Metadata-Version: 2.5
Name: MnMS
Version: 1.1.0
Summary: Agent-based Multimodal Urban Moblity Simulator resulting from the ERC MAGnUM project
Project-URL: Repository, https://github.com/EMob-Lab/MnMS
Project-URL: Issues, https://github.com/EMob-Lab/MnMS/issues
Maintainer-email: Cécile Becarie <cecile.becarie@univ-eiffel.fr>
License-Expression: LGPL-3.0-only
License-File: LICENSE
Keywords: traffic,urban-mobility
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: dill>=0.4
Requires-Dist: hipop~=2.0
Requires-Dist: jsonpickle>=4.1
Requires-Dist: matplotlib>=3.10
Requires-Dist: numpy>=2.2
Requires-Dist: pandas>=2.3
Requires-Dist: scipy>=1.15
Requires-Dist: seaborn>=0.13
Requires-Dist: shapely>=2.1
Description-Content-Type: text/markdown

# MnMS :candy:

MnMS (**M**ultimodal **N**etwork **M**odelling and **S**imulation) is a multimodal dynamic traffic simulator
designed for a large urban scale. It results from all research activities of the ERC MAGnUM project.
Further extensions related to on-demand mobility have been developed with the DIT4TraM project.

MnMS is an agent-based dynamic simulator for urban mobility. Travelers make mode and route choices considering
all multimodal options on the city transportation network, including traditional modes,
such as personal cars or public transportation, and new mobility services, such as ride-hailing,
ride-sharing, or vehicle sharing.
Vehicles motion is governed by regional multimodal MFD (Macroscopic Fundamental Diagram) curves,
so all vehicles of the same type (car, bus, etc.) share the same speed within a specific region at a given time.
The adoption of this traffic flow modelling framework makes it possible to address at large urban scale
timely research topics such as the management of new mobility services (operation, optimization, regulation),
the design of regulatory policies taking into account the multiple stakeholders setting
of today's urban transportation system, and beyond!


## Installation

### From package manager

This is the recommended (and most simple!) method to install MnMS:
just download it from [PyPI](https://pypi.org/project/MnMS/).

```shell
pip install mnms
```


### From sources

1. Download the latest MnMS sources from https://github.com/EMob-Lab/MnMS/archive/refs/heads/main.zip
   or by cloning the git repository:
   ```shell
   git clone https://github.com/EMob-Lab/MnMS.git
   ```

2. From the root directory of the MnMS sources:
   ```shell
   pip install .

   # Optionally, to run the tests:
   pip install --group dev
   pytest
   ```

Remarks: the `--group <group-name>` option requires pip ≥ 25.1. If you have an older version,
the install command above will fail with an error message such as `no such option: --group`.
In this case, try to upgrade pip beforehand with:
```shell
pip install --upgrade pip
```
Alternatively, install the test dependencies `pytest` and `pytest-cov` manually
(or skip the optional test running step).


### HiPOP dependency

MnMS depends on [HiPOP](https://github.com/EMob-Lab/HiPOP.git), the C++ graph library
used under the hood. It is declared as a regular dependency, thus is automatically fetched
from [PyPI](https://pypi.org/project/HiPOP/) when necessary.
**For most users this is transparent**: a prebuilt HiPOP distribution adapted
to your OS / system architecture is downloaded, and no C++ toolchain is required.

Prebuilt distributions are currently provided for the following environments:
- Windows on x86_64 architecture (i.e. Intel/AMD CPU)
- Linux on x86_64 architecture (i.e. Intel/AMD CPU)
- MacOS (≥ 14 Sonoma) on ARM64 architecture (i.e. Apple M* CPU)

If your environment is not covered, the installation fails while fetching HiPOP.
You then need to build HiPOP locally (a C++ toolchain is required; see the
[HiPOP documentation](https://github.com/EMob-Lab/HiPOP#install-from-local-build)),
or contact the package maintainers.


## Usage, tutorials and examples

Simulations can be run from the command line with:

```shell
mnms path/to/config.json
```

... where `path/to/config.json` is a JSON configuration file defining the simulation parameters.
See `examples/cli/mnms_settings.json` for an example of such a configuration file,
and run `mnms -h` for more details.

Tutorials can be found in the `doc/tutorials` directory as jupyter notebooks.
Some simulation examples can be found in the `examples` directory.


## Documentation

### Built

Build the technical documentation using mkdocs with:

```shell
pip install --group doc
mkdocs serve
```


### Detailed

The detailed documentation is available here:
https://github.com/EMob-Lab/MnMS/blob/main/doc/MnMS_detailed_documentation.pdf
