Thanks for reading up before asking questions, and then asking targeted, informed questions. That's appreciated!

Most of our models can be improved in this regard, here are some examples:

• Wolf–Sheep Predation: A classic predator–prey model where wolves and sheep move, eat, and reproduce while tracking continuous energy levels. It highlights how even simple agents require juggling multiple drives (survival, movement, reproduction) using hand-coded logic. Pain point: Multi-step actions (e.g., hunting) must be faked with per-tick rules because Mesa lacks task duration or priority management.
• Schelling Segregation: Agents evaluate local similarity and relocate when dissatisfied, producing emergent spatial patterns from threshold-based decisions. It’s a clean example of stateful decision-making driven by continuous dissatisfaction metrics. Pain point: Moves are instantaneous and there’s no concept of gradual action, making it impossible to model multi-step relocation or inertia.
• Epstein's Civil Violence: Citizens and cops interact based on grievance, risk, and legitimacy, approximating BDI-like reasoning through inline formulas. It’s a strong case of complex motivations crammed into a single step function. Pain point: The behavior architecture collapses into bulky conditional logic because Mesa offers no structure for beliefs, desires, or competing goals.
• Boids (Flocking): Agents compute steering forces (alignment, cohesion, separation) continuously, creating smooth flocking. This model stresses continuous state updates and layered behaviors in every tick. Pain point: All behaviors are blended manually each step instead of modularized, showing the need for stackable behavior components or continuous behavior nodes.
• Sugarscape: Agents consume resources, metabolize energy, move based on local gradients, and even trade in extended versions. It demonstrates rich, multi-variable needs that demand arbitration between competing goals. Pain point: All needs (food, movement, vision, trading) get stuffed into one big step method, illustrating how badly Mesa lacks goals, tasks, or behavior trees.

You can find them in https://github.com/projectmesa/mesa/tree/main/mesa/examples

So note there can be two distinct goals:

• Make existing complex behavior easier to implement
• Allow new, previously impossible, behaviour

Project can address either one of these or both.

This is really helpful, thanks! I'll start implementing these models and dig into the pain points. If I get stuck or have questions along the way, I'll reach out.

@EwoutH I read the discussions, and have a couple of ideas to get myself started. I see that mesa-llm was worked upon last year, so I have a social simulation that can be added as example if I get it right. The first is a more complex and dynamic extension of the world we live in, where essentially an agent powered by an llm is given in charge of a household, each having varying degrees of income, behaviour patterns and respective goals. This would focus on allowing newer, complex behaviours. This is something I plan on working to better understand the framework as well as the mesa-llm capabilities.

Secondly, I was wondering if the idea of an open source llm finetuned to help with mesa code is something that sounds appealing. I have a background in deep learning, and would like to know your thoughts on pursuing this as a project and if so the expected scope

I have a social simulation that can be added as example if I get it right

Cool, be sure to open an PR to Mesa-examples!

the idea of an open source llm finetuned to help with mesa code is something that sounds appealing

Personally, based on my limited knowledge and experience in this topic, with current frameworks for fine tuning and without continual learning, I think context engineering and scaffolding is enough to get LLMs to write proper Mesa code. The conceptual modeling decisions and data are more challenging than the code itself anyway. But I’m open to learn on this topic!

Yes current setups are enough, the context length is sometimes a friction though and multiple iterations to get it done. Rather I would agree on the fact that not having continual learning is a bigger issue because what would really benefit such a model is to keep updating itself as the codebase expands and gets updated

Thanks for proposing it. You have seen https://github.com/projectmesa/mesa-llm right?

We greatly appreciate ideas for mesa-llm if you have any !

However, I encourage you to take a deeper look at mesa-llm in person and not only through the lens of ChatGPT or other tools like this.
To answer to each of your comments :

• no scheduler is used in mesa-llm, and it's fully up to date with mesa3.0
• we already use enforced structured output as jsons
• we already provide support for local models via ollama as well as online API for bigger models

