pymaro

Multi-Agent Resource Optimization (MARO) platform is an instance of Reinforcement Learning as a Service (RaaS) for real-world resource optimization problems.

https://github.com/microsoft/maro

Science Score: 51.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
○
.zenodo.json file
○
DOI references
✓
Academic publication links
Links to: arxiv.org
✓
Committers with academic emails
2 of 30 committers (6.7%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (9.8%) to scientific vocabulary

Keywords

agent citi-bike docker finance inventory-management logistics maro multi-agent multi-agent-reinforcement-learning operations-research raas reinforcement-learning resource-optimization rl-algorithms simulator transportation

Keywords from Contributors

transformer large-language-model cameratrap ai-system embedded interactive cryptocurrencies mesh interpretability profiles

Last synced: 4 months ago · JSON representation ·

Repository

Multi-Agent Resource Optimization (MARO) platform is an instance of Reinforcement Learning as a Service (RaaS) for real-world resource optimization problems.

Basic Info

Host: GitHub
Owner: microsoft
License: mit
Language: Python
Default Branch: master
Homepage: https://maro.readthedocs.io/en/latest/
Size: 110 MB

Statistics

Stars: 892
Watchers: 27
Forks: 161
Open Issues: 23
Releases: 21

Topics

Created about 6 years ago · Last pushed 9 months ago

Metadata Files

Readme Changelog Contributing License Code of conduct Citation Security

README.md

Multi-Agent Resource Optimization (MARO) platform is an instance of Reinforcement learning as a Service (RaaS) for real-world resource optimization. It can be applied to many important industrial domains, such as container inventory management in logistics, bike repositioning in transportation, virtual machine provisioning in data centers, and asset management in finance. Besides Reinforcement Learning (RL), it also supports other planning/decision mechanisms, such as Operations Research.

Key Components of MARO:

Simulation toolkit: it provides some predefined scenarios, and the reusable wheels for building new scenarios.
RL toolkit: it provides a full-stack abstraction for RL, such as agent manager, agent, RL algorithms, learner, actor, and various shapers.
Distributed toolkit: it provides distributed communication components, interface of user-defined functions for message auto-handling, cluster provision, and job orchestration.

MARO Key Components

| File/folder | Description | | ----------- | ------------------------------------------------------------------------------------------------- | | maro | MARO source code. | | docs | MARO docs, it is host on readthedocs. | | examples | Showcase of MARO. | | notebooks | MARO quick-start notebooks. |

Try MARO playground to have a quick experience.

Install MARO from PyPI

Notes: The CLI commands (including the visualization tool) are not included in pymaro package. To enable these support, you need to install from source.

Mac OS / Linux

sh pip install pymaro

Windows

```powershell # Install torch first, if you don't have one. pip install torch===1.6.0 torchvision===0.7.0 -f https://download.pytorch.org/whl/torch_stable.html

pip install pymaro ```

Install MARO from Source

Notes: Install from source if you want to use the CLI commands (including the visualization tool).

Prerequisites
- C++ Compiler
- Linux or Mac OS X: gcc
- Windows: Build Tools for Visual Studio 2017
Enable Virtual Environment
- Mac OS / Linux
```sh

If your environment is not clean, create a virtual environment firstly.

python -m venv marovenv source ./marovenv/bin/activate ``` - Windows

```powershell

If your environment is not clean, create a virtual environment firstly.

python -m venv maro_venv

You may need this for SecurityError in PowerShell.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

Activate the virtual environment.

.\maro_venv\Scripts\activate ```
Install MARO

sh # Git Clone the whole source code. git clone https://github.com/microsoft/maro.git

Mac OS / Linux

```sh

Install MARO from source.

bash scripts/install_maro.sh; pip install -r ./requirements.dev.txt; ```
Windows

```powershell

Install MARO from source.

.\scripts\install_maro.bat; pip install -r ./requirements.dev.txt; ```
- Notes: If your package is not found, remember to set your PYTHONPATH
Mac OS / Linux

sh export PYTHONPATH=PATH-TO-MARO

Windows

powershell $Env:PYTHONPATH=PATH-TO-MARO

Quick Example

```python from maro.simulator import Env

env = Env(scenario="cim", topology="toy.5pssdddl0.0", start_tick=0, durations=100)

metrics, decisionevent, isdone = env.step(None)

while not isdone: metrics, decisionevent, is_done = env.step(None)

print(f"environment metrics: {env.metrics}")

```

Environment Visualization

```sh

Enable environment dump feature, when initializing the environment instance

env = Env(scenario="cim", topology="toy.5pssdddl0.0", starttick=0, durations=100, options={"enable-dump-snapshot": "./dumpdata"})

Inspect environment with the dump data

maro inspector dashboard --sourcepath ./dumpdata/YOURSNAPSHOTDUMP_FOLDER ```

Show Cases

Case I - Container Inventory Management
Case II - Citi Bike

Run Playground

Pull from Docker Hub

```sh # Pull the docker image from docker hub docker pull maro2020/playground

# Run playground container. # Redis commander (GUI for redis) -> http://127.0.0.1:40009 # Jupyter lab with maro -> http://127.0.0.1:40010 docker run -p 40009:40009 -p 40010:40010 maro2020/playground ```

Build from source
- Mac OS / Linux
```sh

Build playground image.

bash ./scripts/build_playground.sh

Run playground container.

Redis commander (GUI for redis) -> http://127.0.0.1:40009

Jupyter lab with maro -> http://127.0.0.1:40010

docker run -p 40009:40009 -p 40010:40010 maro2020/playground ``` - Windows

```powershell

Build playground image.

.\scripts\build_playground.bat

Run playground container.

Redis commander (GUI for redis) -> http://127.0.0.1:40009

Jupyter lab with maro -> http://127.0.0.1:40010

docker run -p 40009:40009 -p 40010:40010 maro2020/playground ```

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Related News

MSRA Top-10 Hack-Techs in 2021

Open Source Platform MARO: Anywhere Door for Resource Optimization

AI from "Point" to "Surface"

Cite Us

License

Licensed under the MIT License.

Owner

Name: Microsoft
Login: microsoft
Kind: organization
Email: opensource@microsoft.com
Location: Redmond, WA

Website: https://opensource.microsoft.com
Twitter: OpenAtMicrosoft
Repositories: 7,257
Profile: https://github.com/microsoft

Open source projects and samples from Microsoft

Citation (CITATION)

@misc{MARO_MSRA
title = {MARO: A Multi-Agent Resource Optimization Platform},
author = {Arthur Jiang, Jia Zhang, Pingchao Yu, Lyuchun Huang, Yang Qiu, Jinyu Wang, Wenlei Shi, Kaiqi Li, Zhanyu Wang, Chengruidong Zhang, Tianyi Sun, Miaoran Chen, Kuanwei Yu, Xinran Wei, Michael Li, Ning Shang, Qiwei Meng, Shan Li, Jiang Bian, Biao Cheng, Tie-Yan Liu},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
url = {https://github.com/microsoft/maro}
}

GitHub Events

Total

Watch event: 96
Push event: 2
Fork event: 8

Last Year

Watch event: 96
Push event: 2
Fork event: 8

Committers

Last synced: 10 months ago

All Time

Total Commits: 490
Total Committers: 30
Avg Commits per committer: 16.333
Development Distribution Score (DDS): 0.741

Past Year

Commits: 0
Committers: 0
Avg Commits per committer: 0.0
Development Distribution Score (DDS): 0.0

Top Committers

Name	Email	Commits
Arthur Jiang	A**g@g**m	127
Arthur Jiang	s**n@m**m	63
Jinyu-W	5****W	63
ysqyang	y**g@g**m	54
Jinyu Wang	W**u@m**m	32
Chaos Yu	c**u@g**m	25
Huoran Li	h**i@m**m	12
kaiqli	5****i	11
dependabot[bot]	4****]	10
Meroy Chen	3****9	10
Chaos Yu	v**u@m**m	10
Romic Huang	r**d@g**m	10
Kuan Wei Yu	v**u@m**m	8
Kuan Wei Yu	7****i	8
zhanyu wang	p**1@1**m	7
Jinyu Wang	w**u@m**m	6
zhanyu	v**n@m**m	5
Microsoft Open Source	m****e	4
Kaiqi Li (Pactera)	v**i@m**m	4
MicrosoftHam	7****m	3
Michael Li	m**0@h**m	3
v-zhache	v**e@m**m	3
Jeremy Reynolds	j**s@m**m	2
slowy07	s**y@g**m	2
yourmoonlight	f**t@g**m	2
ysqyang	v**i@m**m	2
solosilence	a**s@g**m	1
microsoft-github-operations[bot]	5****]	1
Jinyu Wang	j**u@R**t	1
liuaj	4****s	1

