Skip to content

Releases: projectmesa/mesa

v3.1.1

14 Dec 16:25
@EwoutH EwoutH
v3.1.1
393f6a0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.1.1 Latest
Latest

Highlights

Mesa 3.1.1 is a maintenance release that includes visualization improvements and documentation updates. The key enhancement is the addition of an interactive play interval control to the visualization interface, allowing users to dynamically adjust simulation speed between 1ms and 500ms through a slider in the Controls panel.

Several example models were updated to use Mesa 3.1's recommended practices, particularly the create_agents() method for more efficient agent creation and NumPy's rng.integers() for random number generation. The Sugarscape example was modernized to use PropertyLayers.

Bug fixes include improvements to PropertyLayer visualization and a correction to the Schelling model's neighbor similarity calculation. The tutorials were also updated to reflect current best practices in Mesa 3.1.

What's Changed

🎉 New features added

  • Add Interactive Play Interval Control to Mesa Visualization by @AdamZh0u in #2540

🐛 Bugs fixed

🔍 Examples updated

📜 Documentation improvements

New Contributors

Full Changelog: v3.1.0...3.1.1

Contributors

quaquel, AdamZh0u, and 3 other contributors
Assets 2
Loading

v3.1.0

04 Dec 19:39
@EwoutH EwoutH
v3.1.0
03ce5f0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.1.0

Highlights

With Mesa 3.1.0 we're back on our regular release schedule after the big Mesa 3.0 release, with some exciting new features.