For next time, it gives better impression if it looks like you've actually seen the library once when you claim to have done it ;)

Hi @colinfrisch,

Touché. You are absolutely right, and I owe you an apology.

I made the mistake of making assumptions based on a superficial scan of the repository rather than a deep code review. That was sloppy on my part, and I appreciate you calling it out.

It is genuinely impressive that mesa-llm already handles structured JSON and local models seamlessly with Mesa 3.0. That puts the foundation much further ahead than I realized.

I will take a step back and properly study the existing codebase (actually running it this time) after my exams conclude in mid-January. If I find a genuine gap—perhaps in advanced memory architectures or specific agent evaluations—I will propose something concrete then. Until then, I’ll hold off on making claims.

Thanks for the honest check. Lesson learned. 😅

After following this discussion (#1944) and the more recent work around DataRegistry, DataSet, and Recorder, one area that seems both critical and still relatively underdeveloped is the storage backend layer that Recorder delegates to.

From the direction outlined here — especially the separation between live state (DataSet) and snapshot recording (Recorder) — it’s clear that Recorder is intended to be backend-agnostic, with support for multiple storage targets such as in-memory, SQL, Parquet, or numpy-based backends. The introduction of a StorageBackend protocol and typed Snapshot abstraction is a really strong foundation, but there doesn’t yet appear to be a complete, consistent set of reference backends designed specifically for scalable experiment workflows.

A practical contribution in this area could be to implement a modular, production-ready backend framework that integrates cleanly with Recorder and supports efficient storage, retrieval, and analysis for large simulations.

Concretely, this would involve:

• Implementing one or two fully supported backend implementations, such as:

– ParquetBackend, using PyArrow, to provide efficient columnar storage, compression, and direct interoperability with Polars, DuckDB, and pandas
– DuckDBBackend, enabling fast local querying and analysis of simulation results without requiring an external database

• Ensuring these backends implement the existing StorageBackend protocol properly and support all Snapshot kinds (agent datasets, model datasets, numpy datasets, and event logs).

• Designing a clear and consistent schema mapping between DataSet snapshots and stored representation, aligned with the schema-based storage approach discussed earlier in this thread, so that attribute names, agent IDs, and timestamps are stored efficiently without redundant key duplication.

• Making backend switching fully transparent at the model.data level, for example:

model.data.backend = ParquetBackend("./results")

without requiring changes to dataset definitions or Recorder logic.

• Supporting efficient retrieval back into analysis tools, so users can load results directly into pandas, Polars, or DuckDB for downstream analysis.

This aligns directly with several design goals discussed in #1944 :

– Making data collection extensible and backend-independent
– Supporting large-scale and long-running simulations without excessive memory usage
– Enabling integration with modern scientific data tooling
– Preserving a clean separation between state tracking (DataSet) and storage (Recorder)

It would also complement the current Recorder architecture well, since Recorder already handles snapshot generation and is designed to delegate persistence to interchangeable backends.

A concrete first step would be implementing ParquetBackend and DuckDBBackend as reference implementations, validating them against the experimental data collection workflow, and ensuring they support agent, model, and event datasets consistently.

I’d be interested to hear whether expanding the storage backend layer in this way would be a useful and aligned direction with the ongoing redesign of Mesa’s data collection system.

I've been thinking about one aspect of discoverability. The current categorization structure of example models in mesa-examples

Currently example models are categorized mostly just on the basis of spatial implementation (with a few exceptions). They lack any kind of domain specification (such as NetLogo's approach for their sample models that segments them into domains like Biology, Social Science, Art, Mathematics, etc).

While citations in READMEs can make up for domain context or source, it certainly won't make the process of finding a domain specific example model any easier for a new user.

One possible improvement could be to introduce domain-level categorization either though domain-based directory structure, tags or metadata files in every example model's folder (such as a metadata.toml file) that would explicitly capture the domain an example belongs to. This could then be used to enable domain-based browsing or filtering in the documentation making it easier for users to discover example relevant to the kinds of problems they are interested in without requiring prior knowledge of the repository's structure or Mesa's internal abstractions.

We could further add more filters such as implementation complexity, core features and tooling, etc.

The said metadata.toml file might look something like:

title = "Deffuant–Weisbuch Opinion Dynamics"

# Domain-level discoverability
domain = [
  "social_science",
  "opinion_dynamics"
]

# How difficult the example is to understand / extend
complexity_level = "intermediate"

# Mesa components demonstrated by this example
mesa_features_used = [
  "RandomActivation",
  "DataCollector"
]

# High-level modeling idea
[model]
concept = "agent_interaction"

# Source 
[source]
type = "paper"
citation = "Deffuant, G., Neau, D., Amblard, F., & Weisbuch, G. (2000). Mixing beliefs among interacting agents. Advances in Complex Systems."

# Optional but can be useful for docs / gallery
[docs]
short_description = "A bounded-confidence opinion dynamics model on a network."
learning_objectives = [
  "Demonstrate bounded-confidence interaction rules",
  "Show opinion clustering on networks",
]

# Who maintains this example
[maintenance]
maintainer(s) = "@github-username"
last_updated = "2026-01-24"

I think something like this could be worth discussing further.

Feel free to create a new discussion thread for this. Maybe in Mesa-examples.

I've started a discussion at #313.

I’ll be starting discussion points for the other goals as well inside that thread as I continue to study, brainstorm, and scope the project further!

@EwoutH I have been building example models and contributing to mesa-examples for the past few months.

While going through the repository and the discussions here, I was thinking about a possible direction that might help make mesa-examples easier to maintain while also improving discoverability and contributor experience.

One idea could be to separate example code from the infrastructure used to maintain and validate it, so contributors mainly focus on the model itself while automation handles compatibility testing, validation, and indexing.

For example, the repository could follow a structure like this:

examples/
│
├── forest_fire/
│ ├── example/ # model code
│ ├── docs/ # explanation and usage
│ └── infra/ # metadata, tests, CI helpers
│
├── schelling/
│ ├── example/
│ ├── docs/
│ └── infra/
│
└── traffic/
├── example/
├── docs/
└── infra/

In this setup:

• example/ contains the actual Mesa model implementation
• docs/ contains the explanation and usage documentation
• infra/ contains metadata, dependency definitions, and validation tests used by automation

This keeps the example code simple for contributors while allowing the repository to support automated tooling.

Example Metadata

Each example could include a lightweight metadata file:

name: Forest Fire
domain: ecology
difficulty: beginner
mesa_version: ">=3.0"
tags: [grid, spatial]

This metadata could be used for categorization and indexing.

Automation Pipeline

Conceptually the maintenance pipeline could look like this:

Example Code
     │
     ▼
Metadata + Validation
     │
     ▼
CI Compatibility Tests
     │
     ▼
Example Health Status
     │
     ▼
Searchable Example Gallery

This would help ensure that examples:

• remain functional as Mesa evolves

• are easier to discover

• require less manual maintenance

At the same time contributors would mainly interact with just:

example/
docs/

which keeps the contribution process simple.

Further i am working on this idea!
Curious to hear if a structure like this might make sense for the future of the repository, or if there are concerns or improvements worth considering.

I think this will be excellent pathfinding!

Hi @EwoutH,

I’ve opened a small PR that adds a minimal CI smoke test for batch_run
using the Boltzmann Wealth example, based on the gap discussed in #2184.

Whenever you get a chance, I’d really appreciate a quick review or any
feedback on whether this direction aligns with the current CI strategy.

Thanks a lot!

Sounds interesting. I think it’s a good start.

I think decide might also need something of a bound as input, like which actions are possible/allowed (i.e. RL action_space?). But that can also be investigated later.

Thank you @EwoutH for this insight.

I agree with you. A raw decide(state) interface is too open-ended. Passing explicit constraints is critical for RL agents and LLM agents. I will refine the interface design to include this constraint propagation.

I have now implemented the Durative Tasks and Interruption primitives we discussed.

I refactored the WolfSheep example to validate them:

• Reactive State: Sheep use mesa_signals to detect hunger without polling.
• Durative Actions: Grazing is a task that takes 5 ticks (using DEVS).
• Interruption: If a Wolf is detected while grazing, the task is cancelled immediately so the Sheep can flee.

I have opened a Draft PR with the implementation code and execution logs here: #3206

Now that the execution primitives are working, I will circle back to designing the decide(state, action_space) interface as you suggested.

from abc import ABC, abstractmethod

class DecisionModule(ABC):
    """
    The class that selects actions. 
    Can be swapped with RuleBased, LLM, or RL Policy.
    """
    @abstractmethod
    def select_action(self, state: dict, action_mask: list[str]) -> str:
        """
        Args:
            state: The current observation (e.g., {'energy': 5, 'wolves_near': True})
            action_mask: List of PHYSICALLY possible actions (e.g. ['GRAZE', 'MOVE'])
                         If a Wolf is near, 'GRAZE' might be removed from this list.
        """
        pass

class RuleBasedLogic(DecisionModule):
    def select_action(self, state, action_mask):
        # 1. Interruption logic moved here
        if "FLEE" in action_mask and state.get("threat"):
            return "FLEE"
        
        # 2. Needs
        if "GRAZE" in action_mask and state.get("energy") < 10:
            return "GRAZE"
            
        # 3. Default
        return "WANDER"

I’ve drafted the design for decision module and action spaces. Before I implement it, I want to check if this API signature aligns with your vision.

Thank you for the detailed feedback. Based on your comments, I will modify my roadmap to address the volatility of the core API and the specific needs of GIS visualization.

1. How about a Layer-Based Renderer. Rather than a single draw_propertylayer, the renderer will support a stack of composable layers (e.g., setup_raster_layer, setup_vector_layer). This mimics GIS tools (like Leaflet/QGIS) where users compose a map from multiple sources, while still adhering to the SpaceRenderer lifecycle (setup vs. draw) for compatibility with Solara.
2. I am thinking of designing RasterLayer to treat Mesa's PropertyLayer primarily as a backing storage engine. By encapsulating this dependency and keeping the public RasterLayer API distinct, we can shield Mesa-Geo users from potential internal implementation changes in Mesa 4.0.
3. I will write unit tests for the new affine coordinate transformations and create a tutorial notebook demonstrating the new pandas-like aggregation workflow on a real-world dataset.

@wang-boyu,
Following your advice on adopting a geo-specific visualization strategy, I have built a working prototype of the Layer-Based Renderer, GeoSpaceRenderer adapter that adheres to the SpaceRenderer interface but internally manages a stack of GIS layers rather than a fixed grid.

import solara
import matplotlib.pyplot as plt
import numpy as np
import mesa
from mesa.visualization.solara_viz import SolaraViz
from mesa.visualization.space_renderer import SpaceRenderer

class GeoSpaceRenderer(SpaceRenderer):
    """
    A Layer-Based Renderer that adapts to Mesa's SpaceRenderer interface.
    """
    def __init__(self, model):
        self.model = model
        self.backend = "matplotlib"
        self.layers = [] 
        self.fig, self.ax = plt.subplots(figsize=(6, 6))    
        self.agent_mesh = True 
        self.space_mesh = False
        self.propertylayer_mesh = False
        self._post_process_applied = False
        self.post_process = None
        class MockBackend:
            def __init__(self):
                self._active_colorbars = []
        self.backend_renderer = MockBackend()

    @property
    def canvas(self):
        return self.ax

    def setup_raster_layer(self, source, cmap="viridis", alpha=1.0):
        self.layers.append({"type": "raster", "source": source, "cmap": cmap, "alpha": alpha})

    def setup_vector_layer(self, source, color="red", marker="o"):
        self.layers.append({"type": "vector", "source": source, "color": color, "marker": marker})

    def draw_agents(self):
        self.ax.clear()
        for layer in self.layers:
            if layer["type"] == "raster":
                data = layer["source"](self.model)
                self.ax.imshow(data, cmap=layer["cmap"], alpha=layer["alpha"], origin="lower")
            elif layer["type"] == "vector":
                coords = layer["source"](self.model)
                if coords:
                    xs, ys = zip(*coords)
                    self.ax.scatter(xs, ys, c=layer["color"], marker=layer["marker"], s=50)
        return True 

    def draw_structure(self): pass
    def draw_propertylayer(self): pass

class MockGeoModel(mesa.Model):
    def __init__(self):
        super().__init__()     
        self.grid_width = 50
        self.grid_height = 50
        self.steps = 0
        self.simulation_agents = [mesa.Agent(self) for _ in range(10)]
        for a in self.simulation_agents:
            a.x = np.random.randint(0, 50)
            a.y = np.random.randint(0, 50)

    def step(self):
        self.steps += 1
        for a in self.agents: 
            a.x = (a.x + np.random.choice([-1, 0, 1])) % 50
            a.y = (a.y + np.random.choice([-1, 0, 1])) % 50


def get_elevation(model):
    """Dynamic Raster: Changes slightly every step"""
    x = np.linspace(0, 10, 50)
    y = np.linspace(0, 10, 50)
    X, Y = np.meshgrid(x, y)
    return np.sin(X) + np.cos(Y) + (model.steps * 0.1)

def get_agent_positions(model):
    """Vector Source: Returns list of (x,y) tuples"""
    return [(a.x, a.y) for a in model.agents]

model = MockGeoModel()

geo_renderer = GeoSpaceRenderer(model)

geo_renderer.setup_raster_layer(get_elevation, cmap="terrain")
geo_renderer.setup_vector_layer(get_agent_positions, color="black", marker="x")

page = SolaraViz(model, renderer=geo_renderer)

Does this adapter approach align with your vision for the visualization overhaul?

@wang-boyu,
I refactored a standard cellular automaton (Vegetation Growth) to use the PropertyLayer backend with strictly vectorized operations.
Instead of iterating Cell agents, the step logic is now purely numpy based.

import time
import numpy as np
import matplotlib.pyplot as plt
import mesa
from mesa.discrete_space import PropertyLayer

class CurrentCell:
    def __init__(self, x, y, vegetation=0.0):
        self.vegetation = vegetation
    def step(self):
        self.vegetation = min(1.0, self.vegetation + 0.05)

class CurrentModel(mesa.Model):
    def __init__(self, width, height):
        self.cells = [CurrentCell(x, y, np.random.uniform(0, 0.5)) 
                      for x in range(width) for y in range(height)]
    def step(self):
        for cell in self.cells:
            cell.step()

class NewModel(mesa.Model):
    def __init__(self, width, height):
        self.vegetation_layer = PropertyLayer(
            "vegetation", (width, height), default_value=0.0, dtype=np.float64
        )
        self.vegetation_layer.data = np.random.uniform(0, 0.5, (width, height))
    def step(self):
        self.vegetation_layer.data += 0.05
        np.clip(self.vegetation_layer.data, 0, 1.0, out=self.vegetation_layer.data)

def run_benchmark():
    W, H = 200, 200
    STEPS = 30000
    t0 = time.perf_counter()
    current_model = CurrentModel(W, H)
    for _ in range(STEPS): current_model.step()
    t_cur = time.perf_counter() - t0
    print(f"Current Way (Object Loop):   {t_cur:.4f} seconds")
    t0 = time.perf_counter()
    new_model = NewModel(W, H)
    for _ in range(STEPS): new_model.step()
    t_new = time.perf_counter() - t0
    print(f"New Way (Vectorized):    {t_new:.4f} seconds")
    speedup = t_cur / t_new
    print(f"\nSpeedup: {speedup:.1f}x faster")
    plt.figure(figsize=(6, 5))
    plt.imshow(new_model.vegetation_layer.data, cmap="Greens", vmin=0, vmax=1)
    plt.colorbar(label="Vegetation Density")
    plt.show()

if __name__ == "__main__":
    run_benchmark()

Current Way (Object Loop):   38.2370 seconds
New Way (Vectorized):    0.4808 seconds

Speedup: 79.5x faster

I have a few questions moving forward.

1. Moving to PropertyLayer means we lose cell.step(). Should we strictly enforce NumPy vectorization for performance, or should we expose a lightweight CellAgent wrapper for users who prefer object oriented logic?
2. PropertyLayer is grid based and unaware of CRS. I am thinking of designing RasterLayer as a wrapper that contains a PropertyLayer for storage but manages the Affine transform separately. This favors composition over inheritance.
3. Should a single RasterLayer object manage multiple internal PropertyLayers, or should users instantiate separate RasterLayer objects for each band?

Kindly let me know your thoughts on this.
Thank You.

Thanks for working on this. To answer your questions:

1. Moving to PropertyLayer means we lose cell.step(). Should we strictly enforce NumPy vectorization for performance, or should we expose a lightweight CellAgent wrapper for users who prefer object oriented logic?

I would prefer to keep cell.step(). Not all models can be easily written in a vectorized manner, especially if there's complex interactions between cells.

2. PropertyLayer is grid based and unaware of CRS. I am thinking of designing RasterLayer as a wrapper that contains a PropertyLayer for storage but manages the Affine transform separately. This favors composition over inheritance.

Sure but please be aware that there may (or may not) be future changes to PropertyLayer. If there's any changes to it in core Mesa, and we use it in Mesa-Geo, then we'll need to change accordingly.

3. Should a single RasterLayer object manage multiple internal PropertyLayers, or should users instantiate separate RasterLayer objects for each band?

Currently it's possible to have multiple bands in one RasterLayer, and it's quite common in GIS in general, so I'd like to keep that. This means that one Cell of such RasterLayer can have multiple properties, e.g., cell.elevation, cell.slope, etc.

Then it's possible to have multiple RasterLayers in a GeoSpace, each with its own resolution, transformation, Cell class, and so on.

1. How about we allow cell.step() without sacrificing the performance of the underlying NumPy storage. We will design the Cell class as a lightweight view into the RasterLayer data, rather than a data container itself. The Cell object only stores its coordinates (x, y). Properties like cell.elevation will dynamically read or write to the underlying PropertyLayer NumPy array. Users can still use cell.elevation += 1 and cell.step(). Data remains in contiguous NumPy arrays (inside PropertyLayer), enabling fast I/O, aggregation, and rendering.

class RasterCell(Cell):
    def __init__(self, layer, x, y):
        self._layer = layer
        self.x, self.y = x, y
        
    @property
    def elevation(self):
        # Reads directly from the vectorized backend
        return self._layer.bands["elevation"].data[self.x, self.y]
    
    @elevation.setter
    def elevation(self, value):
        # Writes directly to the vectorized backend
        self._layer.bands["elevation"].data[self.x, self.y] = value

    def step(self):
        # User logic works exactly as before
        if self.elevation < 10:
             self.elevation += 1

2. We will implement RasterLayer to manage a dictionary of PropertyLayer objects, one for each band (e.g., self.bands = {"elevation": prop_layer_1, "slope": prop_layer_2}). The RasterCell will act as the unified interface to access any of these bands.

3. I have already noted your warning about PropertyLayer volatility. As I have mentioned in my comment before, we wrap PropertyLayer entirely within RasterLayer, by which we shield the user-facing API from internal Mesa core changes. If PropertyLayer changes, we only need to update the internal wiring of RasterLayer.

Does this work for you?

@tpike3

I have also just submitted an example to mesa/mesa-examples with mesa/mesa-examples#434, interested in hearing any feedback!

I think it would be helpful to explore the documentation and review a few example implementations before starting your contribution.

Deadline to submit the proposal is March 31, 18:00 UTC