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.

• Meta agents #2748

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

• Stabilize experimental Cell Space as mesa.discrete_space by @quaquel in #2610
• Feat: Added Command Console by @Sahil-Chhoker in #2697
• Stabilize PropertyLayer by @EwoutH in #2440

🛠 Enhancements made

• Visualisation: Add dark mode by @sanika-n in #2689
• Creating threads to update visualization asynchronously by @HMNS19 in #2656
• Movable Input Field with auto-scroll by @Sahil-Chhoker in #2710
• Feat: Added arrow key navigation by @Sahil-Chhoker in #2725
• added property_layer with altair by @sanika-n in #2643
• Debug option for errors in visualisation by @colinfrisch in #2747
• Debug option for errors in visualisation front end by @colinfrisch in #2753
• Add support for dynamic discrete spaces by @quaquel in #2755
• Support multiple functions in AgentSet agg method by @EwoutH in #2743

🔍 Examples updated

• Move boltzmann to cell spaces by @quaquel in #2680
• Move Game of life to cell space by @quaquel in #2681
• Move Schelling to discrete space by @quaquel in #2684
• Move virus_on_a_network to discrete_space by @quaquel in #2688
• Update boid_flockers example include flight direction by @sanika-n in #2696

📜 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

• Meta agents by @tpike3 in #2748

🐛 Bugs fixed

• Minor (bug) fixes to discrete_space by @quaquel in #2687
• Fixed Marker in mpl by @sanika-n in #2670

New Contributors

• @colinfrisch made their first contribution in #2747
• @reyan-singh made their first contribution in #2757

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

v3.1.5

Highlights

Mesa 3.1.5 is a maintenance release focused on improving documentation and cleaning up our resources. This update includes no breaking changes and is compatible with previous 3.1.x releases.

The documentation improvements include enhanced explanations for batch run parallel processing, a significantly expanded overview section covering spaces, property layers and time advancement methods with practical code examples, and a clearer installation guide detailing what the optional [rec] dependencies provide. We've also improved our examples documentation to better distinguish between core and user-contributed examples, and added a new "Roles" section to the contributing guide that outlines the project's community structure and progression paths.

On the maintenance side, we've cleaned up unused images and compressed existing ones, reducing the repository size by over 2MB and distribution size from 3.2MB to 1.2MB.

We recommend all users update to this release for the improved documentation.

What's Changed

📜 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
• Clean-up old images, compress wolf-sheep image, remove version switch artifact by @EwoutH in #2717

Full Changelog: v3.1.4...v3.1.5

v3.1.4

Highlights

This release contains various improvements and bugfixes to the matplotlib-based visualization of spaces. Hexgrids are now fully supported, including property layers. In making this possible, various minor bugs were encountered and also fixed. In addition to the visualization improvements, there are various minor convenience improvements to the docs.

What's Changed

🛠 Enhancements made

• Fixed hex-space draw function to avoid overlaps by @Sahil-Chhoker in #2609
• Fix: Property layer visualization for HexGrid by @Sahil-Chhoker in #2646
• Enhance DataCollector to validate model_reporters functions by @peter-kinger in #2605
• Implemented post_process in Altair based components by @sanika-n in #2641

🐛 Bugs fixed