This release adds experimental support for Observables and Computed, enabling a more reactive and responsive programming model for agent-based simulations. The new Observable and Computable classes allow developers to declaratively define attributes that automatically emit signals when their values change, and compute derived values that update dynamically. This lays the groundwork for more advanced event handling and data visualization features in future releases (#2291).

The experimental cell space module has been updated with full support for n-dimensional property layers. These allow agents to easily interact with and modify spatial properties of the environment, such as terrain, resources, or environmental conditions. The new implementation provides a more intuitive attribute-based API and ensures tight integration with the cell space architecture (#2512).

Mesa now includes built-in support for logging using the standard Python logging module. This provides developers with a flexible and powerful way to add structured diagnostic and debug output to their simulations, without the need for custom logging solutions. The logging system is integrated throughout the library, including the new SolaraViz visualization system (#2506).

Creating multiple agents with varying initialization parameters is now significantly easier with the new Agent.create_agents class method. This factory function supports both uniform and per-agent parameters, simplifying the code required to set up a simulation with a large number of heterogeneous agents (#2351).

In addition to the major new features, this release includes a number of smaller enhancements and bug fixes that improve the overall developer experience. These include removing deprecated functionality, cleaning up examples, and addressing various edge cases reported by the community. Mesa 3.1 requires Python 3.11 or higher.

What's Changed

🧪 Experimental features

  • Add support for Observables to MESA by @quaquel in #2291
  • Add full support for property layers to cell spaces by @quaquel in #2512

🎉 New features added

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

New Contributors

Full Changelog: v3.0.3...v3.1.0

Contributors

quaquel, EwoutH, and 3 other contributors
Assets 2
Loading

v3.0.3

13 Nov 23:29
@EwoutH EwoutH
v3.0.3
9543815
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.0.3

Highlights

A small bugfix release that fixes two bugs.

What's Changed

🧪 Experimental features

  • cell_space: Allow CellCollection to be empty by @EwoutH in #2502

🐛 Bugs fixed

Full Changelog: v3.0.2...v3.0.3

Contributors

Corvince and EwoutH
Assets 2
Loading

v3.0.2

11 Nov 14:52
@EwoutH EwoutH
v3.0.2
8da32e2
This commit was signed with the committer’s verified signature.
EwoutH Ewout ter Hoeven
GPG key ID: 771DD7C82B72798D
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.0.2

Highlighst

Mesa 3.0.2 is a small follow-up patch release to Mesa 3.0, in which we fixed a lot of small bugs in the example models their visualisation, and improved their testing.

What's Changed

🐛 Bugs fixed

  • allow components as a positional argument again by @Corvince in #2488

🔍 Examples updated

  • examples: Add required components keyword by @EwoutH in #2485
  • examples: Fix boid_flockers viz by @EwoutH in #2492
  • examples: Fix schelling viz by @EwoutH in #2490
  • example: Add input sliders to Sugerscape viz by @EwoutH in #2487
  • examples/gol: Add initial fraction alive, add sliders to viz by @EwoutH in #2489

🔧 Maintenance

Full Changelog: v3.0.1...v3.0.2

Contributors

Corvince and EwoutH
Assets 2
Loading

v3.0.1

11 Nov 10:16
@EwoutH EwoutH
v3.0.1
7430eca
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.0.1

Highlights

After our huge 3.0.0 release, Mesa 3.0.1 follows up with two improvements to experimental features, examples and docs.

What's Changed

🧪 Experimental features

🛠 Enhancements made

🔍 Examples updated

  • Integrate benchmarks and example models by @EwoutH in #2473

📜 Documentation improvements

  • docs/tutorial: Replace scheduler in MoneyModel by @EwoutH in #2475
  • docs: update migration_guide.md by @eltociear in #2480
  • Update some DeprecationWarnings to note they are removed in Mesa 3.1 by @EwoutH in #2481

New Contributors

Full Changelog: v3.0.0...v3.0.1

Contributors

quaquel, EwoutH, and eltociear
Assets 2
Loading

v3.0.0

09 Nov 08:07
@EwoutH EwoutH
v3.0.0
743f830
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v3.0.0

Highlights

After our most extensive pre-release program ever, we’re proud to release Mesa 3.0 as stable. Mesa 3.0 brings major improvements to agent-based modeling, making it more intuitive and powerful while reducing complexity. This release modernizes core functionalities and introduces new capabilities for both beginners and advanced users.

Streamlined agent management

The centerpiece of Mesa 3.0 is its new agent management system. Agents are now automatically tracked and assigned unique IDs, eliminating common boilerplate code. The new AgentSet functionality provides an elegant and flexible way to work with agents, for example:

# Find agents meeting specific criteria
wealthy_agents = model.agents.select(lambda a: a.wealth > 1000)

# Group and analyze agents
grouped = model.agents.groupby("state")
state_stats = grouped.agg({
     "count": len,
     "avg_age": ("age", np.mean),
     "total_wealth": ("wealth", sum)
 })

# Activate agents in different patterns
model.agents.shuffle_do("step")  # Random activation
model.agents.select(lambda a: a.energy > 0).do("move")  # Conditional activation

The AgentSet provides powerful methods for filtering, grouping, and analyzing agents, making it easier to express complex model logic. Each model automatically maintains an AgentSet containing all agents (model.agents) and separate AgentSets for each agent type (model.agents_by_type). See the full AgentSet docs here.

Modern Visualization with SolaraViz

Mesa 3.0's new experimental visualization system, SolaraViz, provides a modern, interactive interface for model exploration:

from mesa.visualization import SolaraViz, make_space_component, make_plot_component

visualization = SolaraViz(
    model,
    [
        make_space_component(agent_portrayal),
        make_plot_component(["population", "average_wealth"]),
        lambda m: f"Step {m.steps}: {len(m.agents)} agents"  # Custom text component
    ],
    model_params=parameter_controls
)

Key visualization features:

  • Interactive browser-based interface with real-time updates
  • Support for both grid-based and network models
  • Visualization of PropertyLayers and hexagonal grids
  • Custom components using Matplotlib or text
  • Improved performance and responsiveness

Check out the Visualization Tutorial to get started.

Note: SolaraViz is in active development. We might make API breaking changes between Mesa 3.0 and 3.1.

Enhanced data collection

The DataCollector now supports collecting different metrics for different agent types, using agenttype_reporters:

self.datacollector = DataCollector(
    model_reporters={"total_wealth": lambda m: m.agents.agg("wealth", sum)},
    agent_reporters={"age": "age", "wealth": "wealth"},
    agenttype_reporters={
        Predator: {"kills": "kills_count"},
        Prey: {"distance_fled": "total_flight_distance"}
    }
)

Experimental features

Mesa 3.0 introduces several experimental features for advanced modeling:

These experimental features are in active development and might break API between releases.

Breaking changes

See our Mesa 3.0 migration guide for a full overview.

If you want to move existing models from Mesa 2.x to 3.0, there are a few things you have to change.

  1. Models must explicitly initialize the Mesa base class:
class MyModel(mesa.Model):
    def __init__(self, n_agents, seed=None):
        super().__init__(seed=seed)  # Required in Mesa 3.0
  1. Agents are created without manual ID assignment:
# Old
agent = MyAgent(unique_id=1, model=self)
# New
agent = MyAgent(model=self)
  1. Scheduler replacement with AgentSet operations:
# Old (RandomActivation)
self.schedule = RandomActivation(self)
self.schedule.step()

# New
self.agents.shuffle_do("step")

# Old (SimultaneousActivation)
self.schedule = SimultaneousActivation(self)
self.schedule.step()

# New
self.agents.do("step")
self.agents.do("advance")

Furthermore:

  • Steps counter automatically increments
  • mesa.flat namespace removed
  • Python 3.10+ required
  • Reserved model variables (agents, steps, etc.) protected
  • Simplified DataCollector initialization
  • Old visualization system replaced by SolaraViz

Getting Started

Install Mesa 3.0:

pip install --upgrade mesa

If building a new model, we recommend checking out the updated Mesa Overview and Introductory Tutorial.

For updating existing models, we recommend upgrading in steps:

  1. Update to latest Mesa 2.x
  2. Address deprecation warnings
  3. Upgrade to Mesa 3.0
  4. Replace schedulers with AgentSet functionality

A detailed migration guide is available to help moving to Mesa 3.0. For questions or support, join our GitHub Discussions or Matrix Chat.

We would love to hear what you think about Mesa 3.0! Say hello here and leave any feedback on 3.0 here.

What's Changed

⚠️ Breaking changes

  • Remove mesa.flat namespace by @rht in #2091
  • breaking: Remove visualization_old (mesa-viz-tornado) by @rht in #2133
  • viz: Combine code for rendering in browser and Jupyter by @rht in #2180
  • breaking: Add dependencies argument to custom space_drawer by @rht in #2209
  • Require Mesa models to be initialized with super().__init__() by @EwoutH in #2218
  • Allow AgentSet.do() to take Callable function by @quaquel in #2219
  • Change warning when setting model.agents to error by @EwoutH in #2225
  • model: Automatically increase steps counter by @EwoutH in #2223
  • move solara_viz back to experimental by @Corvince in #2278
  • track unique_id automatically by @quaquel in #2260
  • update Agent.init to remove deprecation warning by @quaquel in #2328
  • replace model with random in AgentSet init by @quaquel in #2350
  • remove cookiecutter by @quaquel in #2421
  • Viz: Refactor Matplotlib plotting by @quaquel in #2430
  • api reorganization by @quaquel in #2447
  • Deprecate initialize_data_collector by @EwoutH in #2327

🧪 Experimental features

🎉 New features added

Read more

Contributors

jackiekazil, rht, and 10 other contributors
Assets 2
Loading

Mesa 3.0 Release Candidate

06 Nov 08:42
@EwoutH EwoutH
v3.0.0rc0
0c6dc35
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
Mesa 3.0 Release Candidate Pre-release
Pre-release

Highlights

We're releasing the Mesa 3.0 Release Candidate, ready for final testing before we release Mesa 3.0 later this week!

In this last 3.0 pre-release, the visualisation has been thoroughly updated, with a brand new API. Visualizing the experimental Cell Space, including PropertyLayers and hexogonal grids, is now also supported.

We're still working very active on the visualisation, so we have marked that experimental for Mesa 3.0. We will stabilize SolaraViz in Mesa 3.1.

Any feedback and last-minute bug reports are welcome here.

What's Changed

⚠️ Breaking changes

🧪 Experimental features

  • Mark SolaraViz as experimental for Mesa 3.0 by @EwoutH in #2459

🛠 Enhancements made

🐛 Bugs fixed

🔍 Examples updated

📜 Documentation improvements

  • Update wolf-sheep png and fix typo in file name by @quaquel in #2444
  • Include main examples readme in docs by @quaquel in #2448
  • remove how-to guide and update docs in places by @quaquel in #2449

🔧 Maintenance

  • remove deprecated HexGrid class by @quaquel in #2441
  • rename make_plot_measure to make_plot_component and add some kwargs by @quaquel in #2446

Full Changelog: v3.0.0b2...v3.0.0rc0

Contributors

quaquel, Corvince, and EwoutH
Assets 2
Loading

Mesa 3.0 beta 2

26 Oct 21:06
@EwoutH EwoutH
v3.0.0b2
e525de3
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
Mesa 3.0 beta 2 Pre-release
Pre-release

Highlights

Mesa 3.0 beta 2 includes major work on the example models, docs, a new tutorial and visualisation.

The included example models are now part of the Mesa package itself and directly importable, using:

from mesa.examples import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, ...

The advanced examples were also restructured and cleaned up.

The tutorial was completely rewritten for Mesa 3.0, including it's latest features and practices. Many of our other docs also received some love, and almost everything is now ready for Mesa 3.0.

A new feature to remove all agents from the model was added, and the visualisation now supports drawing the experimental discrete spaces in both matplotlib and altair. All agents which are in a space can now conveniently be accessed with .agents.

The rarely used mesa startproject cookiecutter feature was removed. We updated our best-practice guide to include how to structure a modern Mesa project, which is now very straightforward.

What's Changed

⚠️ Breaking changes

🧪 Experimental features

🎉 New features added

  • remove_all_agents method added to model by @quaquel in #2394
  • Pass through model.rgn in agent analogous to model.random by @quaquel in #2400
  • add agents property to all spaces by @quaquel in #2418

🛠 Enhancements made

🐛 Bugs fixed

🔍 Examples updated

  • refactor: Simplify Schelling code by @rht in #2353
  • Move examples into mesa by @Corvince in #2387
  • Explicitly test basic examples by @quaquel in #2390
  • Make example import absolute by @quaquel in #2402
  • Cleanup and restructure EpsteinCivilViolence and PdGrid examples by @EwoutH in #2408
  • Reorganize advanced examples: wolf_sheep and sugarscape_g1mt by @quaquel in #2410
  • reactivate ruff for advanced examples and include them in tests by @quaquel in #2414

📜 Documentation improvements

🔧 Maintenance

  • Add empty pull_request_template.md to enable PR template chooser by @EwoutH in #2409

Full Changelog: v3.0.0b1...v3.0.0b2

Contributors

rht, quaquel, and 3 other contributors
Assets 2
Loading

Mesa 3.0 beta 1

18 Oct 04:00
@jackiekazil jackiekazil
v3.0.0b1
d2df9d4
Compare
Choose a tag to compare
Mesa 3.0 beta 1 Pre-release
Pre-release

Highlights

Mesa 3.0 beta 1 is our last beta release before the Mesa 3.0 stable release. We are restructuring our examples and have move 9 core examples from mesa-examples to mesa itself (#2358). The 5 basic examples are now directly importable (#2381):

from examples.basic import BoidFlockers, BoltzmannWealthModel, ConwaysGameOfLife, Schelling, VirusOnNetwork

The 5 basic examples will always use stable Mesa features, we are also working on 4 more advanced example which can also include experimental features.

All our core examples can now be viewed in the examples folder. mesa-examples will continue to exists for user showcases. We're also working on making the examples visible in the ReadtheDocs (#2382) and on an website (mesa-examples#139). Follow all our work on the examples in this tracking issue #2364.

Furthermore, the visualizations are improved by making visualization elements scalable and more clearly labeling the plots, and the Model now has an rng argument for an SPEC 7 compliant NumPy random number generator (#2352).

What's Changed

⚠️ Breaking changes

  • replace model with random in AgentSet init by @quaquel in #2350

🧪 Experimental features

  • cell space: Add convenience properties for grid width and height by @quaquel in #2348
  • Bugfix for deepcopy / pickling discrete spaces by @quaquel in #2378

🎉 New features added

  • Move core example models back (v2) by @EwoutH in #2358
  • Add Model.rng for SPEC-7 compliant numpy random number generation by @quaquel in #2352

🛠 Enhancements made

🐛 Bugs fixed

  • experimental init: Fix Solara import by making it lazy by @EwoutH in #2357
  • fix: pass model.random to schedulers by @quaquel in #2359
  • fix: register agent after creating unique_id and pos attributes by @wang-boyu in #2368
  • solara: viz tutorial: fix histogram code by @Corvince in #2379

🔍 Examples updated

📜 Documentation improvements

🔧 Maintenance

Full Changelog: v3.0.0b0...v3.0.0b1

Contributors

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

Mesa 3.0 beta 0

05 Oct 07:44
@EwoutH EwoutH
v3.0.0b0
2cdbcb6
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
Mesa 3.0 beta 0 Pre-release
Pre-release

Highlights

We're proud to release the first Mesa 3.0 beta! This pre-release announces that we're ready for Mesa 3.0 to be tested by all our regular users. We try to not making breaking changes anymore, but focus on resolving bugs and imperfections.

In this beta, not so much has changed as in the alphas (we're stabilizing, that's a good sign), but there are still a few notable things:

  • Agents now have to be initialized without their unique_id. See #2328 and the Migration guide.
  • PropertyLayers can now be visualized! See #2336 for details and some examples, and mesa-examples#214 as a simple example model.
  • We reduced the core dependencies of Mesa, so that's a lighter and simpler install. You can now use extras to install the dependencies, for example add [viz] to install all visualisation dependencies: pip install -U --pre mesa[viz]. See #2265 for details.
  • The Mesa Overview as fully updated for 3.0. We highly recommend reading though it!
  • We made some more progress on the experimental Cell Space, adding movement and integrating the PropertyLayer. Among others, Agents have nu initial movement capabilities for grids. Development continues during the betas and

We plan to release one or two more beta's in the coming weeks, and tag a release candidate and Mesa 3.0 late October. In the v3.0 milestone are the critical items on our todo-list.

You can install this pre-release as usual with:

pip install --upgrade --pre mesa

We're very curious what you think, try it out and ask any questions or share any feedback here!

What's Changed

⚠️ Breaking changes

  • update Agent.__init__ to remove deprecation warning by @quaquel in #2328

🎉 New features added

🧪 Experimental features

🛠 Enhancements made

  • Reduce core dependencies, split in optional dependencies by @EwoutH in #2265

🐛 Bugs fixed

  • viz: stop running and disable buttons when model.running is False by @wang-boyu in #2332

📜 Documentation improvements

  • docs: Update overview for Mesa 3.0 by @EwoutH in #2317
  • Readthedocs: Add version switch and update URL by @EwoutH in #2324

🔧 Maintenance

  • tests: Resolve warnings by removing scheduler and updating arguments by @EwoutH in #2329
  • add super call to Model and remove self.schedule by @quaquel in #2334

Other changes

Full Changelog: v3.0.0a5...v3.0.0b0

Contributors

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