projectmesa / mesa

Mesa is an open-source Python library for agent-based modeling, ideal for simulating complex systems and exploring emergent behaviors.

Mesa: Agent-based modeling in Python

CI/CD
Package
Meta
Chat

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.

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:

pip install mesa

You can also use pip to install the 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 Boltzmann Wealth Model, for beginners or those new to Mesa.)
• Complexity Explorer Tutorial (An advanced-beginner model, SugarScape with Traders, with instructional videos)
• Mesa Examples (A repository of seminal ABMs using Mesa and examples of employing specific Mesa Features)
• Docs (Mesa's documentation, API and useful snippets)
• Discussions (GitHub threaded discussions about Mesa)
• Matrix Chat (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 and then, in the folder 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, 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 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).
• Just check out the code on GitHub.

If you run into an issue, please file a ticket 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 or join a dev session (see Mesa discussions). A feature is most likely to be added if you build it!

Don't forget to checkout the Contributors guide.

Citing Mesa

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

mesa's Issues

Write tests for Data Collector

This has no tests. Filing this ticket to hold ourselves accountable -- #45

Server failing when requesting non-existent step

Currently, nothing stops the server from requesting a step which exceeds the range of model steps created; this causes the server to fail. Should be very easy to fix.

Compare previous versions of model code (same as tornado ticket)

This is in progress here...
https://github.com/projectmesa/mesa/tree/master/docs/notes/model_comparisons

What license do we use & why?

Batch runner / parameter sweeper

Class which takes a model object and a sequence of parameters and associated ranges, executes a sweep of all their possible permutations, and stores the given reporters. The latter part should be conceptually similar to the DataCollector object.

I think this is the real killer feature -- no other ABM framework lets you run a parameter sweep, then immediately and interactively analyze the output without leaving your environment or exporting it to a different application.

Synch between visualization and model

@kfuruya pointed out that I made a big unstated assumption in a previous comment, so opening up a new ticket to discuss.

Basically: how close a coupling should there be between the model and the visualization? As I see it, the two basic options are:

1. The model object and the browser visualization stay in step with one another. The model runs one step, sends the visualization data to the browser, which renders it. The browser then sends a message back to the server, which runs the next step of the model, etc.
2. The model and the visualization run somewhat independently. In practice, this presumably means that the model runs very quickly and generates a queue of visualization states (which might be stored in the server, or in the browser).

There are advantages and disadvantages to both. Off the top of my head, some of them are

• Tight coupling can be good for experiments where the user can change parameters at runtime and see the results right away. Otherwise, you either disable that feature altogether or have some really unwieldy way to fake it.
• Loose coupling makes it easier to allow 'scrubbing' forward and backward through a model run, which I think can be immensely powerful (and as far as I know would be a new feature that doesn't exist in any widespread ABM framework).
• Tight coupling is probably easier to code, since we don't need to worry about where to cache the data, updating the cache from both ends, etc.
• Loose coupling could allow a model to 'buffer' and make the visualization smoother, important for really time-consuming models.
• Tight coupling can give an immediate sense of how fast / slowly a model is running, particularly if its running slower than the user's target frame rate.

In a perfect world (/ final product), we would have both. Writing the advantages / disadvantages down now, I'm actually changing my mind and leaning towards looser coupling. Reasons are:

1. Updating parameters on the fly can be good for experimenting, but encourages bad (read: not self-documenting) science. If you want a different behavior, you should either reset the model and run with new parameters, or explicitly add in a mid-run parameter change.
2. I don't want to deal with writing a cache / queue thing, but I really want a visualization scrubber.

User-settable parameters in visualization

In many cases, we want the user to be able to set some (though not necessarily all!) model parameters via the visualization interface. There should be a way to easily annotate which parameters ought to be interactive, what their data type is, and what their legal range is.

Implement canvas visualization

Implement a (grid, to start) visualization which uses HTML5 canvas

Test canvas server with Schelling model

Get the new canvas branch, and run SchellingCanvas.py in the examples. Open a browser to 127.0.0.1:8888 and see if it works.

Unit-testing framework

Another 3am insomnia idea, but: The problem with unit-testing ABMs is that all their componentsare so interconnected. What if Mesa had a built-in unit-testing framework designed specifically for ABMs? I don't think such a thing exists yet, but it could be very valuable.

Research Tornado/other options for server & possible front-end solutions

Basics things we are looking for...

• Run a local server
• Be able to run step by step (or show animation of a whole run)
• Is it step, display, step, display OR does the model cache all the steps, then run it
• Front-end scrubber exists in ipython notebook
  • Look at Schelling Scrubber file from David.

Nice to have one day...

• ABM in as a web app with 100k people all playing it. MUHAHAHAHA
  • 100k has their own instance
  • 100k participating in the same model or watching it

Review tornado usage from previous projects

https://github.com/jackiekazil/goalnet
& the css605 2012 repo

Canvas speed test with ForestFire model

I added a simple ForestFire model to the canvas branch, and created a CanvasServer visualization for it. It's a good stress test, I think, since it involves sending and drawing ~6500 portrayal objects for every step. It ran at a very reasonable speed for me, though it isn't getting up to the full-speed 20fps. Try it yourself and see if the performance is adequate.

To do it, check out the dmasad.ticket46.canvas branch, to to examples/ForestFire, and run ForestFireVisualization.py. Then open your browser to 127.0.0.1:8888 and see how it runs for you.

Create initial implementation of visual front-end grid

See #19 for guidance.

Network structure

Implement a network data structure for agents, probably built on top of NetworkX.

Turn mesa into a python package proper

Turn mesa into a proper python package.

Canvas multigrid

Add a quick check to make sure the canvas server can handle MultiGrids

Logo

It would be nice to have a logo. Anyone feeling artistic? Sadly, it looks like a good logo is already taken.

Create template for README.md for examples

To complete this...

• Create general template for example READMEs
  • brief description
  • how to demo the example; how do I run this
  • anything else that is important
  • citations?
• Implement one -- the forest fire
• Create tickets for all the other Readme files to be created (or create them) :-)

Start a feature doc somewhere -- in reference repo or google

Move ideas from Readme in this report to the ideas doc.

Create an example ipython notebook

Create an example ipython notebook.

• Use it to show the ascii visualization.

Come up with some more target examples

Come up with (and try to implement, or at least dummy-code) some more good foundational ABMs.

Update Pypi record -- https://pypi.python.org/pypi/Mesa/0.0.0

After #64 -- update Pypi record -- https://pypi.python.org/pypi/Mesa/0.0.0

Document discussion scribbles -- suggested implementation format

schelling

• init.py
• agent.py
• model.py
• new customized stuff -- ie scheduler.py, decision_model.py
• visualization.py

Continuous space

A space object where objects can have continuous position, and a get_neighbors(...) method equivalent which can get all the objects within a certain radius of a point.

Mason does this (I think) with a quadtree, but I don't know whether we need to worry about that at this point. A bigass agent:coords dictionary might work just as well for starters?

If / when we add GIS (not looking forward to that), it'll probably extend this.

Flesh out initial objects in mesa

Composite different server visualization elements

Currently there are two completely different servers: TextServer takes a TextVisualization and puts it in the browser, and CanvasServer can only draw a grid. They have many elements in common, though also some key differences.

The way to probably refactor them is to let the user create a Visualization class, which can mix and match text, canvas, to-be-implemented charts, etc. Then this composite visualization object is given to a highly parameterized server, which assembles the corresponding web page (based on a highly parameterized template, or better yet via mixing-and-matching with Tornado's UI objects), and figures out how to serve it appropriately.

SBP Tutorial Submission

Propose an SBP tutorial

Model parameters in server

Currently, the visualization server (TextServer.py) takes a bunch of inputs at creation, some of which are actually the parameters to instantiate the model object with. There should be a way to store these more elegantly in the server object, and catch errors from passing parameters which the model constructor doesn't expect.

Create Changes file

How to keep PyPI up to date

Figure out how to update the mesa available on PyPI -- is there a way to synch it to GitHub? Does Jackie need to update it every so often with a new zip file? What's the best practice on that?

Front-end choices

What web tools to use to to design the front-end? Jackie and David's initial discussion was bootstrap + d3, but there might be better ways. Might also depend on which back-end system we use?

Add neighborhood description to Schelling Model.ipynb

Right now, the neighborhood is not described in the schelling notebook -- 4? or 8?
Please add this clarification to the notebook.

Test setup instructions for Mesa

Go through the setup instructions and make sure they work.
Instructions here: https://github.com/projectmesa/mesa/blob/master/README.md

Where it is weak, update the Readme section.
This should be to get someone set up & launch one of the sample simulations.

Update front-end text server to user fixed width font

Update front-end text server to user fixed width font

Multiple visualizations

I think it should be possible to create several visualizations for a single model -- and more importantly, have multiple visualizations hooked up to a single model instance, so that when the model steps, all the visualizations do as well.

(I actually woke up at 4AM worrying about this, so it's possible that this idea needs more thought)

Make model run a coroutine

Right now, the visualization server (mesa/visualization/TextServer.py) runs the entire model to completion prior (the run_model(...) method) to serving the visualization. The model run should if possible be concurrent. This is the "Kim make this thing concurrent" ticket.

Create a settings file, then call the settings file

We have a hard coded ip in our code identified here: #44 (comment)

Todo:

• url should be settable
• port should be settable

Add grass to Wolf-Sheep Predation Model

The wolf-sheep predation model does not currently have the sheep eating grass. Add in the grass, and have it reduced by sheep eating it, and grow back at a fixed rate.

Make Grid.get_neighbors() support radius > 1

Setup Sphnix documentation

Data collector

Base data collector which can (as easily as possible) collect data from one or more model runs and put them into (presumably) a pandas DataFrame. For inspiration into what this should look like, look at how RNetLogo does it:
http://blog.revolutionanalytics.com/2014/07/agent-based-models-and-rnetlogo.html

Figure out Javascript library to use to write visualization

What Javascript library should we use to implement the front-end visualization? D3.js seems like the most natural choice, but it has its own weird data model which may not work for us. Raphael seems to be lower level, but might need more coding to spin up. There are probably other options too.

Run through master and fit everything to the styleguide

Also make a styleguide

ASCII based server visualization

Write a simple Tornado server that displays the ascii visualization in the browser.

Grid neighbors errorring out on non-torus

Discovered in the Forest Fire model in the BatchRun branch. When the grid is not a torus, the get_neighbors method is erroring out on the edge.

create reference repo & dump 605 code in there

Python 2 or 3

Let's discuss.
@dmasad @kfuruya?

My vote is for 3, but I am open to hearing otherwise.

Implement dat-gui

Add dat-gui to the ASCII server.

Write a contributing file

Use this an example: Like this.... https://github.com/18F/midas/blob/devel/CONTRIBUTING.md