Mesarcade

Mesa + Arcade

Mesarcade is a Python package that provides fast, interactive visualizations of Mesa agent-based models using Python Arcade.

⚠️ Mesarcade is under active development. APIs may change.

Gallery

Schelling

Virus on network

Sugarscape

Components

Mesarcade follows a compositional design: you define how agents are drawn (Artists), where they are drawn (SpacePlots), what is tracked over time (HistoryPlots), and how parameters can be changed (Controllers), all embedded in a Canvas.

Artists

Artists are the visual representations of the entities in a mesa model.

• CellArtists: A visual representation for entities of type Cell.
• CellAgentArtists: A visual representation for a set of entities of type CellAgent.
• ContinuousSpaceAgentArtists: A visual representation for a set of entities of type mesa.ContinuousSpaceAgents.
• NetworkCellArtists: A visual representation for cells in a Network.
• NetworkAgentArtists: A visual representation for agents on a Network.

Example:

Let's create a visual representation for our CellAgents. We map the agent attribute type to the colors blue and red.

agents = mesar.CellAgentArtists(
    color_attribute="type",
    color_map={0: "blue", 1: "red"},
)

SpacePlots

SpacePlots are visual representations of certain space types in Mesa and plot the corresponding Artists at their position. You can add/layer as many artists as you want to.

• GridSpacePlot: Visualizes a grid.
• ContinuousSpacePlot: Visualizes a continuous space.
• NetworkPlot: A space in which networks are visualized.

Example:

Let's create a visual representation of a grid and add our agent artists. We could add other artists, too.

grid_space = mesar.GridSpacePlot(artists=[agents])

HistoryPlots

Line plots that plot (multiple) values as a function of the simulated time steps.

• ModelHistoryPlot: Plots model attributes or data that is collected using the model's datacollector as a function of the simulated time steps.

• AgentHistoryPlot: On the ToDo-List.

Example

Let's add a ModelHistoryPlot that visualizes the model attribute happy over time:

happy_plot = mesar.ModelHistoryPlot(model_attributes=["happy"], labels=["Happy agents"])

ValueDisplay

Text-based display for showing a single value of a model attribute.

Example

Let's add a ValueDisplay that shows the current value of the model attribute happy:

happy_value = mesar.ValueDisplay(model_attribute="happy", label="Happy agents")

Controllers

Interactive controllers of model attributes and parameters.

• NumController: A controller for numeric parameters.
• CatController: A controller for categorical parameters.

Example

Let's add a controller that determines the value of the model parameter homophily:

homophily = mesar.NumController(
    parameter_name="homophily", 
    parameter_value=0.4, 
    min_value=0,
    max_value=1,
    step=0.125,
    )

Canvas

The Canvas is the main window in which all components are placed.

Example

canvas = mesar.Canvas(
    model_class=Schelling, # the mesa model
    plots=[space, happy_plot], # all plots
    controllers=[density, minority_pc, homophily, width, height], # all controllers
)

# start the visualization
canvas.show()

Full example

More examples can be found in "/mesarcade/examples".

import mesarcade as mesar
from mesa.examples.basic.schelling.model import Schelling

# artists
agents = mesar.CellAgentArtists(
    color_attribute="type",
    color_map={0: "blue", 1: "red"},
    shape="circle",
)

# space plot
space = mesar.GridSpacePlot(artists=agents)

# line plot
happy_plot = mesar.ModelHistoryPlot(model_attributes=["happy"], labels=["Happy agents"])

# value display
happy_value = mesar.ValueDisplay(model_attribute="happy", label="Happy agents")

# controllers
density = mesar.NumController("density", 0.8, 0.1, 0.9, 0.1)
minority_pc = mesar.NumController("minority_pc", 0.2, 0.0, 1.0, 0.05)
homophily = mesar.NumController("homophily", 0.4, 0.0, 1.0, 0.125)
width = mesar.NumController("width", 100, 10, 200, 10)
height = mesar.NumController("height", 100, 10, 200, 10)

# gui window
canvas = mesar.Canvas(
    model_class=Schelling,
    plots=[space, happy_plot],
    value_displays=[happy_value],
    controllers=[density, minority_pc, homophily, width, height],
)

# show gui window
canvas.show()