Committer Domains (Top 20 + Academic)

microsoft.com: 11 rl4inv.l1ea1prscrcu1p4sa0eapum5vc.bx.internal.cloudapp.net: 1 163.com: 1

Issues and Pull Requests

Last synced: 5 months ago

All Time

Total issues: 11
Total pull requests: 101
Average time to close issues: 2 months
Average time to close pull requests: about 1 month
Total issue authors: 7
Total pull request authors: 13
Average comments per issue: 1.45
Average comments per pull request: 0.63
Merged pull requests: 69
Bot issues: 0
Bot pull requests: 8

Past Year

Issues: 0
Pull requests: 0
Average time to close issues: N/A
Average time to close pull requests: N/A
Issue authors: 0
Pull request authors: 0
Average comments per issue: 0
Average comments per pull request: 0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

yangboz (4)
hanyong-max (2)
QiAnXinCodeSafe (1)
lihuoran (1)
shuo-y (1)
Ahmedest61 (1)
theseusyang1 (1)

Pull Request Authors

lihuoran (36)
Jinyu-W (30)
dependabot[bot] (8)
ShangYizhan (5)
v-heli (5)
VictorYXL (5)
zhawan (3)
chaosddp (3)
YizhanShang (1)
ysqyang (1)
yangboz (1)
J-shang (1)
wesley-stone (1)

