# Mesa: Agent-based modeling in Python
| | |
| --- | --- |
| CI/CD | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |
| Package | [![PyPI - Version](https://img.shields.io/pypi/v/mesa.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mesa.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mesa.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/Mesa/) |
| Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) |
| Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
Mesa allows users to quickly create agent-based models using built-in
core components (such as spatial grids and agent schedulers) or
customized implementations; visualize them using a browser-based
interface; and analyze their results using Python's data analysis
tools. Its goal is to be the Python-based alternative to NetLogo,
Repast, or MASON.
![A screenshot of the Schelling Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/Mesa_Screenshot.png)
*Above: A Mesa implementation of the Schelling segregation model, this
can be displayed in browser windows or Jupyter.*
## Features
- Modular components
- Browser-based visualization
- Built-in tools for analysis
- Example model library
## Using Mesa
Getting started quickly:
``` bash
pip install mesa
```
You can also use `pip` to install the github version:
``` bash
pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa
```
Or any other (development) branch on this repo or your own fork:
``` bash
pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa
```
For resources or help on using Mesa, check out the following:
- [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann
Wealth Model, for beginners or those new to Mesa.)
- [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
SugarScape with Traders, with instructional videos)
- [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/main/examples) (A repository of seminal ABMs using Mesa and
examples of employing specific Mesa Features)
- [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
- [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)
- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)
## Running Mesa in Docker
You can run Mesa in a Docker container in a few ways.
If you are a Mesa developer, first [install Docker
Compose](https://docs.docker.com/compose/install/) and then, in the
folder containing the Mesa Git repository, you run:
``` bash
$ docker compose up
# If you want to make it run in the background, you instead run
$ docker compose up -d
```
This runs the Schelling model, as an example.
With the docker-compose.yml file in this Git repository, the `docker compose up` command does two important things:
- It mounts the mesa root directory (relative to the
docker-compose.yml file) into /opt/mesa and runs pip install -e on
that directory so your changes to mesa should be reflected in the
running container.
- It binds the docker container's port 8765 to your host system's
port 8765 so you can interact with the running model as usual by
visiting localhost:8765 on your browser
If you are a model developer that wants to run Mesa on a model, you need
to:
- make sure that your model folder is inside the folder containing the
docker-compose.yml file
- change the `MODEL_DIR` variable in docker-compose.yml to point to
the path of your model
- make sure that the model folder contains an app.py file
Then, you just need to run `docker compose up -d` to have it
accessible from `localhost:8765`.
## Contributing to Mesa
Want to join the Mesa team or just curious about what is happening with
Mesa? You can\...
> - Join our [Matrix chat room](https://matrix.to/#/#project-mesa:matrix.org) in which questions, issues, and
> ideas can be (informally) discussed.
> - Come to a monthly dev session (you can find dev session times,
> agendas and notes on [Mesa discussions](https://github.com/projectmesa/mesa/discussions)).
> - Just check out the code on [GitHub](https://github.com/projectmesa/mesa/).
If you run into an issue, please file a [ticket](https://github.com/projectmesa/mesa/issues) for us to discuss. If
possible, follow up with a pull request.
If you would like to add a feature, please reach out via [ticket](https://github.com/projectmesa/mesa/issues) or
join a dev session (see [Mesa discussions](https://github.com/projectmesa/mesa/discussions)). A feature is most likely
to be added if you build it!
Don't forget to checkout the [Contributors guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md).
## Citing Mesa
To cite Mesa in your publication, you can use the [CITATION.bib](https://github.com/projectmesa/mesa/blob/main/CITATION.bib).
Raw data
{
"_id": null,
"home_page": null,
"name": "Mesa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ABM, agent, based, model, modeling, multi-agent, simulation",
"author": null,
"author_email": "Project Mesa Team <projectmesa@googlegroups.com>",
"download_url": "https://files.pythonhosted.org/packages/8c/7b/5b99a01a3710ff699b5a54e9beed56508bf6a0b463426bba56466cfb3e4a/mesa-2.3.0.tar.gz",
"platform": null,
"description": "# Mesa: Agent-based modeling in Python\n\n| | |\n| --- | --- |\n| CI/CD | [![GitHub Actions build status](https://github.com/projectmesa/mesa/workflows/build/badge.svg)](https://github.com/projectmesa/mesa/actions) [![Coverage status](https://codecov.io/gh/projectmesa/mesa/branch/main/graph/badge.svg)](https://codecov.io/gh/projectmesa/mesa) |\n| Package | [![PyPI - Version](https://img.shields.io/pypi/v/mesa.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mesa.svg?color=blue&label=Downloads&logo=pypi&logoColor=gold)](https://pypi.org/project/Mesa/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mesa.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/Mesa/) |\n| Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) |\n| Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |\n\nMesa allows users to quickly create agent-based models using built-in\ncore components (such as spatial grids and agent schedulers) or\ncustomized implementations; visualize them using a browser-based\ninterface; and analyze their results using Python's data analysis\ntools. Its goal is to be the Python-based alternative to NetLogo,\nRepast, or MASON.\n\n![A screenshot of the Schelling Model in Mesa](https://raw.githubusercontent.com/projectmesa/mesa/main/docs/images/Mesa_Screenshot.png)\n\n*Above: A Mesa implementation of the Schelling segregation model, this\ncan be displayed in browser windows or Jupyter.*\n\n## Features\n\n- Modular components\n- Browser-based visualization\n- Built-in tools for analysis\n- Example model library\n\n## Using Mesa\n\nGetting started quickly:\n\n``` bash\npip install mesa\n```\n\nYou can also use `pip` to install the github version:\n\n``` bash\npip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa\n```\n\nOr any other (development) branch on this repo or your own fork:\n\n``` bash\npip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa\n```\n\nFor resources or help on using Mesa, check out the following:\n\n- [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann\n Wealth Model, for beginners or those new to Mesa.)\n- [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,\n SugarScape with Traders, with instructional videos)\n- [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/main/examples) (A repository of seminal ABMs using Mesa and\n examples of employing specific Mesa Features)\n- [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)\n- [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)\n- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)\n\n## Running Mesa in Docker\n\nYou can run Mesa in a Docker container in a few ways.\n\nIf you are a Mesa developer, first [install Docker\nCompose](https://docs.docker.com/compose/install/) and then, in the\nfolder containing the Mesa Git repository, you run:\n\n``` bash\n$ docker compose up\n# If you want to make it run in the background, you instead run\n$ docker compose up -d\n```\n\nThis runs the Schelling model, as an example.\n\nWith the docker-compose.yml file in this Git repository, the `docker compose up` command does two important things:\n\n- It mounts the mesa root directory (relative to the\n docker-compose.yml file) into /opt/mesa and runs pip install -e on\n that directory so your changes to mesa should be reflected in the\n running container.\n- It binds the docker container's port 8765 to your host system's\n port 8765 so you can interact with the running model as usual by\n visiting localhost:8765 on your browser\n\nIf you are a model developer that wants to run Mesa on a model, you need\nto:\n\n- make sure that your model folder is inside the folder containing the\n docker-compose.yml file\n- change the `MODEL_DIR` variable in docker-compose.yml to point to\n the path of your model\n- make sure that the model folder contains an app.py file\n\nThen, you just need to run `docker compose up -d` to have it\naccessible from `localhost:8765`.\n\n## Contributing to Mesa\n\nWant to join the Mesa team or just curious about what is happening with\nMesa? You can\\...\n\n> - Join our [Matrix chat room](https://matrix.to/#/#project-mesa:matrix.org) in which questions, issues, and\n> ideas can be (informally) discussed.\n> - Come to a monthly dev session (you can find dev session times,\n> agendas and notes on [Mesa discussions](https://github.com/projectmesa/mesa/discussions)).\n> - Just check out the code on [GitHub](https://github.com/projectmesa/mesa/).\n\nIf you run into an issue, please file a [ticket](https://github.com/projectmesa/mesa/issues) for us to discuss. If\npossible, follow up with a pull request.\n\nIf you would like to add a feature, please reach out via [ticket](https://github.com/projectmesa/mesa/issues) or\njoin a dev session (see [Mesa discussions](https://github.com/projectmesa/mesa/discussions)). A feature is most likely\nto be added if you build it!\n\nDon't forget to checkout the [Contributors guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md).\n\n## Citing Mesa\n\nTo cite Mesa in your publication, you can use the [CITATION.bib](https://github.com/projectmesa/mesa/blob/main/CITATION.bib).\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Agent-based modeling (ABM) in Python",
"version": "2.3.0",
"project_urls": {
"homepage": "https://github.com/projectmesa/mesa",
"repository": "https://github.com/projectmesa/mesa"
},
"split_keywords": [
"abm",
" agent",
" based",
" model",
" modeling",
" multi-agent",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b77416a7b5a2de5e49ae3b168e3a802b5c3130c0a9a95a450e7ee1eef3e244e",
"md5": "29b541f757e37bd38cf41852d400f151",
"sha256": "dbeb1cb04c3e815c27c9511bff88f0111311e33c8433566a6c9fc42e735ed46f"
},
"downloads": -1,
"filename": "mesa-2.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29b541f757e37bd38cf41852d400f151",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 65614,
"upload_time": "2024-04-23T19:36:09",
"upload_time_iso_8601": "2024-04-23T19:36:09.197177Z",
"url": "https://files.pythonhosted.org/packages/1b/77/416a7b5a2de5e49ae3b168e3a802b5c3130c0a9a95a450e7ee1eef3e244e/mesa-2.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c7b5b99a01a3710ff699b5a54e9beed56508bf6a0b463426bba56466cfb3e4a",
"md5": "70b80b62c11de1e9c965877487579175",
"sha256": "c171c2c94934e44cf8c9ee5ad6b2970b228f64c2bb6d1ef1679ae90f9984694c"
},
"downloads": -1,
"filename": "mesa-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "70b80b62c11de1e9c965877487579175",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1819834,
"upload_time": "2024-04-23T19:36:11",
"upload_time_iso_8601": "2024-04-23T19:36:11.723108Z",
"url": "https://files.pythonhosted.org/packages/8c/7b/5b99a01a3710ff699b5a54e9beed56508bf6a0b463426bba56466cfb3e4a/mesa-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 19:36:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "projectmesa",
"github_project": "mesa",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "mesa"
}