Skip to content

Releases: mesa/mesa

v3.5.1

15 Mar 11:41
@EwoutH EwoutH
v3.5.1
e733e8e
This commit was signed with the committer’s verified signature.
EwoutH Ewout ter Hoeven
GPG key ID: 1271C5568170579C
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.5.1 Latest
Latest

Highlights

Mesa 3.5.1 is a maintenance release that backports bug fixes, performance improvements, and minor enhancements from the Mesa 4.0 development branch to the stable 3.5.x series.

The event scheduling system stabilized in 3.5.0 receives several enhancements: EventGenerator gains pause()/resume() methods (#3431) and a next_scheduled_time property (#3423). EventList adds a compact() method for cleaning up cancelled events (#3359). Monotonic time is now enforced in event scheduling (#3343), and a memory leak from strong references in EventGenerator is fixed (#3360).

Performance is improved for Event.__lt__ (#3336), EventList.peek_ahead (#3413), and EventList.__len__ (#3512), which all avoid unnecessary allocations.

Bug fixes include inconsistent state when assigning a CellAgent to a full cell (#3374), atomic agent addition in FixedCell (#3415), time rewind prevention (#3329), and removal of legacy model.steps usage from solara_viz (#3344).

Finally, tooltip support is added to the Altair visualization backend (#3392). Type hints are improved across the event system and AgentSet. Benchmarks are updated to use Scenario, and the Wolf-Sheep example is optimized (#3503).

What's Changed

🛠 Enhancements

🐛 Bugs fixed

⚡ Performance improvements

  • Optimize Event.__lt__ to avoid tuple allocation by @souro26 in #3336
  • Use generator in peek_ahead instead of list allocation by @souro26 in #3413
  • avoid temporary list allocation in EventList.len by @souro26 in #3512

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

  • Remove additional lines of code used for testing by @codebreaker32 in #3335
  • Add tests for execution ordering and cancellation invariants for EventList by @souro26 in #3353
  • Fix benchmark workflow permissions for fork PRs by @EwoutH in #3459

New Contributors

Full Changelog: v3.5.0...v3.5.1

Contributors

quaquel, wang-boyu, and 10 other contributors
Assets 2
Loading

Mesa 4.0 alpha 0

14 Mar 08:58
@EwoutH EwoutH
v4.0.0a0
d07108e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Mesa 4.0 alpha 0 Pre-release
Pre-release

Highlights

Mesa 4.0 alpha 0 (v4.0.0a0) is the first pre-release of the next major version of Mesa. It removes long-deprecated APIs, cleans up the core architecture, and introduces experimental timed actions for agents. This is an alpha release intended for early testing , expect rough edges and further breaking changes before the stable 4.0 release.

Breaking changes: deprecated APIs removed

Mesa 4.0 follows through on deprecations announced in Mesa 3.x by removing several legacy components:

  • seed parameter removed (#3318): The seed keyword argument to Model.__init__(), deprecated since Mesa 3.4, is gone. Use rng instead (or pass it through a Scenario). reset_rng has also been updated to reset model.random alongside the NumPy generator.
  • model.steps removed (#3328): The step counter has been replaced by model.time, completing the shift to a time-centric simulation model. All internal usages now reference model.time, and the step-wrapping machinery has been simplified accordingly.
  • batch_run removed (#3325): The batch_run function and all associated files have been removed. Users should manage experiment execution through Scenario and direct model control (see #3134 for background).
  • mesa.space removed (#3337): The legacy space module and agent.pos have been removed. Use mesa.discrete_space for grid-based and network models.
  • PropertyLayer and HasPropertyLayers mixin removed (#3340, #3432): The standalone PropertyLayer class is replaced by raw NumPy arrays stored directly on the grid as property_layers. Property access on cells now uses native property closures on a dynamic GridCell class, simplifying the internals.
  • Simulator classes removed (#3530): The Simulator, ABMSimulator, and DEVSimulator classes and the entire mesa.experimental.devs package have been removed, completing the deprecation cycle started in Mesa 3.5.0. Their functionality is covered by model.run_for(), model.run_until(), model.schedule_event(), and model.schedule_recurring(). Note that the core event system remains fully functional in mesa.time.

Experimental: Timed agent actions

Mesa 4.0a0 introduces an experimental Action system (#3461), giving agents a built-in concept of doing something over time. Actions integrate with Mesa's event scheduling for precise timing, support interruption with progress tracking, and can be resumed.

from mesa.experimental.actions import Action

class Forage(Action):
    def __init__(self, sheep):
        super().__init__(sheep, duration=5.0)

    def on_complete(self):
        self.agent.energy += 30

    def on_interrupt(self, progress):
        self.agent.energy += 30 * progress  # Partial credit

sheep.start_action(Forage(sheep))

Key features include:

  • Subclassable with on_start(), on_resume(), on_complete(), and on_interrupt(progress) hooks
  • Live-computed progress, remaining_time, and elapsed_time properties
  • Callable duration and priority for state-dependent values (e.g., duration=lambda a: a.distance / a.speed)
  • Interrupted actions remember progress and can be resumed, scheduling only the remaining duration
  • Agent integration via agent.start_action(), agent.interrupt_for(), agent.cancel_action(), and agent.is_busy

This is an experimental feature and may change in future releases. See the PR description for the full API reference and design rationale.

Event system improvements

The event scheduling system introduced in Mesa 3.5 receives several enhancements:

  • EventGenerator now supports pause() and resume() for temporarily suspending recurring events without terminating the generator (#3431)
  • A next_scheduled_time property on EventGenerator exposes the time of the next scheduled execution (#3423)
  • EventList gains a compact() method to clean up cancelled events and improve performance under heavy cancellation (#3359)
  • Event scheduling now enforces monotonic time, scheduling events in the past raises a clear error (#3343)
  • Memory leak from EventGenerator holding strong references is fixed via weak references (#3360)

Architecture and internals

  • Exception hierarchy (#3197): A new mesa.errors module introduces a base MesaError class with specific exceptions like CellNotEmptyError, replacing generic Exception usage. Related PRs tighten exception types across the codebase (#3380).
  • DiscreteSpace is now an abstract base class (#3387): Subclasses must implement spatial hooks like find_nearest_cell and _connect_cells, enforcing a consistent spatial API contract.
  • HasObservables renamed to HasEmitters (#3367): The reactive programming mixin now uses more precise terminology reflecting its role as a generic event emitter system.
  • Tooltip support in Altair backend (#3392): Agent data can now be shown on hover in Altair-based visualizations.

Performance improvements

Several targeted optimizations improve simulation performance:

  • Event.__lt__ avoids tuple allocation (#3336)
  • EventList.peek_ahead uses a generator instead of list allocation (#3413)
  • EventList.__len__ avoids temporary list allocation (#3512)
  • Continuous space agent removal is optimized (#3491)

This pre-release is meant for early testing of new features and providing us with feedback to guide Mesa 4.0 development. We don't recommend using it in production. Install with:

pip install -U --pre mesa

What's Changed

⚠️ Breaking changes

🧪 Experimental

🛠 Enhancements made

🐛 Bugs fixed

  • Fix unbounded growth of Model._event_generators by @EwoutH in #3317
  • fix: prevent time rewind in _advance_time by adding early return by @Krishsharma179 in #3329
  • Remove model.steps usage from solara_viz by @codebreaker32 in #3344
  • Enforce monotonic time invariant in event scheduling by @souro26 in #3343
  • Fix inconsistent state when assigning CellAgent to full cell by @souro26 in #3374
  • Fix: Enforce strict layout validation in Network space by @Nithurshen in #3386
  • fix: FixedCell setter atomically adds agent before updating reference (fixes #3411) by @Rishav23av in #3415
  • Fix checkout of untrusted code in benchmark.yml by @jackiekazil in #3438
  • Fixes a cache-invalidation bug for SignalingList by @codebreaker32 in #3486
  • Fix incorrect warnings and exception types in model.py and datacollection.py by @codebyNJ in #3434
  • Fix sliding window eviction crash in ModelDataSet by @ShreyasN707 in #3389
  • fix: InputText widget returns string seed causing model reset to fail by @R1patil in #3518

⚡ Performance improvements

🔍 Examples updated

📜 Documentation improvements

Read more

Contributors

jackiekazil, quaquel, and 16 other contributors
Loading

v3.5.0

15 Feb 17:53
@EwoutH EwoutH
v3.5.0
69ad0da
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.5.0

Highlights

Mesa 3.5.0 is a major feature release that introduces a public event scheduling API, stabilizes the event system, and lays the groundwork for Mesa 4.0 by deprecating several legacy patterns.

Public event scheduling and time advancement

The headline feature of 3.5.0 is a new public API for event scheduling and time advancement directly on Model (#3266). Instead of interacting with experimental Simulator classes, users can now schedule events and advance time with simple, expressive methods:

# Run the model for a duration
model.run_for(10)       # Advance 10 time units
model.run_until(50.0)   # Run until absolute time 50

# Schedule one-off events
model.schedule_event(callback, at=25.0)    # At absolute time
model.schedule_event(callback, after=5.0)  # Relative to now

# Schedule recurring events
from mesa.time import Schedule
model.schedule_recurring(func, Schedule(interval=10, start=0))

For traditional ABMs, model.run_for(1) is functionally equivalent to model.step(), but this generalizes naturally to event-driven and hybrid models. The mental model shifts from "execute step N" to "advance time, and whatever is scheduled will run."

Our new Agent activation and event scheduling tutorials cover this extensively (#3280).

Stabilized event scheduling system

The event scheduling system (EventList, Event, EventGenerator, Schedule, Priority) has been moved from mesa.experimental.devs to the new stable mesa.time module (#3276), making event-based simulation a first-class feature of Mesa. The new Schedule dataclass provides a clean way to define recurring timing patterns with interval, start, end, and count parameters (#3250). See our migration guide.

Deprecations toward Mesa 4.0

This release deprecates several legacy patterns to prepare for Mesa 4.0:

  • Simulator classes deprecated (#3277): ABMSimulator and DEVSimulator are replaced by the new Model methods above.
  • seed parameter deprecated (#3147): Use the rng parameter in Model.__init__() instead.
  • AgentSet sequence behavior deprecated (#3208): Indexing/slicing on AgentSet is deprecated in favor of the new to_list() method.
  • Portrayal dictionaries deprecated (#3144): Use AgentPortrayalStyle and PropertyLayerStyle instead.

See our migration guide for more detail.

Internal architecture improvements

Under the hood, Model now uses an EventGenerator internally for step scheduling (#3260), unifying the step mechanism with the broader event system. A new _HardKeyAgentSet (#3219, #3224) replaces WeakKeyDictionary-based storage for model-managed agent collections, eliminating weak reference overhead while preventing memory leaks through automatic downgrading when creating views. An AbstractAgentSet base class (#3210) formalizes the AgentSet interface. Discrete spaces now distinguish between logical cell indices and physical spatial positions (#3268), laying the foundation for stacked spaces by adding a Cell.position property.

New agent creation from DataFrames

Agents can now be created directly from a pandas DataFrame (#3199), mapping columns to constructor arguments:

agents = MyAgent.from_dataframe(model, df)

Experimental features

Several experimental features see significant progress in this release.

Scenarios

Explicit Scenario support (#3103, #3168) provides a structured way to define and manage computational experiments separately from model logic. Scenarios encapsulate parameter sets and can be used with SolaraViz (#3178), which automatically routes slider parameters to the correct Scenario or Model and reconstructs scenarios on reset.

class MyScenario(Scenario):
    density: float = 0.7

class MyModel(Model):
    def __init__(self, width=40, scenario=None):
        super().__init__(scenario=scenario)

# 'density' is auto-detected as a Scenario parameter
page = SolaraViz(MyModel(), model_params={"width": 40, "density": Slider("Density", 0.7, 0, 1, 0.1)})

Reactive model and data collection

The Model class is now reactive (#3212): model.time is observable, and signals are emitted when agents are registered or deregistered, enabling event-driven architectures. Building on this, a new DataRecorder (#3145, #3295) provides a decoupled, event-driven data collection system that separates what to collect (DataRegistry) from when and how to store it, with memory, SQLite, Parquet, and JSON backends.

self.recorder = DataRecorder(self)
self.data_registry.track_agents(self.agents, "agent_data", "wealth").record(self.recorder)
self.data_registry.track_model(self, "model_data", "gini").record(
    self.recorder, configuration=DatasetConfig(start_time=4, interval=2)
)

Other experimental progress includes improved meta-agent support with overlapping memberships (#3172).

Note that experimental features are in active development and can have (breaking) changes in every release.

What's Changed

⏳ Deprecations

  • Deprecate the agent and propertylayer portrayal dicts by @EwoutH in #3144
  • Deprecate seed parameter in favor of rng in Model by @quaquel in #3147
  • Deprecate AgentSet sequence behavior and add to_list() method by @codebyNJ in #3208
  • Deprecate Simulator classes, add migration guide entry by @EwoutH in #3277

🎉 New features added

🛠 Enhancements made

🧪 Experimental features

🐛 Bugs fixed

  • Fix batch_run Data Collection to Ensure Accuracy and Capture All Steps by @codebreaker32 in #3109
  • Fix network visualization bug: Replace array indexing with dictionary lookup by @codebyNJ in #3045
  • Fix TypeError in find_combinations when evaluation_func is None by @codebyNJ in #3112
  • Make create_meta_agent deterministic by @quaquel in #3183
  • Fix seed logic to ensure reproducibility by @codebreaker32 in #3192
  • Bugfix for pickling dynamically modified grids by @quaquel in #3217
  • check whether model reporter is a partial function by @wang-boyu in #3220
  • Prevent RecursionError and data loss in Cell/Grid deepcopy by @falloficarus22 in #3222
  • fix: update alliance_formation example to use AgentSet.to_list() by @souro26 in #3235
  • fix: preserve falsy evaluation values in find_combinations by @souro26 in #3237
  • Naming collision in meta-agents add_atrributes by @tpike3 in #3239
  • fix: update Altair tooltip type inference for compatibility by @souro26 in #3234
  • Fix Solara Altair dependency updates by @falloficarus22 in #3244

🔍 Examples updated

  • Update wolf-sheep example to use new event scheduling API by @EwoutH in #3278
  • Update Epstein Civil Violence model to use the new experimental Scenario class by @EwoutH in #3167

📜 Documentation improvements

  • Add deprecation of passing portrayal arguments to draw() methods to migration guide by @EwoutH in #3202
  • docs: clarify SolaraViz keyword-only model arguments by @Arjun-Sasi in #3044
  • docs: Add Mesa migration guide for AgentSet sequence behavior by @codebyNJ in #3218
  • docs: improve Boltzmann Wealth Model READM...
Read more

Contributors

quaquel, wang-boyu, and 14 other contributors
Loading

v3.5.0 beta 0

12 Feb 07:44
@EwoutH EwoutH
v3.5.0b0
4f399ca
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.5.0 beta 0 Pre-release
Pre-release

Highlights

Mesa 3.5.0 will be a major feature release that introduces a public event scheduling API, stabilizes the event system, and lays the groundwork for Mesa 4.0 by deprecating several legacy patterns.

Because of the size of this release, we're now first releasing beta release v3.5.0b0. Feedback and bug reports are welcome and appreciated!

Public event scheduling and time advancement

The headline feature of 3.5.0 is a new public API for event scheduling and time advancement directly on Model (#3266). Instead of interacting with experimental Simulator classes, users can now schedule events and advance time with simple, expressive methods:

# Run the model for a duration
model.run_for(10)       # Advance 10 time units
model.run_until(50.0)   # Run until absolute time 50

# Schedule one-off events
model.schedule_event(callback, at=25.0)    # At absolute time
model.schedule_event(callback, after=5.0)  # Relative to now

# Schedule recurring events
from mesa.time import Schedule
model.schedule_recurring(func, Schedule(interval=10, start=0))

For traditional ABMs, model.run_for(1) is functionally equivalent to model.step(), but this generalizes naturally to event-driven and hybrid models. The mental model shifts from "execute step N" to "advance time, and whatever is scheduled will run."

Stabilized event scheduling system

The event scheduling system (EventList, Event, EventGenerator, Schedule, Priority) has been moved from mesa.experimental.devs to the new stable mesa.time module (#3276), making event-based simulation a first-class feature of Mesa. The new Schedule dataclass provides a clean way to define recurring timing patterns with interval, start, end, and count parameters (#3250).

Deprecations toward Mesa 4.0

This release deprecates several legacy patterns to prepare for Mesa 4.0:

  • Simulator classes deprecated (#3277): ABMSimulator and DEVSimulator are replaced by the new Model methods above.
  • seed parameter deprecated (#3147): Use the rng parameter in Model.__init__() instead.
  • AgentSet sequence behavior deprecated (#3208): Indexing/slicing on AgentSet is deprecated in favor of the new to_list() method.
  • Portrayal dictionaries deprecated (#3144): Use AgentPortrayalStyle and PropertyLayerStyle instead.

See our migration guide for more detail.

Internal architecture improvements

Under the hood, Model now uses an EventGenerator internally for step scheduling (#3260), unifying the step mechanism with the broader event system. A new _HardKeyAgentSet (#3219, #3224) replaces WeakKeyDictionary-based storage for model-managed agent collections, eliminating weak reference overhead while preventing memory leaks through automatic downgrading when creating views. An AbstractAgentSet base class (#3210) formalizes the AgentSet interface.

New agent creation from DataFrames

Agents can now be created directly from a pandas DataFrame (#3199), mapping columns to constructor arguments:

agents = MyAgent.from_dataframe(model, df)

Experimental features

Several experimental features see significant progress: explicit Scenario support for computational experiments (#3103, #3168), a data registry for structured data collection (#3156), reactive model support (#3212), and improved meta-agent support with overlapping memberships (#3172).

Installation

Install this beta release with:

pip install --upgrade --pre mesa

What's Changed

⏳ Deprecations

  • Deprecate the agent and propertylayer portrayal dicts by @EwoutH in #3144
  • Deprecate seed parameter in favor of rng in Model by @quaquel in #3147
  • Deprecate AgentSet sequence behavior and add to_list() method by @codebyNJ in #3208
  • Deprecate Simulator classes, add migration guide entry by @EwoutH in #3277

🎉 New features added

🛠 Enhancements made

🧪 Experimental features

🐛 Bugs fixed

  • Fix batch_run Data Collection to Ensure Accuracy and Capture All Steps by @codebreaker32 in #3109
  • Fix network visualization bug: Replace array indexing with dictionary lookup by @codebyNJ in #3045
  • Fix TypeError in find_combinations when evaluation_func is None by @codebyNJ in #3112
  • Make create_meta_agent deterministic by @quaquel in #3183
  • Fix seed logic to ensure reproducibility by @codebreaker32 in #3192
  • Bugfix for pickling dynamically modified grids by @quaquel in #3217
  • check whether model reporter is a partial function by @wang-boyu in #3220
  • Prevent RecursionError and data loss in Cell/Grid deepcopy by @falloficarus22 in #3222
  • fix: update alliance_formation example to use AgentSet.to_list() by @souro26 in #3235
  • fix: preserve falsy evaluation values in find_combinations by @souro26 in #3237
  • Naming collision in meta-agents add_atrributes by @tpike3 in #3239
  • fix: update Altair tooltip type inference for compatibility by @souro26 in #3234
  • Fix Solara Altair dependency updates by @falloficarus22 in #3244

🔍 Examples updated

  • Update wolf-sheep example to use new event scheduling API by @EwoutH in #3278

📜 Documentation improvements

🔧 Maintenance

  • Fix pickling for scheduled events by serializing weak-referenced callbacks safely by @EwoutH in #3205
  • Unify event list between Model and Simulator by @EwoutH in #3204
  • Fix: Replace 'assert ValueError' with proper return None by @codebyNJ in #3189
  • Update model.py to replace AgentSet with _HardKeyAgentSet by @codebreaker32 in #3224
  • Use type(model.value).init in ModelCreator param check by @falloficarus22 in #3264
  • Stabilize event scheduling system from experimental to mesa.time by @EwoutH in #3276

New Contributors

Full Changelog: v3.4.1...v3.5.0b0

Contributors

quaquel, wang-boyu, and 14 other contributors
Loading

v3.4.2

23 Jan 12:25
@EwoutH EwoutH
v3.4.2
7287946
This commit was signed with the committer’s verified signature.
EwoutH Ewout ter Hoeven
GPG key ID: 1271C5568170579C
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.4.2

Highlights

Mesa 3.4.2 is a bugfix release that addresses a critical memory leak affecting all Mesa models.

A memory leak where model instances could never be garbage collected after agents were created was found (#3179). The root cause was the Agent._ids class attribute: a defaultdict that stored references to model instances to ensure unique_id values were unique per model. Because this was a class-level attribute persisting across the Python process, any model used as a key maintained a hard reference indefinitely, preventing cleanup of the model and all its associated objects even after going out of scope.

This bug has serious implications for users running multiple simulations or batch experiments, as each model instance would accumulate in RAM rather than being cleaned up, eventually exhausting available memory. The fix moves unique_id assignment from the Agent class into Model.register_agent(), with each model now maintaining its own agent_id_counter instance attribute (#3180). This eliminates persistent class-level references and allows proper garbage collection of model objects.

This release also includes a fix for PropertyLayer.from_data() to prevent unintended side effects (#3122), along with several small documentation improvements (#3104, #3124, #3127), and expanded contribution guidelines detailing Mesa's development philosophy and workflow (#3135).

Upgrading to Mesa 3.4.2 is highly recommended.

pip install --upgrade mesa

What's Changed

🐛 Bugs fixed

📜 Documentation improvements

Full Changelog: v3.4.1...v3.4.2

Contributors

quaquel, EwoutH, and Sonu0305
Loading

v3.4.1

10 Jan 09:46
@EwoutH EwoutH
v3.4.1
1bf47e7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.4.1

Highlights

Mesa 3.4.1 is a patch release with bug fixes, performance improvements, and documentation enhancements. This release addresses issues affecting data collection, memory management, and grid operations while introducing performance optimizations.

This release resolves several bugs affecting simulation accuracy: fixed multiple batch_run and DataCollector issues including agenttype_reporters support (#3095), sparse data collection (#2988), and proper handling of multiple collect() calls per step (#3058); resolved MultiGrid._empty_mask not updating correctly (#3019) and infinite loops in select_random_empty_cell() (#3014); fixed a memory leak in ContinuousSpace agent removal (#3031); corrected EventList.peek_ahead() chronological ordering (#3010); and ensured FixedAgent state consistency after removal (#3100).

Several optimizations improve Mesa's performance: PropertyLayer was refactored to implement the NumPy interface directly, enabling standard NumPy syntax (#3074); select_random_empty_cell() now uses vectorized NumPy operations instead of slow O(N) Python iteration (#3087); and Cell.is_empty/is_full checks were optimized to remove unnecessary O(n) copies (#3069).

The documentation received several improvements including version warnings for visualization tutorials (#2949), updated contribution guidelines (#3028), and implementation of Vale for consistent documentation style (#3022). The entire mesa.space module is now marked as maintenance-only (#3082), with users encouraged to use mesa.discrete_space for new projects. Generic type parameters were added to Agent, AgentSet, and Model classes to improve static type checking (#2885).

We're excited to welcome 9 new contributors to Mesa in this release! Thank you to everyone who contributed bug fixes, performance improvements, and documentation enhancements.

What's Changed

🛠 Enhancements made

🐛 Bugs fixed

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

New Contributors

Full Changelog: v3.4.0...v3.4.1

Contributors

quaquel, EwoutH, and 13 other contributors
Loading

v3.4.0

24 Dec 16:25
@EwoutH EwoutH
v3.4.0
3be1194
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.4.0

Highlights

The Mesa 3.4.0 feature release introduces universal time tracking, improves batch run reproducibility, and strengthens our deprecation policy. This release also requires Python 3.12+ and includes numerous bug fixes and quality-of-life improvements.

Universal simulation time with model.time

Mesa now provides a single source of truth for simulation time through the model.time attribute (#2903). Previously, time was fragmented across different components - simple models used model.steps as a proxy, while discrete event simulations stored time in simulator.time. This created complexity for features needing consistent time access.

Now all models have a model.time attribute that:

  • Automatically increments with each step (by 1.0)
  • Works seamlessly with discrete event simulators
  • Provides a consistent interface for data collection, visualization, and user code
# Basic usage - time auto-increments
model = Model()
model.step()
print(model.time)  # 1.0

# With discrete event simulation
simulator = DEVSimulator()
simulator.setup(model)
simulator.schedule_event_absolute(some_function, 2.5)
simulator.run_until(3.0)
print(model.time)  # 3.0

The old simulator.time still works but emits a deprecation warning.

Improved batch run reproducibility

The batch_run function has been updated to provide explicit control over random seeds across replications (#2841). Previously, using iterations with a fixed seed caused all iterations to use the same seed, producing identical results instead of independent replications.

The new rng parameter accepts either a single seed value or an iterable of seed values, giving you complete control over reproducibility:

rng = np.random.default_rng(42)
seed_values = rng.integers(0, sys.maxsize, size=(5,))

results = mesa.batch_run(
    MoneyModel,
    parameters=params,
    rng=seed_values.tolist(),  # Each iteration uses a different seed
)

The old iterations parameter is now deprecated and will be removed in Mesa 4.0. See the migration guide for details on updating your code.

Strengthened deprecation policy

Mesa now has a formal deprecation policy that ensures users have adequate time to migrate while allowing Mesa to evolve (#2900). A related change is that all deprecation warnings now use FutureWarning instead of DeprecationWarning (#2905), making them visible by default since DeprecationWarning is hidden for imported modules.

The policy guarantees:

  • New features must be available for at least one minor release before deprecating old ones
  • Documentation, migration guides, and examples must be updated before active deprecation
  • Breaking changes only occur in major version releases
  • Experimental features have more flexibility but still communicate changes

Organization name change

Mesa has migrated from the projectmesa to mesa organization on GitHub (#2880), (#2887), thanks to Daniel Langemann (@dlangemann) who generously transferred the mesa name to us. Our repositories are now accessible at github.com/mesa/mesa instead of github.com/projectmesa/mesa, signaling authority and maturity in a way that better reflects Mesa's position as the agent-based modeling framework in Python. GitHub automatically redirects old links, so existing URLs and git remotes continue to work seamlessly.

Python 3.12+ required

Mesa 3.4.0 drops support for Python 3.11 and now requires Python 3.12 or higher (#2842). This allows Mesa to use modern Python type parameter syntax and prepares the codebase for future Python features. Python 3.14 is now also fully tested in CI.

Other improvements

This release includes significant enhancements to the visualization system, including support for AgentPortrayalStyle in Altair components, improved property layer styling, and better error handling. The experimental cell space module has been removed in favor of the stable mesa.discrete_space module (#2969).

Numerous bugs were fixed, including issues with scalar color handling in matplotlib, empty cell collection indexing, and cell capacity handling. The test suite was reorganized to mirror the source module structure and now treats warnings as errors to prevent accumulation.

We welcome 10 new contributors to the Mesa project in this release! Thank you to everyone who contributed bug fixes, documentation improvements, and feature enhancements.

What's Changed

⏳ Deprecations

  • Replace DeprecationWarnings with FutureWarnings by @EwoutH in #2905
  • Fix: Auto-increment seed across batch_run iterations by @EwoutH in #2841

🎉 New features added

  • Add model.time as universal source of truth for simulation time by @EwoutH in #2903

🛠 Enhancements made

🐛 Bugs fixed

🔍 Examples updated

  • examples: Add Activation Order and Grid Type selectors to EpsteinCivilViolence by @Nithurshen in #2955

📜 Documentation improvements

🔧 Maintenance

  • Drop Python 3.11, require Python 3.12+ and update to modern type parameter syntax by @EwoutH in #2842
  • Pin Readthedocs build to Python 3.13 by @EwoutH in #2899
  • tests: Resolved "Missing Random Number Generator" warnings by @ShreyasN707 in #2911
  • tests: Update agent portrayals to use AgentPortrayalStyle by @Tejasv-Singh in #2909
  • Add Python 3.14 support to workflows and metadata by @EwoutH in #2843
  • Fix dtype/default_value mismatches in PropertyLayer tests to resolve UserWarnings by @ShreyasN707 in #2913
  • Replace deprecated np.bmat with np.block in Voronoi Delaunay triangulation by @EwoutH in #2915
  • Speed up CI by installing only Playwright chromium-headless-shell by @EwoutH in #2916
  • Add deprecation category to release notes by @EwoutH in #2914
  • test: Update simulator.time deprecation test to expect FutureWarning by @EwoutH in #2922
  • tests: Migrate PropertyLayer portrayals from dict to PropertyLayerStyle by @Tejasv-Singh in #2920
  • Fix matplotlib figure memory leak warning in tests by @EwoutH in #2924
  • Update organization name from projectmesa to mesa by @EwoutH in #2880
  • Update dict-based agent portrayals to use AgentPortrayalStyle in tests by @falloficarus22 in #2934
  • Remove experimental cell_space module and update references by @EwoutH in #2969
  • Fix PropertyLayer default value type mismatch warnings by @falloficarus22 in #2963
  • test: Replace deprecated iterations with rng in batch_run tests by @EwoutH in #2984
  • End of year cleanup by @EwoutH in #2971
  • Reorganize tests to mirror source module structure by @EwoutH in #2994
  • SolaraViz: move hooks before early return in ComponentsView by @EwoutH in #2925
  • Fix reproducibility warnings by adding explicit random parameters by @codebreaker32 in #2978
  • ci: treat warnings as errors to prevent accumulation by @EwoutH in #2926
  • Reject negative time_delta in schedule_event_relative by @Nithin9585 in #2999
  • CI: Add job that runs tests with pip pre-release dependencies by @EwoutH in #1852
  • CI: Split off separate coverage job by @EwoutH in #3005
  • Model: remove unreleased step_duration parameter by @EwoutH in #3007

New Contributors

Full Changelog: v3.3.1...v3.4.0

Contributors

quaquel, EwoutH, and 11 other contributors
Loading

v3.3.1

07 Nov 10:43
@EwoutH EwoutH
v3.3.1
2b27a10
This commit was signed with the committer’s verified signature.
EwoutH Ewout ter Hoeven
GPG key ID: 1271C5568170579C
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.3.1

Highlights

Mesa 3.3.1 is a maintenance release focused on bug fixes and documentation improvements following the major 3.3.0 visualization update.

This release addresses two critical visualization bugs affecting PropertyLayers on HexGrids and property layer data mapping across both Altair and Matplotlib backends.

The documentation received several important updates, including fixes to tutorial code examples, a new guide for Google Summer of Code contributors, and improved organization of the documentation structure. The migration guide has been updated to reflect the deprecation of the old agent_portrayal parameter in favor of the new AgentPortrayalStyle introduced in Mesa 3.3.0.

We're excited to welcome six new contributors to the Mesa project in this release! Thank you to everyone who contributed bug fixes, documentation improvements, and test coverage enhancements.

What's Changed

🐛 Bugs fixed

  • Fix visualization error for PropertyLayers on HexGrids. Add tranpose … by @flucco in #2868
  • Fix: Property layer data mapping for both Altair and Matplotlib backends by @Sahil-Chhoker in #2869
  • Fix: AgentSet initialization should not require explicit random number generator by @verisimilidude2 in #2789

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

New Contributors

Full Changelog: v3.3.0...v3.3.1

Contributors

quaquel, colinfrisch, and 8 other contributors
Loading

v3.3.0

06 Sep 20:14
@tpike3 tpike3
v3.3.0
6246a87

Choose a tag to compare

View all tags
v3.3.0

Highlights

The major highlight of release 3.3.0 is the introduction of a new and improved visualization module. This effort was @Sahil-Chhoker's Google Summer of Code project . The new module is backwards compatible and continues to use Solara. It has several new and improved features to include:

  • AgentPortrayalStyle: a more user-friendly way to specify agent portrayal
  • PropertyLayerStyle: Makes propertlayer and agent portrayal consistent.
  • SpaceRender: a new component for drawing spaces, agents and property layers with extensive customization
  • Improved support for Altair and Maplotlib
  • Multipage support (e.g., users can display simulation on one page and charts of the model on another)
  • Updated tutorials for visualization

You can read more about the update here

In addition, there were many other improvements to mesa, from bug fixes to improved CI/CD pipelines. Thanks to the PyCON sprints and the developers who supported Mesa!

What's Changed

🧪 Experimental features

🎉 New features added

🛠 Enhancements made

🐛 Bugs fixed

📜 Documentation improvements

🔧 Maintenance

Other changes

New Contributors

Full Changelog: v3.2.0...v3.3.0

Contributors

jackiekazil, catherinedevlin, and 10 other contributors
Loading

v3.2.0

08 May 09:37
@EwoutH EwoutH
v3.2.0
773ad91
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v3.2.0

Highlights

Mesa 3.2.0 is a feature-packed release, which stabilizes our discrete space, improves many of our visualisation capabilities, improves our tutorial organization, adds the experimental meta-agents, and includes other quality of life enhancements.

We also celebrate the publication of our peer-reviewed Mesa 3 paper in JOSS. See the updated Citing Mesa section on how to cite us.

Stabilization of Discrete Space

The experimental Cell Space system has been stabilized and is now available as mesa.discrete_space (#2610). This powerful spatial modeling framework enables cell-centric simulations with integrated PropertyLayers and improved agent movement capabilities. Key improvements include:

  • Support for dynamic modifications to discrete spaces during simulation (#2755)
  • Methods to add/remove cells and connections in real-time
  • Full integration with PropertyLayers (#2440) for representing environmental variables
  • Compatible with all examples and existing visualizations

The PropertyLayer itself has also been stabilized, allowing for efficient management of spatial environmental properties like terrain, resources, or any grid-based variables. Core examples including Schelling, Game of Life, Boltzmann Wealth, and Virus on Network have been updated to use the new discrete space system.

Enhanced Visualization Experience

The SolaraViz visualization system has received substantial upgrades:

  • Command Console (#2697): An interactive Python console embedded directly in the visualization, allowing real-time model inspection and manipulation
  • Asynchronous Updates (#2656): Visualization now runs in a separate thread, dramatically improving performance for complex models
  • Dark Mode (#2689): Support for Solara Dark theme, automatically matching system preferences
  • Improved Error Handling (#2747, #2753): Better visualization of errors with options to view detailed traceback information
  • Enhanced UI: Arrow key navigation (#2725), movable input field with auto-scroll (#2710), and other quality-of-life improvements
  • PropertyLayer visualisation in Altair (#2643): Support for visualising PropertyLayers using the Altair frontend in Solara.

Restructured and updated tutorial

Our introduction tutorial has been completely restructured (#2731). Instead of one huge notebook, the tutorial is now divided into smaller, focused modules that build progressively:

  • Creating Your First Model: Essential basics to get started
  • Adding Space: Learn how to use the new discrete space system
  • Collecting Data: Effectively gather model statistics
  • AgentSet: Master agent management techniques
  • Visualization: Series of modules covering basic to advanced visualization

Introducing Meta-Agents

Complex systems often have multiple levels of components. An organization is not one entity, but is made of departments, sub-departments, and people. A person is not a single entity, but it is made of micro biomes, organs and cells. A city is not a single entity, but it is made of districts, neighborhoods, buildings, and people. A forest comprises an ecosystem of trees, plants, animals, and microorganisms.

This reality is the motivation for meta-agents. It allows users to represent these multiple levels, where each level can have meta-agents with constituting agents.

To demonstrate meta-agents capability there are two examples:

  1. Dynamic meta-agent creation - Alliance formation, which shows emergent meta-agent formation through a game theoretic based alliance formation.
  2. Deliberate meta-agent creation - Warehouse model, which provides a pseudo warehouse model to demonstrate meta-agent functionality.

Let us know what you think on our Matrix Channel

Other improvements

  • AgentSet's agg method now supports multiple aggregation functions in a single call (#2743)
  • Many documentation improvements have been made based on feedback by our JOSS reviewers

What's Changed

🎉 New features added

🛠 Enhancements made

🔍 Examples updated

📜 Documentation improvements

  • docs: Split off the overview page, extend with spaces/activation by @EwoutH in #2673
  • docs: Add Roles section to CONTRIBUTING.md by @EwoutH in #2694
  • [JOSS] Docs: Clarify difference between core and user examples by @EwoutH in #2706
  • [JOSS] docs: Improve batch_run documentation for parallel processing by @EwoutH in #2707
  • JOSS Tutorial Fixes by @tpike3 in #2708
  • Clean-up old images, compress wolf-sheep image, remove version switch artifact by @EwoutH in #2717
  • docs: Update citation to JOSS article by @EwoutH in #2740
  • update intro tutorial discrete space by @tpike3 in #2731
  • docs: fix broken links to Readthedocs in example descriptions by @reyan-singh in #2757

🧪 Experimental features

🐛 Bugs fixed

New Contributors

Full Changelog: v3.1.4...v3.2.0

Contributors

quaquel, EwoutH, and 6 other contributors
Loading