Top Labels

Issue Labels

🐛 bug (5) 💡 feature request (1) 📚 doc (1)

Pull Request Labels

dependencies (8) in progress (6) v0.2 (2) finance (2) cim (1) supply chain (1)

Packages

Total packages: 1
Total downloads:
- pypi 186 last-month

Total dependent packages: 0
Total dependent repositories: 5
Total versions: 26
Total maintainers: 2

pypi.org: pymaro

MARO Python Package

Homepage: https://github.com/microsoft/maro
Documentation: https://pymaro.readthedocs.io/
License: MIT License
Latest release: 0.3.2a4
published about 2 years ago

Versions: 26
Dependent Packages: 0
Dependent Repositories: 5
Downloads: 186 Last month

Rankings

Stargazers count: 2.3%

Forks count: 4.0%

Average: 6.3%

Dependent repos count: 6.7%

Dependent packages count: 7.3%

Downloads: 11.2%

Maintainers (2)

ArthurJiang Jinyu-W

Last synced: 4 months ago

Dependencies

docs/requirements.docs.txt pypi

Sphinx ==3.1.2
pymaro *
recommonmark ==0.6.0
sphinx-book-theme ==0.0.36
sphinx-copybutton ==0.3.0
sphinx-markdown-tables ==0.0.15
sphinx-rtd-theme ==0.5.0

examples/requirements.ex.txt pypi

PuLP ==2.1

maro/cli/inspector/requirements.inspector.txt pypi

altair ==4.1.0
streamlit ==0.69.1
tqdm ==4.51.0

maro/cli/maro_real_time_vis/back_end/vis_app/Pipfile pypi

pylint * develop
gunicorn >=19.7.1
numpy *

maro/cli/maro_real_time_vis/back_end/vis_app/Pipfile.lock pypi

