Model#

The model class for Mesa framework.

Core Objects: Model

class Model(*args: Any, seed: float | None = None, rng: RNGLike | SeedLike | None = None, scenario: S | None = None, **kwargs: Any)[source]#

Base class for models in the Mesa ABM 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.

Type Parameters:: A: The agent type used in this model S: The scenario type used in this model

running#: A boolean indicating if the model should continue running.

steps#: the number of times model.step() has been called.

time#: the current simulation time. Automatically increments by 1.0 with each step unless controlled by a discrete event simulator.

random#: a seeded python.random number generator.

rng#: a seeded numpy.random.Generator

scenario#: the scenario instance containing model parameters

Notes

Model.agents returns the AgentSet containing all agents registered with the model. Changing the content of the AgentSet directly can result in strange behavior. If you want change the composition of this AgentSet, ensure you operate on a copy.

Create a new model.

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

Parameters:

args – arguments to pass onto super
seed – the seed for the random number generator
rng – Pseudorandom number generator state. When rng is None, a new numpy.random.Generator is created using entropy from the operating system. Types other than numpy.random.Generator are passed to numpy.random.default_rng to instantiate a Generator.
scenario – the scenario specifying the computational experiment to run
kwargs – keyword arguments to pass onto super

Notes

you have to pass either seed or rng, but not both.

property scenario: S#: Return scenario instance.

property agents: _HardKeyAgentSet[A]#

Provides a _HardKeyAgentSet of all agents in the model, combining agents from all types.

Returns:: The agent set containing all agents with strong references.
Return type:: _HardKeyAgentSet

Warning

This returns the actual internal _HardKeyAgentSet used by Mesa for agent registration and tracking. It uses strong references to prevent premature garbage collection and reduce performance overhead caused by weak reference management.

Do not modify this AgentSet directly (e.g., by adding or removing agents manually). Direct modifications can break the model’s agent tracking system and cause unexpected behavior. Instead:

Use Agent() to create new agents (automatically registers them)
Use agent.remove() to remove agents (automatically deregisters them)
For read-only operations or transformations, work on a copy: model.agents.copy()

Notes

This is Mesa’s core agent registration system. All agents created via Agent.__init__ are automatically registered here.

property agent_types: list[type]#: Return a list of all unique agent types registered with the model.

property agents_by_type: dict[type[A], _HardKeyAgentSet[A]]#

A dictionary where keys are agent types and values are the corresponding _HardKeyAgentSets.

Returns:: Dictionary mapping agent types to their AgentSets.
Return type:: dict[type[A], _HardKeyAgentSet[A]]

Warning

Each AgentSet in this dictionary is a _HardKeyAgentSet with strong references, forming part of Mesa’s core agent registration system.

Do not modify these AgentSets directly. Direct modifications can break agent tracking and cause unexpected behavior. Instead:

Use Agent() to create new agents (automatically registers them)
Use agent.remove() to remove agents (automatically deregisters them)
For read-only operations, work on copies: model.agents_by_type[AgentType].copy()

Notes

This is part of Mesa’s core agent registration system. All agents are automatically registered in the appropriate type-specific AgentSet when created via Agent.__init__.

register_agent(agent: A)[source]#

Parameters:: agent – The agent to register.

Notes

This method is called automatically by Agent.__init__, so there is no need to use this if you are subclassing Agent and calling its super in the __init__ method.

batch()#

Return a context manager that batches signals.

Signals emitted during the batch are buffered and aggregated on exit. Nested batches merge into the outer batch; only the outermost dispatches.

Note

Computed properties may return stale cached values during the batch. They will be updated when aggregated signals are dispatched on exit.

clear_all_subscriptions(name: str | _AllSentinel | Iterable[str])#

Clears all subscriptions for the observable <name>.

if name is ALL, all subscriptions are removed

Parameters:: name – name of the Observable to unsubscribe for all signal types

deregister_agent(agent: A)[source]#

Deregister the agent with the model.

Parameters:: agent – The agent to deregister.

Notes

This method is called automatically by Agent.remove

notify(observable: str, signal_type: str | SignalType, **kwargs)#

Emit a signal.

Parameters:

observable – the public name of the observable emitting the signal
signal_type – the type of signal to emit
kwargs – additional keyword arguments to include in the signal

Subscribe to the Observable <name> for signal_type.

Parameters:

observable_name – name of the Observable to subscribe to
signal_type – the type of signal on the Observable to subscribe to
handler – the handler to call

Raises:

ValueError – if the Observable <name> is not registered or if the Observable
does not emit the given signal_type –

suppress()#

Return a context manager that suppresses all signals.

No signals are emitted, buffered, or dispatched during suppression.

Note

Computed properties may become permanently stale because their triggering signals are dropped entirely.

Unsubscribe to the Observable <name> for signal_type.

Parameters:

observable_name – name of the Observable to unsubscribe from
signal_type – the type of signal on the Observable to unsubscribe to
handler – the handler that is unsubscribing

run_model() → None[source]#

Run the model until the end condition is reached.

Overload as needed.

step() → None[source]#: A single step. Fill in here.

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

Reset the model random number generator.

Parameters:: seed – A new seed for the RNG; if None, reset using the current seed

Reset the model random number generator.

Parameters:: rng – A new seed for the RNG; if None, reset using the current seed

remove_all_agents()[source]#

Remove all agents from the model.

Notes

This method calls agent.remove for all agents in the model. If you need to remove agents from e.g., a SingleGrid, you can either explicitly implement your own agent.remove method or clean this up near where you are calling this method.

schedule_event(function: Callable, *, at: float | None = None, after: float | None = None, priority: Priority = Priority.DEFAULT) → Event[source]#

Schedule a one-off event.

Parameters:

function – The callable to execute
at – Absolute time to execute (mutually exclusive with after)
after – Relative time from now to execute (mutually exclusive with at)
priority – Priority level for the event

Returns:

The scheduled Event (can be used to cancel)

Raises:

ValueError – If both or neither of at/after are specified
ValueError – If both or neither of at/after are specified, or if the scheduled time is in the past.

schedule_recurring(function: Callable, schedule: Schedule, priority: Priority = Priority.DEFAULT) → EventGenerator[source]#

Schedule a recurring event based on a Schedule.

Parameters:

function – The callable to execute repeatedly
schedule – The Schedule defining when events occur
priority – Priority level for generated events

Returns:

The EventGenerator (can be used to stop)

Raises:

ValueError – If the schedule start time is in the past.

run_for(duration: float | int) → None[source]#

Run the model for the specified duration.

Parameters:: duration – Time units to advance

run_until(end_time: float | int) → None[source]#

Run the model until the specified time.

Parameters:: end_time – Absolute time to run until

If model.time is larger than end_time, the method returns directly.

Model#

This Page