Skip to content

Commit c6f9212

Browse files
rcschrgrcschrg
committed
Initial converted project.
0 parents  commit c6f9212

59 files changed

Lines changed: 6529 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Build and deploy docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.11"
28+
cache: pip
29+
30+
- name: Install dependencies
31+
run: pip install -e ".[docs]"
32+
33+
- name: Build docs
34+
run: make -C docs html
35+
36+
- name: Upload pages artifact
37+
uses: actions/upload-pages-artifact@v3
38+
with:
39+
path: docs/build/html
40+
41+
deploy:
42+
needs: build
43+
runs-on: ubuntu-latest
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
steps:
48+
- name: Deploy to GitHub Pages
49+
id: deployment
50+
uses: actions/deploy-pages@v4

‎.github/workflows/publish.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
publish:
12+
runs-on: ubuntu-latest
13+
environment: pypi
14+
permissions:
15+
id-token: write # required for trusted publishing
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.11"
23+
24+
- name: Install build deps
25+
run: pip install build
26+
27+
- name: Run tests
28+
run: |
29+
pip install -e ".[dev]"
30+
pytest
31+
32+
- name: Build package
33+
run: python -m build
34+
35+
- name: Publish to PyPI
36+
uses: pypa/gh-action-pypi-publish@release/v1

‎.github/workflows/test.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- development
8+
pull_request:
9+
types: [opened, synchronize, reopened]
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
test-linux:
16+
runs-on: ubuntu-latest
17+
strategy:
18+
fail-fast: false
19+
matrix:
20+
python-version: ["3.10", "3.11", "3.12", "3.13"]
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Set up Python ${{ matrix.python-version }}
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: ${{ matrix.python-version }}
28+
cache: pip
29+
30+
- name: Install dependencies
31+
run: |
32+
pip install -e ".[dev,docs]"
33+
pip install ruff coverage pytest-cov
34+
35+
- name: Lint with ruff
36+
run: |
37+
ruff check .
38+
ruff format --check .
39+
40+
- name: Test + coverage
41+
run: |
42+
pytest --cov=distributed_resource_optimization --cov-report=xml
43+
44+
- name: Upload coverage
45+
uses: codecov/codecov-action@v5
46+
with:
47+
token: ${{ secrets.CODECOV_TOKEN }}
48+
fail_ci_if_error: false
49+
50+
test-mac:
51+
runs-on: macos-latest
52+
strategy:
53+
fail-fast: false
54+
matrix:
55+
python-version: ["3.11", "3.13"]
56+
steps:
57+
- uses: actions/checkout@v4
58+
59+
- name: Set up Python ${{ matrix.python-version }}
60+
uses: actions/setup-python@v5
61+
with:
62+
python-version: ${{ matrix.python-version }}
63+
cache: pip
64+
65+
- name: Install dependencies
66+
run: pip install -e ".[dev]"
67+
68+
- name: Run tests
69+
run: pytest

