Model#

Quick intro#

The Model orchestrates the simulation lifecycle: creating and registering AgentSet``s, stepping the simulation, and integrating with ``DataCollector and spatial ``Grid``s. Typical usage:

Instantiate Model, add AgentSet instances to model.sets.
Call model.sets.do('step') inside your model loop to trigger set-level updates.
Use DataCollector to sample model- and agent-level columns each step.

Minimal example#

from mesa_frames import Model, AgentSet, DataCollector
import polars as pl

class People(AgentSet):
    def step(self):
        self.add(pl.DataFrame({'wealth': [1, 2, 3]}))

class MyModel(Model):
    def __init__(self):
        super().__init__()
        self.sets += People(self)
        self.dc = DataCollector(model_reporters={'avg_wealth': lambda m: m.sets['People'].df['wealth'].mean()})

m = MyModel()
m.step()

API reference#

Overview

Lifecycle / Core

`Model.__init__`	Create a new model.
`Model.step`	Run a single step.
`Model.run_model`	Run the model until the end condition is reached.
`Model.reset_randomizer`	Reset the model random number generator.

Accessors / Properties

`Model.steps`	Get the current step count.
`Model.sets`	Get the AgentSetRegistry object containing all agent sets in the model.
`Model.space`	Get the space object associated with the model.
`Model.seed`	Return the current seed used by the model's random generator.

Full API

class Model(seed: int | Sequence[int] | None = None)[source]#

Base class for models in the mesa-frames library.

This class serves as a foundational structure for creating agent-based models. It includes the basic attributes and methods necessary for initializing and running a simulation model.

Methods:

`__init__`	Create a new model.
`reset_randomizer`	Reset the model random number generator.
`run_model`	Run the model until the end condition is reached.
`step`	Run a single step.

Attributes:

`random`
`running`
`seed`	Return the current seed used by the model's random generator.
`steps`	Get the current step count.
`sets`	Get the AgentSetRegistry object containing all agent sets in the model.
`space`	Get the space object associated with the model.

__init__(seed: int | Sequence[int] | None = None) → None[source]#

Create a new model.

Overload this method with the actual code to start the model. Always start with super().__init__(seed) to initialize the model object properly.

Parameters:: seed (int | Sequence[int] | None, optional) – The seed for the model’s generator

random: Generator#

running: bool#

reset_randomizer(seed: int | Sequence[int] | None) → None[source]#

Reset the model random number generator.

Parameters:: seed (int | Sequence[int] | None) – A new seed for the RNG; if None, reset using the current seed

property seed: int | Sequence[int]#

Return the current seed used by the model’s random generator.

Returns:: The seed that initialized the underlying RNG.
Return type:: int | Sequence[int]

run_model() → None[source]#

Run the model until the end condition is reached.

Overload as needed.

step() → None[source]#

Run a single step.

The default method calls the step() method of all agents. Overload as needed.

property steps: int#

Get the current step count.

Returns:: The current step count of the model.
Return type:: int

property sets: AgentSetRegistry#

Get the AgentSetRegistry object containing all agent sets in the model.

Returns:: The AgentSetRegistry object containing all agent sets in the model.
Return type:: AgentSetRegistry
Raises:: ValueError – If the model has not been initialized properly with super().__init__().

property space: Space#

Get the space object associated with the model.

Returns:: The space object associated with the model.
Return type:: Space
Raises:: ValueError – If the space has not been set for the model.