.. image:: https://img.shields.io/pypi/l/pymaro
:target: https://github.com/microsoft/maro/blob/master/LICENSE
:alt: License
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/platform.svg
:target: https://pypi.org/project/pymaro/
:alt: Platform
.. image:: https://img.shields.io/pypi/pyversions/pymaro.svg?logo=python&logoColor=white
:target: https://pypi.org/project/pymaro/#files
:alt: Python Versions
.. image:: https://img.shields.io/github/languages/code-size/microsoft/maro
:target: https://github.com/microsoft/maro
:alt: Code Size
.. image:: https://img.shields.io/docker/image-size/maro2020/maro
:target: https://hub.docker.com/repository/docker/maro2020/maro/tags?page=1
:alt: Docker Size
.. image:: https://img.shields.io/github/issues/microsoft/maro
:target: https://github.com/microsoft/maro/issues
:alt: Issues
.. image:: https://img.shields.io/github/issues-pr/microsoft/maro
:target: https://github.com/microsoft/maro/pulls
:alt: Pull Requests
.. image:: https://img.shields.io/librariesio/github/microsoft/maro
:target: https://libraries.io/pypi/pymaro
:alt: Dependencies
.. image:: https://github.com/microsoft/maro/workflows/test/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3Atest
:alt: test
.. image:: https://github.com/microsoft/maro/workflows/build/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3Abuild
:alt: build
.. image:: https://github.com/microsoft/maro/workflows/docker/badge.svg
:target: https://hub.docker.com/repository/docker/maro2020/maro
:alt: docker
.. image:: https://readthedocs.org/projects/maro/badge/?version=latest
:target: https://maro.readthedocs.io/
:alt: docs
.. image:: https://img.shields.io/pypi/v/pymaro
:target: https://pypi.org/project/pymaro/#files
:alt: PypI Versions
.. image:: https://img.shields.io/pypi/wheel/pymaro
:target: https://pypi.org/project/pymaro/#files
:alt: Wheel
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/citi_bike.svg
:target: https://maro.readthedocs.io/en/latest/scenarios/citi_bike.html
:alt: Citi Bike
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/cim.svg
:target: https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html
:alt: CIM
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/vm_scheduling.svg
:target: https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html
:alt: VM Scheduling
.. image:: https://img.shields.io/gitter/room/microsoft/maro
:target: https://gitter.im/Microsoft/MARO#
:alt: Gitter
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/stack_overflow.svg
:target: https://stackoverflow.com/questions/ask?tags=maro
:alt: Stack Overflow
.. image:: https://img.shields.io/github/release-date-pre/microsoft/maro
:target: https://github.com/microsoft/maro/releases
:alt: Releases
.. image:: https://img.shields.io/github/commits-since/microsoft/maro/latest/master
:target: https://github.com/microsoft/maro/commits/master
:alt: Commits
.. image:: https://github.com/microsoft/maro/workflows/vulnerability%20scan/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3A%22vulnerability+scan%22
:alt: Vulnerability Scan
.. image:: https://github.com/microsoft/maro/workflows/lint/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3Alint
:alt: Lint
.. image:: https://img.shields.io/codecov/c/github/microsoft/maro
:target: https://codecov.io/gh/microsoft/maro
:alt: Coverage
.. image:: https://img.shields.io/pypi/dm/pymaro
:target: https://pypi.org/project/pymaro/#files
:alt: Downloads
.. image:: https://img.shields.io/docker/pulls/maro2020/maro
:target: https://hub.docker.com/repository/docker/maro2020/maro
:alt: Docker Pulls
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/play_with_maro.svg
:target: https://hub.docker.com/r/maro2020/maro
:alt: Play with MARO
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/logo.svg
:target: https://maro.readthedocs.io/en/latest/
:alt: MARO LOGO
================================================================================================================
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/vm_scheduling.svg
:target: https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html
:alt: VM Scheduling
.. image:: https://img.shields.io/gitter/room/microsoft/maro
:target: https://gitter.im/Microsoft/MARO#
:alt: Gitter
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/stack_overflow.svg
:target: https://stackoverflow.com/questions/ask?tags=maro
:alt: Stack Overflow
.. image:: https://img.shields.io/github/release-date-pre/microsoft/maro
:target: https://github.com/microsoft/maro/releases
:alt: Releases
.. image:: https://img.shields.io/github/commits-since/microsoft/maro/latest/master
:target: https://github.com/microsoft/maro/commits/master
:alt: Commits
.. image:: https://github.com/microsoft/maro/workflows/vulnerability%20scan/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3A%22vulnerability+scan%22
:alt: Vulnerability Scan
.. image:: https://github.com/microsoft/maro/workflows/lint/badge.svg
:target: https://github.com/microsoft/maro/actions?query=workflow%3Alint
:alt: Lint
.. image:: https://img.shields.io/codecov/c/github/microsoft/maro
:target: https://codecov.io/gh/microsoft/maro
:alt: Coverage
.. image:: https://img.shields.io/pypi/dm/pymaro
:target: https://pypi.org/project/pymaro/#files
:alt: Downloads
.. image:: https://img.shields.io/docker/pulls/maro2020/maro
:target: https://hub.docker.com/repository/docker/maro2020/maro
:alt: Docker Pulls
.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/play_with_maro.svg
:target: https://hub.docker.com/r/maro2020/maro
:alt: Play with MARO
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/logo.svg
:target: https://maro.readthedocs.io/en/latest/
:alt: MARO LOGO
================================================================================================================
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 <https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html>`_
in logistics, `bike repositioning <https://maro.readthedocs.io/en/latest/scenarios/citi_bike.html>`_
in transportation, `virtual machine <https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html>`_ provisioning in data centers, and asset management in finance. Besides
`Reinforcement Learning <https://www.andrew.cmu.edu/course/10-703/textbook/BartoSutton.pdf>`_ (RL),
it also supports other planning/decision mechanisms, such as
`Operations Research <https://en.wikipedia.org/wiki/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.
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/maro_overview.svg
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/maro_overview.svg
:alt: MARO Key Components
Contents
--------
.. list-table::
:header-rows: 1
* - File/folder
- Description
* - ``maro``
- MARO source code.
* - ``docs``
- MARO docs, it is host on `readthedocs <https://maro.readthedocs.io/en/latest/>`_.
* - ``examples``
- Showcase of MARO.
* - ``notebooks``
- MARO quick-start notebooks.
*Try `MARO playground <#run-playground>`_ to have a quick experience.*
Install MARO from `PyPI <https://pypi.org/project/pymaro/#files>`_
----------------------------------------------------------------------
*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
.. code-block:: sh
pip install pymaro
*
Windows
.. code-block:: 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 <https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15>`_
*
Enable Virtual Environment
*
Mac OS / Linux
.. code-block:: sh
# If your environment is not clean, create a virtual environment firstly.
python -m venv maro_venv
source ./maro_venv/bin/activate
*
Windows
.. code-block:: 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
.. code-block:: sh
# Git Clone the whole source code.
git clone https://github.com/microsoft/maro.git
*
Mac OS / Linux
.. code-block:: sh
# Install MARO from source.
bash scripts/install_maro.sh
*
Windows
.. code-block:: powershell
# Install MARO from source.
.\scripts\install_maro.bat
*
*Notes: If your package is not found, remember to set your PYTHONPATH*
* Mac OS / Linux
.. code-block:: sh
export PYTHONPATH=PATH-TO-MARO
* Windows
.. code-block:: powershell
$Env:PYTHONPATH=PATH-TO-MARO
Quick Example
-------------
.. code-block:: python
from maro.simulator import Env
env = Env(scenario="cim", topology="toy.5p_ssddd_l0.0", start_tick=0, durations=100)
metrics, decision_event, is_done = env.step(None)
while not is_done:
metrics, decision_event, is_done = env.step(None)
print(f"environment metrics: {env.metrics}")
`Environment Visualization <https://maro.readthedocs.io/en/latest/>`_
-------------------------------------------------------------------------
.. code-block:: sh
# Enable environment dump feature, when initializing the environment instance
env = Env(scenario="cim",
topology="toy.5p_ssddd_l0.0",
start_tick=0,
durations=100,
options={"enable-dump-snapshot": "./dump_data"})
# Inspect environment with the dump data
maro inspector dashboard --source_path ./dump_data/YOUR_SNAPSHOT_DUMP_FOLDER
Show Cases
^^^^^^^^^^
*
Case I - Container Inventory Management
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_inter_epoch.gif
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_inter_epoch.gif
:alt: CIM Inter Epoch
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_intra_epoch_by_ports.gif
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_intra_epoch_by_ports.gif
:alt: CIM Intra Epoch
*
Case II - Citi Bike
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_inter_epoch.gif
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_inter_epoch.gif
:alt: Citi Bike Inter Epoch
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_intra_epoch_by_station.gif
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_intra_epoch_by_station.gif
:alt: Citi Bike Intra Epoch
Run Playground
--------------
*
Pull from `Docker Hub <https://hub.docker.com/r/maro2020/playground>`_
.. code-block:: 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
.. code-block:: 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
.. code-block:: 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 <https://opensource.microsoft.com/codeofconduct/>`_.
For more information see the
`Code of Conduct FAQ <https://opensource.microsoft.com/codeofconduct/faq/>`_
or contact `opencode@microsoft.com <mailto:opencode@microsoft.com>`_
with any additional questions or comments.
Related Papers
--------------
`Container Inventory Management <https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/scenario/cim_vis.gif
:target: https://github.com/microsoft/maro/blob/master/docs/source/images/scenario/cim_vis.gif
:alt: CIM Vis
Wenlei Shi, Xinran Wei, Jia Zhang, Xiaoyuan Ni, Arthur Jiang, Jiang Bian, Tie-Yan Liu. "\ `Cooperative Policy Learning with Pre-trained Heterogeneous Observation Representations <https://arxiv.org/abs/2012.13099>`_\ ". AAMAS 2021
Xihan Li, Jia Zhang, Jiang Bian, Yunhai Tong, Tie-Yan Liu. "\ `A Cooperative Multi-Agent Reinforcement Learning Framework for Resource Balancing in Complex Logistics Network <https://arxiv.org/abs/1903.00714>`_\ ". AAMAS 2019
Related News
------------
`MSRA Top-10 Hack-Techs in 2021 <https://mp.weixin.qq.com/s/Y4kjQq8gKcsEsVadjdwnEQ>`_
`Open Source Platform MARO: Anywhere Door for Resource Optimization <https://mp.weixin.qq.com/s/zXIpgzomLhDWS_YUFmRlEQ>`_
`AI from "Point" to "Surface" <https://mp.weixin.qq.com/s/PggO49wwmS7grTO0nEMgVQ>`_
`Cite Us <https://github.com/microsoft/maro/blob/master/CITATION>`_
---------------------------------------------------------------------
License
-------
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the `MIT <https://github.com/microsoft/maro/blob/master/LICENSE>`_ License.
Raw data
{
"_id": null,
"home_page": "https://github.com/microsoft/maro",
"name": "pymaro",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "citi-bike,inventory-management,operations-research,reinforcement-learning,resource-optimization,simulator",
"author": "MARO Team",
"author_email": "maro-team@microsoft.com",
"download_url": "",
"platform": "Windows",
"description": "\n\n.. image:: https://img.shields.io/pypi/l/pymaro\n :target: https://github.com/microsoft/maro/blob/master/LICENSE\n :alt: License\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/platform.svg\n :target: https://pypi.org/project/pymaro/\n :alt: Platform\n\n\n.. image:: https://img.shields.io/pypi/pyversions/pymaro.svg?logo=python&logoColor=white\n :target: https://pypi.org/project/pymaro/#files\n :alt: Python Versions\n\n\n.. image:: https://img.shields.io/github/languages/code-size/microsoft/maro\n :target: https://github.com/microsoft/maro\n :alt: Code Size\n\n\n.. image:: https://img.shields.io/docker/image-size/maro2020/maro\n :target: https://hub.docker.com/repository/docker/maro2020/maro/tags?page=1\n :alt: Docker Size\n\n\n.. image:: https://img.shields.io/github/issues/microsoft/maro\n :target: https://github.com/microsoft/maro/issues\n :alt: Issues\n\n\n.. image:: https://img.shields.io/github/issues-pr/microsoft/maro\n :target: https://github.com/microsoft/maro/pulls\n :alt: Pull Requests\n\n\n.. image:: https://img.shields.io/librariesio/github/microsoft/maro\n :target: https://libraries.io/pypi/pymaro\n :alt: Dependencies\n\n\n.. image:: https://github.com/microsoft/maro/workflows/test/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3Atest\n :alt: test\n\n\n.. image:: https://github.com/microsoft/maro/workflows/build/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3Abuild\n :alt: build\n\n\n.. image:: https://github.com/microsoft/maro/workflows/docker/badge.svg\n :target: https://hub.docker.com/repository/docker/maro2020/maro\n :alt: docker\n\n\n.. image:: https://readthedocs.org/projects/maro/badge/?version=latest\n :target: https://maro.readthedocs.io/\n :alt: docs\n\n\n.. image:: https://img.shields.io/pypi/v/pymaro\n :target: https://pypi.org/project/pymaro/#files\n :alt: PypI Versions\n\n\n.. image:: https://img.shields.io/pypi/wheel/pymaro\n :target: https://pypi.org/project/pymaro/#files\n :alt: Wheel\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/citi_bike.svg\n :target: https://maro.readthedocs.io/en/latest/scenarios/citi_bike.html\n :alt: Citi Bike\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/cim.svg\n :target: https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html\n :alt: CIM\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/vm_scheduling.svg\n :target: https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html\n :alt: VM Scheduling\n\n\n.. image:: https://img.shields.io/gitter/room/microsoft/maro\n :target: https://gitter.im/Microsoft/MARO#\n :alt: Gitter\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/stack_overflow.svg\n :target: https://stackoverflow.com/questions/ask?tags=maro\n :alt: Stack Overflow\n\n\n.. image:: https://img.shields.io/github/release-date-pre/microsoft/maro\n :target: https://github.com/microsoft/maro/releases\n :alt: Releases\n\n\n.. image:: https://img.shields.io/github/commits-since/microsoft/maro/latest/master\n :target: https://github.com/microsoft/maro/commits/master\n :alt: Commits\n\n\n.. image:: https://github.com/microsoft/maro/workflows/vulnerability%20scan/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3A%22vulnerability+scan%22\n :alt: Vulnerability Scan\n\n\n.. image:: https://github.com/microsoft/maro/workflows/lint/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3Alint\n :alt: Lint\n\n\n.. image:: https://img.shields.io/codecov/c/github/microsoft/maro\n :target: https://codecov.io/gh/microsoft/maro\n :alt: Coverage\n\n\n.. image:: https://img.shields.io/pypi/dm/pymaro\n :target: https://pypi.org/project/pymaro/#files\n :alt: Downloads\n\n\n.. image:: https://img.shields.io/docker/pulls/maro2020/maro\n :target: https://hub.docker.com/repository/docker/maro2020/maro\n :alt: Docker Pulls\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/play_with_maro.svg\n :target: https://hub.docker.com/r/maro2020/maro\n :alt: Play with MARO\n\n\n\n.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/logo.svg\n :target: https://maro.readthedocs.io/en/latest/\n :alt: MARO LOGO\n\n================================================================================================================\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/vm_scheduling.svg\n :target: https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html\n :alt: VM Scheduling\n\n\n.. image:: https://img.shields.io/gitter/room/microsoft/maro\n :target: https://gitter.im/Microsoft/MARO#\n :alt: Gitter\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/stack_overflow.svg\n :target: https://stackoverflow.com/questions/ask?tags=maro\n :alt: Stack Overflow\n\n\n.. image:: https://img.shields.io/github/release-date-pre/microsoft/maro\n :target: https://github.com/microsoft/maro/releases\n :alt: Releases\n\n\n.. image:: https://img.shields.io/github/commits-since/microsoft/maro/latest/master\n :target: https://github.com/microsoft/maro/commits/master\n :alt: Commits\n\n\n.. image:: https://github.com/microsoft/maro/workflows/vulnerability%20scan/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3A%22vulnerability+scan%22\n :alt: Vulnerability Scan\n\n\n.. image:: https://github.com/microsoft/maro/workflows/lint/badge.svg\n :target: https://github.com/microsoft/maro/actions?query=workflow%3Alint\n :alt: Lint\n\n\n.. image:: https://img.shields.io/codecov/c/github/microsoft/maro\n :target: https://codecov.io/gh/microsoft/maro\n :alt: Coverage\n\n\n.. image:: https://img.shields.io/pypi/dm/pymaro\n :target: https://pypi.org/project/pymaro/#files\n :alt: Downloads\n\n\n.. image:: https://img.shields.io/docker/pulls/maro2020/maro\n :target: https://hub.docker.com/repository/docker/maro2020/maro\n :alt: Docker Pulls\n\n\n.. image:: https://raw.githubusercontent.com/microsoft/maro/master/docs/source/images/badges/play_with_maro.svg\n :target: https://hub.docker.com/r/maro2020/maro\n :alt: Play with MARO\n\n\n\n.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/logo.svg\n :target: https://maro.readthedocs.io/en/latest/\n :alt: MARO LOGO\n\n================================================================================================================\n\nMulti-Agent Resource Optimization (MARO) platform is an instance of Reinforcement\nlearning as a Service (RaaS) for real-world resource optimization. It can be\napplied to many important industrial domains, such as `container inventory\nmanagement <https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html>`_\nin logistics, `bike repositioning <https://maro.readthedocs.io/en/latest/scenarios/citi_bike.html>`_\nin transportation, `virtual machine <https://maro.readthedocs.io/en/latest/scenarios/vm_scheduling.html>`_ provisioning in data centers, and asset management in finance. Besides\n`Reinforcement Learning <https://www.andrew.cmu.edu/course/10-703/textbook/BartoSutton.pdf>`_ (RL),\nit also supports other planning/decision mechanisms, such as\n`Operations Research <https://en.wikipedia.org/wiki/Operations_research>`_.\n\nKey Components of MARO:\n\n\n* Simulation toolkit: it provides some predefined scenarios, and the reusable\n wheels for building new scenarios.\n* RL toolkit: it provides a full-stack abstraction for RL, such as agent manager,\n agent, RL algorithms, learner, actor, and various shapers.\n* Distributed toolkit: it provides distributed communication components, interface\n of user-defined functions for message auto-handling, cluster provision, and job orchestration.\n\n\n.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/maro_overview.svg\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/maro_overview.svg\n :alt: MARO Key Components\n\n\nContents\n--------\n\n.. list-table::\n :header-rows: 1\n\n * - File/folder\n - Description\n * - ``maro``\n - MARO source code.\n * - ``docs``\n - MARO docs, it is host on `readthedocs <https://maro.readthedocs.io/en/latest/>`_.\n * - ``examples``\n - Showcase of MARO.\n * - ``notebooks``\n - MARO quick-start notebooks.\n\n\n*Try `MARO playground <#run-playground>`_ to have a quick experience.*\n\nInstall MARO from `PyPI <https://pypi.org/project/pymaro/#files>`_\n----------------------------------------------------------------------\n\n*Notes: The CLI commands (including the visualization tool) are not included in pymaro package. To enable these support, you need to install from source.*\n\n\n*\n Mac OS / Linux\n\n .. code-block:: sh\n\n pip install pymaro\n\n*\n Windows\n\n .. code-block:: powershell\n\n # Install torch first, if you don't have one.\n pip install torch===1.6.0 torchvision===0.7.0 -f https://download.pytorch.org/whl/torch_stable.html\n\n pip install pymaro\n\nInstall MARO from Source\n------------------------\n\n*Notes: Install from source if you want to use the CLI commands (including the visualization tool).*\n\n\n*\n Prerequisites\n\n\n * C++ Compiler\n\n * Linux or Mac OS X: ``gcc``\n * Windows: `Build Tools for Visual Studio 2017 <https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15>`_\n\n*\n Enable Virtual Environment\n\n\n *\n Mac OS / Linux\n\n .. code-block:: sh\n\n # If your environment is not clean, create a virtual environment firstly.\n python -m venv maro_venv\n source ./maro_venv/bin/activate\n\n *\n Windows\n\n .. code-block:: powershell\n\n # If your environment is not clean, create a virtual environment firstly.\n python -m venv maro_venv\n\n # You may need this for SecurityError in PowerShell.\n Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted\n\n # Activate the virtual environment.\n .\\maro_venv\\Scripts\\activate\n\n*\n Install MARO\n\n .. code-block:: sh\n\n # Git Clone the whole source code.\n git clone https://github.com/microsoft/maro.git\n\n\n *\n Mac OS / Linux\n\n .. code-block:: sh\n\n # Install MARO from source.\n bash scripts/install_maro.sh\n\n *\n Windows\n\n .. code-block:: powershell\n\n # Install MARO from source.\n .\\scripts\\install_maro.bat\n\n*\n *Notes: If your package is not found, remember to set your PYTHONPATH*\n\n\n * Mac OS / Linux\n\n .. code-block:: sh\n\n export PYTHONPATH=PATH-TO-MARO\n\n\n * Windows\n\n .. code-block:: powershell\n\n $Env:PYTHONPATH=PATH-TO-MARO\n\nQuick Example\n-------------\n\n.. code-block:: python\n\n from maro.simulator import Env\n\n env = Env(scenario=\"cim\", topology=\"toy.5p_ssddd_l0.0\", start_tick=0, durations=100)\n\n metrics, decision_event, is_done = env.step(None)\n\n while not is_done:\n metrics, decision_event, is_done = env.step(None)\n\n print(f\"environment metrics: {env.metrics}\")\n\n`Environment Visualization <https://maro.readthedocs.io/en/latest/>`_\n-------------------------------------------------------------------------\n\n.. code-block:: sh\n\n # Enable environment dump feature, when initializing the environment instance\n env = Env(scenario=\"cim\",\n topology=\"toy.5p_ssddd_l0.0\",\n start_tick=0,\n durations=100,\n options={\"enable-dump-snapshot\": \"./dump_data\"})\n\n # Inspect environment with the dump data\n maro inspector dashboard --source_path ./dump_data/YOUR_SNAPSHOT_DUMP_FOLDER\n\nShow Cases\n^^^^^^^^^^\n\n\n*\n Case I - Container Inventory Management\n\n .. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_inter_epoch.gif\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_inter_epoch.gif\n :alt: CIM Inter Epoch\n\n\n .. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_intra_epoch_by_ports.gif\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/cim_intra_epoch_by_ports.gif\n :alt: CIM Intra Epoch\n\n\n*\n Case II - Citi Bike\n\n .. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_inter_epoch.gif\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_inter_epoch.gif\n :alt: Citi Bike Inter Epoch\n\n\n .. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_intra_epoch_by_station.gif\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/visualization/dashboard/citi_bike_intra_epoch_by_station.gif\n :alt: Citi Bike Intra Epoch\n\n\nRun Playground\n--------------\n\n\n*\n Pull from `Docker Hub <https://hub.docker.com/r/maro2020/playground>`_\n\n .. code-block:: sh\n\n # Pull the docker image from docker hub\n docker pull maro2020/playground\n\n # Run playground container.\n # Redis commander (GUI for redis) -> http://127.0.0.1:40009\n # Jupyter lab with maro -> http://127.0.0.1:40010\n docker run -p 40009:40009 -p 40010:40010 maro2020/playground\n\n*\n Build from source\n\n\n *\n Mac OS / Linux\n\n .. code-block:: sh\n\n # Build playground image.\n bash ./scripts/build_playground.sh\n\n # Run playground container.\n # Redis commander (GUI for redis) -> http://127.0.0.1:40009\n # Jupyter lab with maro -> http://127.0.0.1:40010\n docker run -p 40009:40009 -p 40010:40010 maro2020/playground\n\n *\n Windows\n\n .. code-block:: powershell\n\n # Build playground image.\n .\\scripts\\build_playground.bat\n\n # Run playground container.\n # Redis commander (GUI for redis) -> http://127.0.0.1:40009\n # Jupyter lab with maro -> http://127.0.0.1:40010\n docker run -p 40009:40009 -p 40010:40010 maro2020/playground\n\nContributing\n------------\n\nThis project welcomes contributions and suggestions. Most contributions require\nyou to agree to a Contributor License Agreement (CLA) declaring that you have\nthe right to, and actually do, grant us the rights to use your contribution. For\ndetails, visit https://cla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether\nyou need to provide a CLA and decorate the PR appropriately (e.g., status check,\ncomment). Simply follow the instructions provided by the bot. You will only need\nto do this once across all repos using our CLA.\n\nThis project has adopted the\n`Microsoft Open Source Code of Conduct <https://opensource.microsoft.com/codeofconduct/>`_.\nFor more information see the\n`Code of Conduct FAQ <https://opensource.microsoft.com/codeofconduct/faq/>`_\nor contact `opencode@microsoft.com <mailto:opencode@microsoft.com>`_\nwith any additional questions or comments.\n\nRelated Papers\n--------------\n\n`Container Inventory Management <https://maro.readthedocs.io/en/latest/scenarios/container_inventory_management.html>`_\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n\n.. image:: https://github.com/microsoft/maro/blob/master/docs/source/images/scenario/cim_vis.gif\n :target: https://github.com/microsoft/maro/blob/master/docs/source/images/scenario/cim_vis.gif\n :alt: CIM Vis\n\n\nWenlei Shi, Xinran Wei, Jia Zhang, Xiaoyuan Ni, Arthur Jiang, Jiang Bian, Tie-Yan Liu. \"\\ `Cooperative Policy Learning with Pre-trained Heterogeneous Observation Representations <https://arxiv.org/abs/2012.13099>`_\\ \". AAMAS 2021\n\nXihan Li, Jia Zhang, Jiang Bian, Yunhai Tong, Tie-Yan Liu. \"\\ `A Cooperative Multi-Agent Reinforcement Learning Framework for Resource Balancing in Complex Logistics Network <https://arxiv.org/abs/1903.00714>`_\\ \". AAMAS 2019\n\nRelated News\n------------\n\n`MSRA Top-10 Hack-Techs in 2021 <https://mp.weixin.qq.com/s/Y4kjQq8gKcsEsVadjdwnEQ>`_\n\n`Open Source Platform MARO: Anywhere Door for Resource Optimization <https://mp.weixin.qq.com/s/zXIpgzomLhDWS_YUFmRlEQ>`_\n\n`AI from \"Point\" to \"Surface\" <https://mp.weixin.qq.com/s/PggO49wwmS7grTO0nEMgVQ>`_\n\n`Cite Us <https://github.com/microsoft/maro/blob/master/CITATION>`_\n---------------------------------------------------------------------\n\nLicense\n-------\n\nCopyright (c) Microsoft Corporation. All rights reserved.\n\nLicensed under the `MIT <https://github.com/microsoft/maro/blob/master/LICENSE>`_ License.\n\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "MARO Python Package",
"version": "0.3.2a4",
"project_urls": {
"Code": "https://github.com/microsoft/maro",
"Documents": "https://maro.readthedocs.io/en/latest",
"Homepage": "https://github.com/microsoft/maro",
"Issues": "https://github.com/microsoft/maro/issues"
},
"split_keywords": [
"citi-bike",
"inventory-management",
"operations-research",
"reinforcement-learning",
"resource-optimization",
"simulator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "770584eef41c85e69c70395fb0436a50f335e3725e68c1f872821c9c175ef108",
"md5": "deb518e2d119375946c9f6408cdbb7ea",
"sha256": "e1e1915d43b6e4c73a62632ea4a796b3c653547d27a19cb117886c6eb3f0bb7b"
},
"downloads": -1,
"filename": "pymaro-0.3.2a4-cp39-cp39-macosx_11_0_x86_64.whl",
"has_sig": false,
"md5_digest": "deb518e2d119375946c9f6408cdbb7ea",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.7",
"size": 1239579,
"upload_time": "2023-10-27T06:22:55",
"upload_time_iso_8601": "2023-10-27T06:22:55.897721Z",
"url": "https://files.pythonhosted.org/packages/77/05/84eef41c85e69c70395fb0436a50f335e3725e68c1f872821c9c175ef108/pymaro-0.3.2a4-cp39-cp39-macosx_11_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 06:22:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "microsoft",
"github_project": "maro",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymaro"
}
JSON