‎.gitignore‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*.egg-info/
5+
dist/
6+
build/
7+
.eggs/
8+
*.egg
9+
10+
# Virtual environments
11+
venv/
12+
.venv/
13+
env/
14+
15+
# Testing and coverage
16+
.pytest_cache/
17+
.coverage
18+
coverage.xml
19+
htmlcov/
20+
21+
# Sphinx docs
22+
docs/build/
23+
24+
# IDEs
25+
.vscode/
26+
.idea/
27+
*.swp
28+
29+
# OS
30+
.DS_Store
31+
Thumbs.db
32+
33+
# Jupyter
34+
.ipynb_checkpoints/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Rico Schrage, Carl von Ossietzky Universität Oldenburg
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
<p align="center">
2+
<img src="docs/source/_static/logo.svg" width="200" alt="distributed-resource-optimization logo" />
3+
</p>
4+
5+
<p align="center">
6+
<a href="https://github.com/Digitalized-Energy-Systems/mango-optimization/actions/workflows/test.yml">
7+
<img src="https://github.com/Digitalized-Energy-Systems/mango-optimization/actions/workflows/test.yml/badge.svg" alt="Tests" />
8+
</a>
9+
<a href="https://codecov.io/gh/Digitalized-Energy-Systems/mango-optimization">
10+
<img src="https://codecov.io/gh/Digitalized-Energy-Systems/mango-optimization/branch/main/graph/badge.svg" alt="Coverage" />
11+
</a>
12+
<img src="https://img.shields.io/badge/lifecycle-experimental-blue.svg" alt="lifecycle" />
13+
<a href="https://github.com/Digitalized-Energy-Systems/mango-optimization/blob/main/LICENSE">
14+
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" />
15+
</a>
16+
<a href="https://pypi.org/project/distributed-resource-optimization/">
17+
<img src="https://img.shields.io/pypi/v/distributed-resource-optimization.svg" alt="PyPI" />
18+
</a>
19+
</p>
20+
21+
# Distributed Resource Optimization
22+
23+
A Python package providing distributed optimization algorithms for coordinating flexible
24+
resources. Algorithms are implemented independently of any particular communication
25+
backend — a pluggable *carrier* abstraction lets you run the same algorithm code in a
26+
single asyncio process or across a real network via [mango-agents](https://github.com/OFFIS-DAI/mango).
27+
28+
Three algorithm families are available:
29+
30+
| Algorithm | Problem type | Coordination |
31+
|-----------|-------------|--------------|
32+
| **ADMM Sharing** | Continuous resource allocation, sum-to-target | Coordinator required |
33+
| **ADMM Consensus** | Agents converge to a shared target vector | Coordinator required |
34+
| **COHDA** | Combinatorial schedule selection, weighted L1 target | Fully distributed |
35+
| **Averaging Consensus** | Distributed averaging with optional gradient terms | Fully distributed |
36+
37+
Two carriers are included:
38+
39+
| Carrier | When to use |
40+
|---------|-------------|
41+
| **SimpleCarrier** | In-process asyncio simulation — zero overhead, ideal for prototyping and testing |
42+
| **MangoCarrier** | Networked multi-agent deployments via mango-agents |
43+
44+
> **Note:** the package is still experimental. API may change between minor versions.
45+
46+
---
47+
48+
## Installation
49+
50+
```bash
51+
pip install distributed-resource-optimization
52+
```
53+
54+
For networked deployments with [mango-agents](https://github.com/OFFIS-DAI/mango):
55+
56+
```bash
57+
pip install "distributed-resource-optimization[mango]"
58+
```
59+
60+
For development:
61+
62+
```bash
63+
git clone https://github.com/Digitalized-Energy-Systems/mango-optimization
64+
cd mango-optimization
65+
pip install -e ".[dev,docs]"
66+
```
67+
68+
---
69+
70+
## Quick Start
71+
72+
### ADMM Sharing — flexible resource coordination
73+
74+
Three resources must collectively match a power target. The sharing ADMM distributes the
75+
load optimally:
76+
77+
```python
78+
import asyncio
79+
from distributed_resource_optimization import (
80+
create_admm_flex_actor_one_to_many,
81+
create_sharing_target_distance_admm_coordinator,
82+
create_admm_sharing_data,
83+
create_admm_start,
84+
start_coordinated_optimization,
85+
)
86+
87+
async def main():
88+
# Three resources: 10 kW, 15 kW, 10 kW input capacities
89+
# Efficiency vectors map input to three output types
90+
flex1 = create_admm_flex_actor_one_to_many(10, [0.1, 0.5, -1.0])
91+
flex2 = create_admm_flex_actor_one_to_many(15, [0.1, 0.5, -1.0])
92+
flex3 = create_admm_flex_actor_one_to_many(10, [-1.0, 0.0, 1.0])
93+
94+
# Target combined output [-4, 0, 6] with first sector weighted x5
95+
coordinator = create_sharing_target_distance_admm_coordinator()
96+
start = create_admm_start(create_admm_sharing_data([-4, 0, 6], [5, 1, 1]))
97+
98+
await start_coordinated_optimization([flex1, flex2, flex3], coordinator, start)
99+
100+
print(flex1.x) # optimal output for resource 1
101+
print(flex2.x) # optimal output for resource 2
102+
print(flex3.x) # optimal output for resource 3
103+
104+
asyncio.run(main())
105+
```
106+
107+
### COHDA — combinatorial schedule coordination
108+
109+
Each participant selects exactly one schedule from a discrete set; COHDA minimises the
110+
L1 distance of the aggregate to a target:
111+
112+
```python
113+
import asyncio
114+
from distributed_resource_optimization import (
115+
create_cohda_participant,
116+
create_cohda_start_message,
117+
start_distributed_optimization,
118+
)
119+
120+
async def main():
121+
actor1 = create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]])
122+
actor2 = create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]])
123+
124+
start = create_cohda_start_message([1.2, 2.0, 3.0])
125+
await start_distributed_optimization([actor1, actor2], start)
126+
127+
print(actor1.memory.solution_candidate.schedules.sum(axis=0))
128+
129+
asyncio.run(main())
130+
```
131+
132+
### Using SimpleCarrier directly
133+
134+
For full control over message flow, create the container and carriers yourself:
135+
136+
```python
137+
import asyncio
138+
from distributed_resource_optimization import (
139+
ActorContainer, SimpleCarrier, cid,
140+
create_cohda_participant, create_cohda_start_message,
141+
)
142+
143+
async def main():
144+
container = ActorContainer()
145+
c1 = SimpleCarrier(container, create_cohda_participant(1, [[0.0, 1, 2], [1, 2, 3]]))
146+
c2 = SimpleCarrier(container, create_cohda_participant(2, [[0.0, 1, 2], [1, 2, 3]]))
147+
148+
start = create_cohda_start_message([1.2, 2.0, 3.0])
149+
c1.send_to_other(start, cid(c2))
150+
await container.done_event.wait()
151+
152+
asyncio.run(main())
153+
```
154+
155+
---
156+
157+
## Documentation
158+
159+
Full documentation including algorithm background, tutorials, and API reference is available at:
160+
161+
**https://digitalized-energy-systems.github.io/mango-optimization/**
162+
163+
---
164+
165+
## Contributing
166+
167+
Contributions are welcome. Please open an issue or pull request on
168+
[GitHub](https://github.com/Digitalized-Energy-Systems/mango-optimization).
169+
170+
---
171+
172+
## License
173+
174+
[MIT](LICENSE)

0 commit comments

Comments
 (0)