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

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:

• Cell Space with integrated PropertyLayers and improved agent movement capabilities
• Voronoi grid implementation
• Event-scheduling simulation capabilities

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

2. Agents are created without manual ID assignment:

# Old
agent = MyAgent(unique_id=1, model=self)
# New
agent = MyAgent(model=self)

3. 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

• devs/eventlist: Add repr method to print EventList pretty by @EwoutH in #2195
• Voronoi Tessellation based Discrete Space by @vitorfrois in #2084
• Make cell connections public and named by @Corvince in #2296
• Update to CellCollection.select by @quaquel in #2307
• Have a dedicated neighborhood property and a get_neighborhood method on Cell by @quaquel in #2309
• Encapsulate cell movement in properties by @quaquel in #2333
• experimental: Integrate PropertyLayers into cell space by @EwoutH in #2319
• Generalize CellAgent by @Corvince in #2292
• cell space: Add convenience properties for grid width and height by @quaquel in #2348
• Bugfix for deepcopy / pickling discrete spaces by @quaquel in #2378
• Add support for drawing discrete grids by @quaquel in #2386
• Altair spaces by @quaquel in #2397
• Mark SolaraViz as experimental for Mesa 3.0 by @EwoutH in #2459

🎉 New features added

• Set JupyterViz as stable by @rht in #2090
• Add AgentSet.groupby by @quaquel in #2220
• AgentSet: Add set method by @EwoutH in #2254
• AgentSet: Add agg method by @EwoutH in #2266
• Implement new SolaraViz API by @Corvince in #2263
• GroupBy: Add count and agg methods by @EwoutH in #2290
• datacollector: Allow collecting data from Agent (sub)classes by @EwoutH in #2300
• Add optimized shuffle_do() method to AgentSet by @EwoutH in #2283
• Visualize PropertyLayers by @EwoutH in https://github...

Mesa 3.0 Release Candidate

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

• Viz: Refactor Matplotlib plotting by @quaquel in #2430
• api reorganization by @quaquel in #2447

🧪 Experimental features

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

🛠 Enhancements made

• expand ax.scatter kwargs that can be used by @quaquel in #2445

🐛 Bugs fixed

• Fix #2452 - handle solara viz model params better by @Corvince in #2454
• Update MoneyModel.py by @quaquel in #2458

🔍 Examples updated

• Updates to Epstein example by @quaquel in #2429
• Update examples to use updated space drawing by @quaquel in #2442

📜 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

Mesa 3.0 beta 2

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

• remove cookiecutter by @quaquel in #2421

🧪 Experimental features

• Add support for drawing discrete grids by @quaquel in #2386
• Altair spaces by @quaquel in #2397

🎉 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

• update_tutorial environment by @tpike3 in #2411

🐛 Bugs fixed

• Fix for mistaken removal of _draw_grid by @quaquel in #2398
• fixes weakref bug in shuffe_do by @quaquel in #2399

🔍 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

• Include examples in readthedocs (port) by @EwoutH in #2392
• Update into_tutorial by @tpike3 in #2372
• Update Schelling Readme.md by @quaquel in #2406
• Update Conway example by @quaquel in #2403
• Boltzman readme by @quaquel in #2405
• Update Readme.md of Boid flockers by @quaquel in #2404
• add advanced examples to rtd by @quaquel in #2413
• Tutorial Improvements by @tpike3 in #2415
• space: Add note that Grids are maintenance only by @EwoutH in #2420
• Migration guide: Update automatic unique_id assignment examples by @EwoutH in #2419
• Update docstring of SimEvent by @quaquel in #2417

🔧 Maintenance

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

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

Mesa 3.0 beta 1

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

• use GridDraggable instead of Column in SolaraViz by @wang-boyu in #2344
• update legend, xlabel & format of matplotlib plots by @wang-boyu in #2346
• init.py: Import mesa.experimental by @EwoutH in #2374
• Importable examples by @Corvince in #2381

🐛 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

• Cleanup and restructure basic example models by @EwoutH in #2365
• Ruff basic examples by @EwoutH in #2370

📜 Documentation improvements

• Update migration_guide.md by @quaquel in #2347

🔧 Maintenance

• Code coverage: ignore experimental and visualization by @Corvince in #2361
• add codecov token, fixes #2363 by @Corvince in #2366
• add test_time back by @quaquel in #2367
• Release notes: Add example category by @EwoutH in #2369

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

Mesa 3.0 beta 0

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

• Visualize PropertyLayers by @EwoutH in #2336

🧪 Experimental features

• Encapsulate cell movement in properties by @quaquel in #2333
• experimental: Integrate PropertyLayers into cell space by @EwoutH in #2319
• Generalize CellAgent by @Corvince in #2292

🛠 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

• Deprecate initialize_data_collector by @EwoutH in #2327

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

v2.4.0

Highlights

Mesa 2.4.0 brings several key improvements from the upcoming 3.0 series, while maintaining compatibility with existing Mesa 2.x models.

