|
1 | | -# Mesa: Agent-based modeling in Python |
| 1 | +# Synthetic movement data generation using Mesa |
2 | 2 |
|
3 | | -| | | |
4 | | -| --- | --- | |
5 | | -| CI/CD | [](https://github.com/projectmesa/mesa/actions) [](https://codecov.io/gh/projectmesa/mesa) | |
6 | | -| Package | [](https://pypi.org/project/Mesa/) [](https://pypi.org/project/Mesa/) [](https://pypi.org/project/Mesa/) | |
7 | | -| Meta | [](https://github.com/astral-sh/ruff) [](https://github.com/psf/black) [](https://github.com/pypa/hatch) [](https://scientific-python.org/specs/spec-0000/) | |
8 | | -| Chat | [](https://matrix.to/#/#project-mesa:matrix.org) | |
| 3 | +## About Mesa |
9 | 4 |
|
10 | | -Mesa allows users to quickly create agent-based models using built-in |
| 5 | +[Mesa](https://github.com/projectmesa/mesa) allows users to quickly create agent-based models using built-in |
11 | 6 | core components (such as spatial grids and agent schedulers) or |
12 | 7 | customized implementations; visualize them using a browser-based |
13 | 8 | interface; and analyze their results using Python's data analysis |
14 | 9 | tools. Its goal is to be the Python-based alternative to NetLogo, |
15 | 10 | Repast, or MASON. |
16 | 11 |
|
17 | | - |
18 | | - |
19 | | -*Above: A Mesa implementation of the WolfSheep model, this |
20 | | -can be displayed in browser windows or Jupyter.* |
21 | | - |
22 | | -## Features |
23 | | - |
24 | | -- Modular components |
25 | | -- Browser-based visualization |
26 | | -- Built-in tools for analysis |
27 | | -- Example model library |
28 | | - |
29 | | -## Using Mesa |
30 | | - |
31 | | -To install our latest stable release (3.0.x), run: |
| 12 | +## Installation |
32 | 13 |
|
33 | 14 | ``` bash |
34 | | -pip install -U mesa |
| 15 | +pip install mesa==2.4.0 shapely movingpandas |
35 | 16 | ``` |
36 | 17 |
|
37 | | -To install our latest pre-release, run: |
38 | | - |
39 | | -``` bash |
40 | | -pip install -U --pre mesa |
41 | | -``` |
42 | | -Starting with Mesa 3.0, we don't install all our dependencies anymore by default. |
43 | | -```bash |
44 | | -# You can customize the additional dependencies you need, if you want. Available are: |
45 | | -pip install -U --pre mesa[network,viz] |
46 | | - |
47 | | -# This is equivalent to our recommended dependencies: |
48 | | -pip install -U --pre mesa[rec] |
49 | | - |
50 | | -# To install all, including developer, dependencies: |
51 | | -pip install -U --pre mesa[all] |
52 | | -``` |
53 | | - |
54 | | -You can also use `pip` to install the latest GitHub version: |
55 | | - |
56 | | -``` bash |
57 | | -pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa |
58 | | -``` |
59 | | - |
60 | | -Or any other (development) branch on this repo or your own fork: |
61 | | - |
62 | | -``` bash |
63 | | -pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa |
64 | | -``` |
65 | | - |
66 | | -## Resources |
67 | | -For resources or help on using Mesa, check out the following: |
68 | | - |
69 | | -- [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann |
70 | | - Wealth Model, for beginners or those new to Mesa.) |
71 | | -- [Visualization Tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization) |
72 | | -- [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model, |
73 | | - SugarScape with Traders, with instructional videos) |
74 | | -- [Mesa Examples](https://github.com/projectmesa/mesa-examples) (A repository of seminal ABMs using Mesa and |
75 | | - examples of employing specific Mesa Features) |
76 | | -- [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets) |
77 | | - - [Development version docs](https://mesa.readthedocs.io/latest/) (the latest version docs if you're using a pre-release Mesa version) |
78 | | -- [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa) |
79 | | -- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa) |
80 | | - |
81 | | -## Running Mesa in Docker |
82 | | - |
83 | | -You can run Mesa in a Docker container in a few ways. |
84 | | - |
85 | | -If you are a Mesa developer, first [install Docker |
86 | | -Compose](https://docs.docker.com/compose/install/) and then, in the |
87 | | -folder containing the Mesa Git repository, you run: |
88 | | - |
89 | | -``` bash |
90 | | -$ docker compose up |
91 | | -# If you want to make it run in the background, you instead run |
92 | | -$ docker compose up -d |
93 | | -``` |
94 | | - |
95 | | -This runs the Schelling model, as an example. |
96 | | - |
97 | | -With the docker-compose.yml file in this Git repository, the `docker compose up` command does two important things: |
98 | | - |
99 | | -- It mounts the mesa root directory (relative to the |
100 | | - docker-compose.yml file) into /opt/mesa and runs pip install -e on |
101 | | - that directory so your changes to mesa should be reflected in the |
102 | | - running container. |
103 | | -- It binds the docker container's port 8765 to your host system's |
104 | | - port 8765 so you can interact with the running model as usual by |
105 | | - visiting localhost:8765 on your browser |
106 | | - |
107 | | -If you are a model developer that wants to run Mesa on a model, you need |
108 | | -to: |
109 | | - |
110 | | -- make sure that your model folder is inside the folder containing the |
111 | | - docker-compose.yml file |
112 | | -- change the `MODEL_DIR` variable in docker-compose.yml to point to |
113 | | - the path of your model |
114 | | -- make sure that the model folder contains an app.py file |
115 | | - |
116 | | -Then, you just need to run `docker compose up -d` to have it |
117 | | -accessible from `localhost:8765`. |
118 | | - |
119 | | -## Contributing to Mesa |
120 | | - |
121 | | -Want to join the Mesa team or just curious about what is happening with |
122 | | -Mesa? You can\... |
123 | | - |
124 | | -> - Join our [Matrix chat room](https://matrix.to/#/#project-mesa:matrix.org) in which questions, issues, and |
125 | | -> ideas can be (informally) discussed. |
126 | | -> - Come to a monthly dev session (you can find dev session times, |
127 | | -> agendas and notes on [Mesa discussions](https://github.com/projectmesa/mesa/discussions)). |
128 | | -> - Just check out the code on [GitHub](https://github.com/projectmesa/mesa/). |
129 | | -
|
130 | | -If you run into an issue, please file a [ticket](https://github.com/projectmesa/mesa/issues) for us to discuss. If |
131 | | -possible, follow up with a pull request. |
| 18 | +## User guide |
132 | 19 |
|
133 | | -If you would like to add a feature, please reach out via [ticket](https://github.com/projectmesa/mesa/issues) or |
134 | | -join a dev session (see [Mesa discussions](https://github.com/projectmesa/mesa/discussions)). A feature is most likely |
135 | | -to be added if you build it! |
| 20 | +To use the generators, follow the instructions in corresponding directory: |
136 | 21 |
|
137 | | -Don't forget to checkout the [Contributors guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md). |
| 22 | +- [Ship movement simulator](https://github.com/movingpandas/synth-data-generator/tree/main/mesa/examples/basic/ships_hybrid_algorithm) |
138 | 23 |
|
139 | | -## Citing Mesa |
| 24 | +## Acknowledgements |
140 | 25 |
|
141 | | -To cite Mesa in your publication, you can use the [CITATION.bib](https://github.com/projectmesa/mesa/blob/main/CITATION.bib). |
| 26 | +This work was supported in part by the Horizon Framework Programme of the European Union under grant agreement No. 101070279 ([MobiSpaces](https://mobispaces.eu)). |
0 commit comments