astroid ==2.5.1 develop
isort ==5.8.0 develop
lazy-object-proxy ==1.5.2 develop
mccabe ==0.6.1 develop
pylint ==2.2.2 develop
typed-ast ==1.4.2 develop
wrapt ==1.12.1 develop
gunicorn ==19.9.0
jinja2 ==2.11.3
markupsafe ==1.1.1
numpy ==1.15.4

maro/cli/maro_real_time_vis/back_end/vis_app/requirements.txt pypi

flask ==1.1.2
flask-cors ==3.0.10
gunicorn ==20.0.4
numpy <1.20.0
pandas ==0.25.3
pyyaml ==5.4
requests ==2.25.1

maro/cli/utils/web_terminal/requirements.txt pypi

click >=7.0
flask >=1.0.2
flask-socketio >=3.3.1
itsdangerous >=1.1.0
jinja2 >=2.10
markupsafe >=1.1.1
python-engineio >=3.4.3
python-socketio >=3.1.2
six >=1.12.0
werkzeug >=0.14.1

maro/requirements.build.txt pypi

Cython >=0.29.14
altair >=4.1.0
numpy <1.20.0
pyjwt *
streamlit >=0.69.1
tqdm >=4.51.0

notebooks/requirements.nb.txt pypi

autopep8 ==1.4.4
ipython ==7.16.3
ipython-genutils ==0.2.0
isort ==4.3.21
jupyter ==1.0.0
jupyter-client *
jupyter-console *
jupyter-contrib-core *
jupyter-contrib-nbextensions *
jupyter-core *
jupyter-highlight-selected-word *
jupyter-latex-envs *
jupyter-nbextensions-configurator *
jupyterlab *
jupyterlab-server *
jupyterthemes *
matplotlib ==3.1.2
numba ==0.46.0
numpy <1.20.0
pandas ==0.25.3
seaborn ==0.9.0
shap ==0.32.1

requirements.dev.txt pypi

Cython ==0.29.14 development
PyJWT ==2.4.0 development
PyYAML ==5.4.1 development
add-trailing-comma * development
altair ==4.1.0 development
aria2p ==0.9.1 development
astroid ==2.3.3 development
azure-identity * development
azure-mgmt-authorization * development
azure-mgmt-containerservice * development
azure-mgmt-resource * development
azure-mgmt-storage * development
azure-storage-file-share * development
black ==22.3.0 development
certifi ==2019.9.11 development
cryptography ==36.0.1 development
cycler ==0.10.0 development
deepdiff ==5.7.0 development
docker * development
editorconfig-checker ==2.4.0 development
flake8 ==4.0.1 development
flask ==1.1.2 development
flask-cors ==3.0.10 development
flask_cors ==3.0.10 development
flask_socketio ==5.2.0 development
flloat ==0.3.0 development
geopy ==2.0.0 development
guppy3 ==3.0.9 development
holidays ==0.10.3 development
isort ==4.3.21 development
jinja2 ==2.11.3 development
kiwisolver ==1.1.0 development
kubernetes ==21.7.0 development
lazy-object-proxy ==1.4.3 development
markupsafe ==2.0.1 development
matplotlib ==3.5.2 development
mccabe ==0.6.1 development
networkx ==2.4 development
numpy <1.20.0 development
palettable ==3.3.0 development
pandas ==0.25.3 development
pre-commit ==2.19.0 development
prompt_toolkit ==2.0.10 development
psutil ==5.8.0 development
ptvsd ==4.3.2 development
pulp ==2.6.0 development
pyaml ==20.4.0 development
pyparsing ==2.4.5 development
python-dateutil ==2.8.1 development
pyzmq ==19.0.2 development
recommonmark * development
redis ==3.5.3 development
requests ==2.25.1 development
scipy ==1.7.0 development
setuptools ==58.0.4 development
six ==1.13.0 development
sphinx ==1.8.6 development
sphinx_rtd_theme ==1.0.0 development
streamlit ==0.69.1 development
stringcase ==1.2.0 development
tabulate ==0.8.5 development
termgraph ==0.5.3 development
torch ==1.6.0 development
torchsummary ==1.5.1 development
tqdm ==4.51.0 development
urllib3 ==1.26.5 development
wrapt ==1.11.2 development
zmq ==0.0.0 development

