Using PropertyLayer instead of stationary patch agents in some examples

[ShreyasN707]

Hi everyone,

While exploring the mesa-examples repository and experimenting with Mesa’s newer APIs, I noticed that some spatial models represent environment state using stationary patch agents. For example, in the forest fire model, each grid cell is represented by a TreeCell agent whose main purpose is just to store the cell’s state (Fine, Burning, Burned).

Since Mesa now provides PropertyLayer for storing grid-based properties, I was wondering if some of these cases could be simplified by moving environment state to a property layer attached to the grid rather than creating thousands of patch agents.

For example, instead of something like:

class TreeCell(Agent):
    def __init__(self, model, pos):
        super().__init__(model)
        self.condition = "Fine"

the model could store this information directly on the grid using a PropertyLayer, e.g.:

fire_state = PropertyLayer(...)

with something like:

fire_state[x, y] = 0  # fine
fire_state[x, y] = 1  # burning
fire_state[x, y] = 2  # burned

The simulation step would then update the grid state directly instead of modifying agent attributes.

The idea would be to apply this only in examples where patch agents are acting purely as containers for environment state, not where they represent actual acting entities.

Some potential steps could be:

• Identify examples where patch agents are used mainly for environment variables (e.g., forest fire–type models).

• Replace those patch agents with one or more PropertyLayers attached to the grid.

• Update the model step logic to read/write from the property layer instead of agent attributes.

• Ensure the simulation behavior remains the same as the original example.

The motivation is mainly to:

• align examples with newer Mesa patterns (especially as the project moves toward Mesa 4),

• reduce unnecessary object overhead when cells are just storing simple state,

• and show new users how PropertyLayer can be used for environment data.

Before trying to work on something like this, @jackiekazil @EwoutH I wanted to check:

• whether this direction makes sense for the examples repository,

• and if there are particular models where this approach would be recommended or discouraged.

[codebreaker32]

PropertyLayer has been removed see mesa/mesa#3340

[ShreyasN707]

Thanks for the clarification! I wasn’t aware at moment that PropertyLayer had been removed.
I’ll take a look at the current recommended approach for handling environment state in spatial examples and rethink the idea accordingly.

[quaquel]

Just to clarify: the property layer class has been removed but the functionality is still there.

[codebreaker32]

Also a small suggestion: At some specific places(like conways_game_of_life_fast), you might want to use numpy arrays directly instead of property_layer due to less overhead

[ShreyasN707]

I took a look into the recent changes and the example conways_game_of_life_fast, it seems that the preferred approach in some cases might be storing environment state directly in array-backed structures (e.g., NumPy arrays) rather than creating stationary patch agents that only store state.

Based on that, I was thinking of slightly adjusting the original idea and exploring if some examples could replace patch agents used purely as environment containers with array-backed state stored on the model.

For example, instead of representing grid cells as agents like:

class TreeCell(Agent):
    def __init__(self, model, pos):
        super().__init__(model)
        self.condition = "Fine"

the environment state could potentially be stored as a grid-backed array:

import numpy as np

self.fire_state = np.zeros((width, height), dtype=np.int8)

with something like:

0 = fine
1 = burning
2 = burned

Then the simulation step could read/update the grid state directly, for example:

for (x, y) in self.grid.coord_iter():
    if self.fire_state[x, y] == BURNING:
        for nx, ny in self.grid.get_neighborhood((x, y), moore=True):
            if self.fire_state[nx, ny] == FINE:
                new_fire[nx, ny] = BURNING

This would avoid creating large numbers of patch agents when they are only acting as data containers.

The examples I was thinking of looking at first are models where patch agents mainly store cell state rather than behaving as agents, such as:

• forest_fire

• color_patches

• hex_snowflake

The goal is to:

• Identify examples where patch agents are only storing environment state.

• Replace those patch agents with array-backed structures.

• Keep the model behavior identical.

• Keep the code readable and educational for new users.

Before attempting any changes, I wanted to check if this direction makes sense for the examples repository, or if there are recommended patterns for storing environment state in these models.

Also happy to adjust or improve this plan if there are better approaches within the current Mesa architecture.