Introducing mesa-interactive

[Corvince]

Hello,

I'm excited to introduce a new frontend package for Mesa—Mesa-Interactive. Designed for both developers and researchers, this package enables interactive exploration of Mesa models for various purposes, such as demonstration, in-depth analysis, and even debugging.

screen-capture.4.webm

Features

• Time Navigation: Traverse back and forth in model time.
• State Modification: Interact with model states via click handlers.
• Simple Setup: A more straightforward visualization setup compared to other options.

Basic Setup Example

To set up the visualization, you can use the following code:

model_params = {
    "width": 20,
    "height": 20,
    "density": slide(0, 1, 0.1, default=0.65),
    "minority_pc": slide(0, 1, 0.05, default=0.2),
    "homophily": slide(0, 8, 1, default=3),
}

page = MesaInteractive(
    Schelling,
    model_params,
    components=[HappyCount, GridView, HappyChart],
    name="Schelling",
)

In the frontend, all model parameters are configurable by default. You have multiple options for how these configurations appear:

• Simple numerical or textual values will be displayed as an input box.
• Lists of possible values will manifest as a dropdown select box.
• Boolean parameters will automatically appear as checkboxes.

For greater control, you can use the utility function slide. This function operates similarly to Python's range, but it offers additional customization by allowing you to set a default value and step size.

Visualization Components

Here's how you can create visualization components like a GridView:

GridView = create_grid(color="type")

The color parameter is used to define which agent variable to use to differentiate the agents. In this case its type. This GridView component can be interactively called in a notebook session using GridView(model).

Interactivity

Add click handlers to make your model interactive:

def switch_agent_type(model, x, y):
    agent = model.grid[x, y]
    agent.type = 1 - agent.type

On a click the function is called with the current model state and the (x,y) coordinates. We can use that to get the correct agent and change its type (in the example the type is either 0 or 1).
Now, redefine your grid with GridView = create_grid("type", on_click=switch_agent_type).

We can also create charts with the following function

HappyChart = create_chart(variables={"happy"}, title="Happy Agents")

That is we call the function with a set or list of variables, which are model attributes and they are displayed as a line chart. Again this could be used standalone via HappyChart(model)

We can also add any model dependent text via

HappyCount = create_markdown(
    lambda model: f"Happy Agents: {model.happy} of {len(model.schedule.agents)}"
)

In principal we can pass any solara component to our visualization and those components will be called with model as their only component. If you want to display components independent of the model state, e.g. static text you can wrap it in a static utility function

from mesa_interactive import static
Instructions = static(solara.Markdown("Click on an agent to switch its type."))

That means you can use your own solara components or for example matplotlib graphs wrapped in solaras FigureMatplotlib

Installation

Mesa-interactive is available as a normal python package and installable via

pip install mesa-interactive

You can have a look at the repo and provided additional ideas here in this thread or as dedicated issues. I hope some people will find this useful and use it for there models.

Deployment

By the end of the year some changes are coming to solara that should make it easier to deploy your own models on the internet and this will be reflected in mesa-interactive, but until then you can look at official solara documentation

[EwoutH]

Thanks a lot for this effort. Being able to really inspect how the environment influences agent behaviour is extremely useful!

Will there be a tutorial or getting started guide in the docs somewhere? I would really love to share this with our students!

I will try to explore Mesa interactive early next week, and if your find it useful, deliver some feedback.

CC @omarkamouh and @igornikolic: This looks like a tremendous new capability to explore ABM models and behaviour, with serious educational value. Might be close following closely!

[Corvince]

Thanks! Yes I didn't manage to add a proper tutorial before I went on vacation. I will add once I am back (beginning of November)

Would be much appreciated if you could have a closer look or even just try to run the examples from the repo.

I also just noticed that I forgot to add a screen cast to the intro post, where I recorded the features. Oh well.

[EwoutH]

Looked at it, nothing happens when I call app or page from the examples. Tried both in a Jupyter Notebook as in regular Python code. What should happen?

[Corvince]

Oh. Are there any error messages? It should work the same as the new normal visualization, i.e. either in a notebook or by calling solara run app.py

[EwoutH]

by calling solara run app.py

Right, didn't know that I needed to call it that way! That works.

In a Jupyter Notebook (running inside PyCharm) I get the following:

But that could be due to my environment (Python 3.11, PyCharm 2023.2.1, Windows 11).

[EwoutH]

Filed an issue about the notebook visualisation at JetBrains.

In the mean time I will play with it a bit outside Jupyter notebooks!

[Corvince]

@rlskoeser Do you think this package might be of interest to you? What features would you wish for?

[rlskoeser]

Hi, @Corvince. Thanks for asking, and sorry for the delay in replying. The ability to go backwards in time to inspect a model and how it arrived at a particular state was something that come up as something of interest to my collaborator after the last time you asked about it.

Simpler setup sounds like it would be valuable; right now I'm more interested in being able to easily customize things, which seems to be tricky with the version of mesa jupyterviz I'm currently using (2.1.2). Maybe those things are related - simpler setup, if done right, could hopefully make it easier to customize certain parts without having to understand all of the details of how the interface is constructed. I haven't looked closely enough at this package to see if that's the case, maybe it already is. Would you markdown let me display the state of the model (running until it converges at some point, and reports on the value of convergence)? How easy to display a custom agent space (I'm drawing mine with Altair instead of matplotlib)? How easy to modify the grid layout or be more responsive (space needs when running in a notebook vs standalone in a browser are pretty different)?

It does seems potentially confusing — how do you clearly differentiate what this package does vs. the interface and interaction provided by the core mesa library?