setup.py pypi

PyYAML <5.5.0
TODO *
azure-storage-blob <12.9.0
azure-storage-common *
deepdiff >=5.2.2
geopy >=2.0.0
holidays >=0.10.3
kubernetes >=12.0.1
numpy <1.20.0
pandas <1.2
paramiko >=2.7.2
prompt_toolkit <3.1.0
psutil <5.9.0
pyaml >=20.4.0
pyzmq <22.1.0
redis >=3.5.3
requests <=2.26.0
scipy <=1.7.0
stringcase >=1.2.0
torch <1.8.0

tests/requirements.test.txt pypi

PyYAML <5.5.0 test
aria2p ==0.9.1 test
azure-storage-blob <12.9.0 test
azure-storage-common * test
coverage * test
deepdiff >=5.2.2 test
geopy * test
holidays >=0.10.3 test
influxdb * test
kubernetes >=12.0.1 test
matplotlib >=3.1.2 test
numpy <1.20.0 test
pandas <1.2 test
paramiko >=2.7.2 test
psutil <5.9.0 test
pyaml >=20.4.0 test
pytest * test
pytz ==2019.3 test
pyzmq <22.1.0 test
redis >=3.5.3 test
requests <=2.26.0 test
termgraph * test
torch <1.8.0 test

.github/workflows/build_wheel.yml actions

RalfG/python-wheels-manylinux-build v0.3.1-manylinux2010_x86_64 composite
actions/checkout v2 composite
actions/setup-python v2 composite
actions/upload-artifact v2 composite

.github/workflows/deploy_docker_image.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite

.github/workflows/deploy_gh_pages.yml actions

JamesIves/github-pages-deploy-action 3.6.1 composite
actions/checkout v2 composite
actions/setup-python v2 composite

.github/workflows/lint.yml actions

actions/checkout v2 composite
github/super-linter latest composite

.github/workflows/test.yml actions

actions/checkout v2 composite
actions/setup-python v2 composite
codecov/codecov-action v1 composite

.github/workflows/test_with_cli.yml actions

Azure/login v1.1 composite
actions/checkout v2 composite
actions/setup-python v2 composite

.github/workflows/vulnerability_scan.yml actions

actions/checkout v2 composite
github/codeql-action/analyze v1 composite
github/codeql-action/autobuild v1 composite
github/codeql-action/init v1 composite

maro/cli/maro_real_time_vis/back_end/nginx/Dockerfile docker

nginx 1.15.8 build

maro/cli/maro_real_time_vis/back_end/vis_app/Dockerfile docker

python 3.6.7 build

maro/streamit/server/Dockerfile docker

node 15-alpine build

maro/streamit/server/docker-compose.yml docker

nginx 1.19.6-alpine
questdb/questdb latest

pymaro

Science Score: 51.0%

Keywords

Keywords from Contributors

Basic Info

Statistics

Topics

Metadata Files

Contents

Install MARO from PyPI

Install MARO from Source

If your environment is not clean, create a virtual environment firstly.

If your environment is not clean, create a virtual environment firstly.

You may need this for SecurityError in PowerShell.

Activate the virtual environment.

Install MARO from source.

Install MARO from source.

Quick Example

Enable environment dump feature, when initializing the environment instance

Inspect environment with the dump data

Show Cases

Run Playground

Build playground image.

Run playground container.

Redis commander (GUI for redis) -> http://127.0.0.1:40009

Jupyter lab with maro -> http://127.0.0.1:40010

Build playground image.

Run playground container.

Redis commander (GUI for redis) -> http://127.0.0.1:40009

Jupyter lab with maro -> http://127.0.0.1:40010

Contributing

Related Papers

Related News

License

Citation (CITATION)

GitHub Events

Total

Last Year

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: pymaro

Rankings

Maintainers (2)

Dependencies