Repository files navigation

CI/CD
Package
Meta
Chat

Mesa allows users to quickly create agent-based models using built-incore components (such as spatial grids and agent schedulers) orcustomized implementations; visualize them using a browser-basedinterface; and analyze their results using Python's data analysistools. Its goal is to be the Python-based alternative to NetLogo,Repast, or MASON.

Above: A Mesa implementation of the WolfSheep model, thiscan be displayed in browser windows or Jupyter.

• Modular components
• Browser-based visualization
• Built-in tools for analysis
• Example model library

To install our latest stable release, run:

pip install -U mesa

Starting with Mesa 3.0, we don't install all our dependencies anymore by default.

# You can customize the additional dependencies you need, if you want. Available are:pip install -U mesa[network,viz]# This is equivalent to our recommended dependencies:pip install -U mesa[rec]# To install all, including developer, dependencies:pip install -U mesa[all]

You can also usepip to install the latest GitHub version:

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:

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 (An introductory model, the BoltzmannWealth Model, for beginners or those new to Mesa.)
• Visualization Tutorial (An introduction into our Solara visualization)
• Complexity Explorer Tutorial (An advanced-beginner model,SugarScape with Traders, with instructional videos)
• Mesa Examples (A repository of seminal ABMs using Mesa andexamples of employing specific Mesa Features)
• Docs (Mesa's documentation, API and useful snippets)
  • Development version docs (the latest version docs if you're using a pre-release Mesa version)
• Discussions (GitHub threaded discussions about Mesa)
• Matrix Chat (Chat Forum via Matrix to talk about Mesa)

You can run Mesa in a Docker container in a few ways.

If you are a Mesa developer, firstinstall DockerCompose and then, in thefolder containing the Mesa Git repository, you run:

$ 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, thedocker compose up command does two important things:

• It mounts the mesa root directory (relative to thedocker-compose.yml file) into /opt/mesa and runs pip install -e onthat directory so your changes to mesa should be reflected in therunning container.
• It binds the docker container's port 8765 to your host system'sport 8765 so you can interact with the running model as usual byvisiting localhost:8765 on your browser

If you are a model developer that wants to run Mesa on a model, you needto:

• make sure that your model folder is inside the folder containing thedocker-compose.yml file
• change theMODEL_DIR variable in docker-compose.yml to point tothe path of your model
• make sure that the model folder contains an app.py file

Then, you just need to rundocker compose up -d to have itaccessible fromlocalhost:8765.

Want to join the Mesa team or just curious about what is happening withMesa? You can...

• Join ourMatrix chat room in which questions, issues, andideas can be (informally) discussed.
• Come to a monthly dev session (you can find dev session times,agendas and notes onMesa discussions).
• Just check out the code onGitHub.

If you run into an issue, please file aticket for us to discuss. Ifpossible, follow up with a pull request.

If you would like to add a feature, please reach out viaticket orjoin a dev session (seeMesa discussions). A feature is most likelyto be added if you build it!

Don't forget to checkout theContributors guide.

To cite Mesa in your publication, you can use theCITATION.bib.