The DataCollector now supports collecting data from specific Agent subclasses using the new agenttype_reporters parameter (#2300). This allows collecting different metrics for different agent types. For example:

self.datacollector = DataCollector(
    agenttype_reporters={
        Wolf: {"sheep_eaten": "sheep_eaten"},
        Sheep: {"wool": "wool_amount"}
    }
)

The AgentSet class, which underpins model.agents, has received major enhancements:

• A new groupby() method to split agents into groups (#2220)
• An agg() method to quickly compute aggregate values (#2266)
• A faster shuffle_do() method for more efficient random agent activation (#2283)
• The select() method now allows choosing a fraction of agents (#2253)
• The do() method can now take any callable function, not just string method names (#2219)

Other notable improvements include:

• The Model class now exposes an agents_by_type property for easier access to agents of specific types (#2267)
• Performance enhancements for Model.agents (#2251)
• The AgentSet.get() method now handles missing values with optional default value (#2279)

This release also fixes a bug in the Grid's move_agent_to_one_of method with selection="closest", which previously selected locations deterministically instead of randomly (#2118).

Finally, we've made significant documentation improvements, including the addition of a new Migration guide to help users transition to future Mesa versions (#2257).

What's Changed

🎉 New features added

• Add AgentSet.groupby by @quaquel in #2220
• AgentSet: Add agg method by @EwoutH in #2266
• GroupBy: Add count and agg methods by @EwoutH in #2290
• datacollector: Allow collecting data from Agent (sub)classes by @EwoutH in #2300
• Add optimized shuffle_do() method to AgentSet by @EwoutH in #2283

🛠 Enhancements made

• Allow AgentSet.do() to take Callable function by @quaquel in #2219
• Split AgentSet into map and do to separate return types by @quaquel in #2237
• Performance enhancements for Model.agents by @quaquel in #2251
• AgentSet: Allow selecting a fraction of agents in the AgentSet by @EwoutH in #2253
• Model: Replace get_agents_of_type method with agents_by_type property by @EwoutH in #2267
• Add default values and missing value handling to agentset.get by @quaquel in #2279

🐛 Bugs fixed

• Jupyter_viz: Allow measures to be None by @EwoutH in #2163
• Fix deterministic behavior in move_agent_to_one_of with selection="closest" by @OrenBochman in #2118

📜 Documentation improvements

• Contribution: Add "I have no idea where to start" section by @EwoutH in #2258
• Write initial Mesa Migration guide by @EwoutH in #2257
• Docs: Fix broken relative links by removing .html suffix by @EwoutH in #2274
• Readthedocs: Don't let notebook failures pass silently by @EwoutH in #2276
• update migration guide to describe solaraviz updates by @Corvince in #2297
• Migration Guide: Add Model initialization requirement and automatic Agent.unique_id assignment by @EwoutH in #2302

🔧 Maintenance

• make typing behavior of AgentSet.get explicit by @quaquel in #2293

Full Changelog: v2.3.4...v2.4.0

v3.0 alpha 5 (pre-release)

Highlights

Mesa v3.0 alpha 5 release contains many quality of life updates, a big new feature for the DataCollector and a major deprecation.

The entire mesa.time module, including all schedulers, has been deprecated (#2306). Users are encouraged to transition to AgentSet functionality for more flexible and explicit agent activation patterns. Check the migration guide on how to upgrade.

The DataCollector now supports collecting data from specific Agent subclasses using the new agenttype_reporters parameter (#2300). This allows collecting different metrics for different agent types. For example:

self.datacollector = DataCollector(
    agenttype_reporters={
        Wolf: {"sheep_eaten": "sheep_eaten"},
        Sheep: {"wool": "wool_amount"}
    }
)

Furthermore, a new shuffle_do() method for AgentSets provides a faster way to perform shuffle().do() (#2283). The GroupBy class gained count() and agg() methods to count the number of agents in groups and aggregate variables of them (#2290).

In the experimental Cell Space, the CellCollection.select method was updated to use at_most instead of n, aligning with the AgentSet API (#2307). Cell connections in grids and networks are now public and named for more intuitive agent movements (#2296). Additionally, the Cell class now features a dedicated neighborhood property for direct neighbors (default radius=1) and a get_neighborhood method for larger radii (#2309).

Finally, SolaraViz received updates improving its interface and performance (#2299, #2304). The Model class initialization process was simplified by moving random seed and random object creation to __init__ (#1940). Documentation has been extensively updated, including enforcing Google docstrings (#2294) and reorganizing the API documentation (#2298) for better clarity and navigation.

While the Mesa 3.0 timeline is still being discussed, we're aiming at the first Mesa 3.0 beta in October followed by a stable release in November. Testing new features and sharing feedback is appreciated!

What's Changed

🎉 New features added

• GroupBy: Add count and agg methods by @EwoutH in #2290
• datacollector: Allow collecting data from Agent (sub)classes by @EwoutH in #2300
• Add optimized shuffle_do() method to AgentSet by @EwoutH in #2283

🛠 Enhancements made

• SolaraViz Updates by @Corvince in #2299
• Solara viz: use_task for non-threaded continuous play by @Corvince in #2304

🧪 Experimental features

• Make cell connections public and named by @Corvince in #2296
• Update to CellCollection.select by @quaquel in #2307
• Have a dedicated neighborhood property and a get_neighborhood method on Cell by @quaquel in #2309

📜 Documentation improvements

• Enforce google docstrings by @quaquel in #2294
• Api docs by @quaquel in #2298
• update migration guide to describe solaraviz updates by @Corvince in #2297
• Migration Guide: Add Model initialization requirement and automatic Agent.unique_id assignment by @EwoutH in #2302
• Deprecate Time module and all its Schedulers by @EwoutH in #2306
• intro_tutorial: Don't initialize agents with an unique_id by @EwoutH in #2315
• Migration guide: Intro, upgrade strategy, model.agents, headers by @EwoutH in #2314

🔧 Maintenance

• make typing behavior of AgentSet.get explicit by @quaquel in #2293
• model: Move random seed and random to init by @rht in #1940
• Remove schedulers from benchmark models. by @quaquel in #2308

Full Changelog: v3.0.0a4...v3.0.0a5