• bugfix for draw_property_layer by @quaquel in #2639
• Uses array for hex grid property layer fix by @Sahil-Chhoker in #2651
• Update Binder environment to use latest Mesa version (#2652) by @aarav-shukla07 in #2655
• Change Hexgrid._connect_cells_2d to use x,y coordinates by @quaquel in #2632

🔍 Examples updated

• Added property layer viz to sugarscape by @sanika-n in #2653
• added color-bar for spice by @sanika-n in #2622

📜 Documentation improvements

• remove any reference to using --pre by @quaquel in #2618
• Updated Docs by @sanika-n in #2624
• Fixed 404 error for Examples Tab in Introductory Tutorial (#2662) by @aarav-shukla07 in #2664
• Documentation by @Spartan-71 in #2630
• Adding a copy option at the top of the code written in the docs by @PrashantChoudhary13579 in #2628
• Adding Mesa Extension page by @PrashantChoudhary13579 in #2627

🔧 Maintenance

• remove remnants of mesa cli by @quaquel in #2617
• benchmarks.yml: Install SciPy and use uv for pip install by @EwoutH in #2633
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in #2659

New Contributors

• @PrashantChoudhary13579 made their first contribution in #2628
• @aarav-shukla07 made their first contribution in #2655
• @peter-kinger made their first contribution in #2605

Full Changelog: v3.1.3...v3.1.4

v3.1.3

Highlights

Mesa 3.1.3 introduces a major experimental reimplementation of Mesa's continuous space, providing an intuitive agent-centric API and significant performance improvements. The new implementation supports n-dimensional spaces and offers streamlined methods for agent movement and neighbor calculations.

New Continuous Space Features

• Agent-centric movement API similar to cell spaces
• Efficient neighbor calculations and position updates
• Support for n-dimensional spaces
• Improved memory management with dynamic array resizing

Here's a quick look at the new API:

# Create a 2D continuous space
space = ContinuousSpace(
    dimensions=[[0, 1], [0, 1]],
    torus=True,
    random=model.random
)

# Create and position an agent
agent = ContinuousSpaceAgent(space, model)
agent.position = [0.5, 0.5]

# Move agent using vector arithmetic
agent.position += [0.1, 0.1]

# Get neighbors within radius
neighbors, distances = agent.get_neighbors_in_radius(radius=0.2)

# Find k nearest neighbors
nearest, distances = agent.get_nearest_neighbors(k=5)

The new implementation particularly benefits models requiring frequent position updates and neighbor queries, such as flocking simulations or particle systems. See PR #2584 and the API documentation for more details. We would love to get feedback on the new Continuous Space in #2611.

Other improvements in this release include consistent visualization behavior across space types with the reimplementation of draw_voronoi #2608, and a new render interval slider for controlling visualization update frequency in SolaraViz, which helps improve performance when working with complex visualizations #2596. We've also fixed a bug affecting random number generation determinism when using Model(seed=something), ensuring both model.random and model.rng now behave consistently when seeded with the same initial value #2598.

What's Changed

🧪 Experimental features

• Reimplementation of Continuous Space by @quaquel in #2584

🛠 Enhancements made

• reimplementation of draw_voroinoi by @quaquel in #2608
• Add render interval slider to control visualization update frequency by @HMNS19 in #2596

🐛 Bugs fixed

• Bugfix for non deterministic rng behavior by @quaquel in #2598

🔍 Examples updated

• Clarify ContinuousSpace.get_neighbors behavior with multiple agents at same position by @quaquel in #2599

New Contributors

• @HMNS19 made their first contribution in #2596

Full Changelog: v3.1.2...v3.1.3

v3.1.2

Highlights

Mesa v3.1.2 is a patch release containing updates to our wolf-sheep, shelling and prisoner's dilemma example models and improving documentation in the tutorials and visualisation docstring. No functional changes to the core library were made.

What's Changed

🔍 Examples updated

• examples/wolf_sheep: Don't allow dumb moves by @EwoutH in #2503
• Added homophily ratio in basic schelling example by @vbv-shm in #2520
• examples: Update pd_grid analysis.ipynb to use new spaces by @quaquel in #2553

📜 Documentation improvements

• Corrected a few errors in Intro tutorial by @sanika-n in #2583
• Small draw_space docstring fix by @quaquel in #2554
• fix: model name in visualization tutorial by @Sahil-Chhoker in #2591

New Contributors

• @vbv-shm made their first contribution in #2520
• @sanika-n made their first contribution in #2583

Full Changelog: v3.1.1...v3.1.2

v3.1.1

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

• bug fixes for draw_property_layers by @quaquel in #2548

🔍 Examples updated

• Wolf-sheep to use create_agent by @quaquel in #2543
• Shift sugarscape example to using create_agent by @quaquel in #2544
• Fix: Schelling Model Neighbor Similarity Calculation by @Sahil-Chhoker in #2518
• Change pd_grid example to use create_agents by @quaquel in #2545
• Switch sugarscape to using property layers by @quaquel in #2546

📜 Documentation improvements

• Updated docs and check_model param by @nissu99 in #2510
• Update tutorials to use create_agents and rng.integers by @DarshPareek in #2541

New Contributors

• @nissu99 made their first contribution in #2510
• @DarshPareek made their first contribution in #2541

Full Changelog: v3.1.0...3.1.1

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

• Add logging to MESA by @quaquel in #2506
• Add create_agents factory method to Agent by @quaquel in #2351

🔍 Examples updated

• Add seed control to all examples by @quaquel in #2496

📜 Documentation improvements

• doc fix for pip install error on mac by @quaquel in #2508
• Refactored docs for Introductory Tutorial by @Spartan-71 in #2511
• Add module-level docstring to experimental features by @EwoutH in #2532

🔧 Maintenance

• Remove deprecated time module by @EwoutH in #2476
• Drop support for Python 3.10, require Python >= 3.11 by @EwoutH in #2474
• Remove deprecated functionality by @EwoutH in #2483
• Remove visualization modules from mesa.experimental by @quaquel in #2495
• Cleanup two occurrences of removed scheduler by @EwoutH in #2499
• move _setup_agent_registration into Model.__init__ by @quaquel in #2501
• remove devs related examples from devs/examples by @quaquel in #2507
• added empty iterable checks and updated tests by @Sahil-Chhoker in #2523
• Fix: running Mesa in Docker with Schelling model by @AdamZh0u in #2524

New Contributors

• @Spartan-71 made their first contribution in #2511
• @Sahil-Chhoker made their first contribution in #2523
• @AdamZh0u made their first contribution in #2524

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

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

• Only set model_parameters once by @Corvince in #2505

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

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

• test app init of examples by @Corvince in #2491

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

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

• Bugfixes to DEVS by @quaquel in #2478
• Support simulators in SolaraViz by @quaquel in #2470

🛠 Enhancements made

• issue a user warning if random is None by @quaquel in #2479

🔍 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

• @eltociear made their first contribution in #2480

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