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

v3.0 alpha 4 (pre-release)

Highlights

Mesa 3.0.0a4 contains two major breaking changes:

1. The Agent's unique_id is now automatically assigned, so doesn't need to be passed to the Agent class anymore. In a subclassed custom Agent, like normally used, this now looks like this:

   class Wolf(Agent):
   -    def __init__(self, unique_id, model, energy=None):
   +    def __init__(self, model, energy=None):
           # When initializing the super class (Agent), passing unique_id isn't needed anymore
   -        super().__init__(unique_id, model)
   +        super().__init__(model)
   
   - wolf = Wolf(unique_id, model)
   + wolf = Wolf(model)

   Example models were updated in mesa-examples#194, which shows more examples on how to update existing models.

2. Our visualisation API is being overhauled, to be more flexible and powerful. For more details, see #2278.

   • An initial update to the tutorial was made in #2289 and is available here.
   • An initial example model was updated in mesa-examples#195, and more examples will be updated in mesa-examples#195.
   • The old SolaraViz API is still available at mesa.experimental, but might be removed in future releases.

Furthermore, the AgentSet has a new agg method to quickly get an aggerate value (for example min_energy = model.agents.agg("energy", min)) (#2266), The Model get_agents_of_type function is replaced by directly exposing the agents_by_type property (which can be accessed as a dict) (#2267, mesa-examples#190) and the AgentSet get() methods can now handle missing values by replacing it with a default value (#2279).

Finally, it fixes a bug in which the Grid's move_agent_to_one_of method with selection="closest" selected a location deterministically, instead of randomly (#2118).

What's Changed

⚠️ Breaking changes

• move solara_viz back to experimental by @Corvince in #2278
• track unique_id automatically by @quaquel in #2260

🎉 New features added

• AgentSet: Add agg method by @EwoutH in #2266
• Implement new SolaraViz API by @Corvince in #2263

🛠 Enhancements made

• Model: Replace get_agents_of_type method with agents_by_type property by @EwoutH in #2267
• add default SolaraViz by @Corvince in #2280
• Simplify ModelController by @Corvince in #2282
• Add default values and missing value handling to agentset.get by @quaquel in #2279

🐛 Bugs fixed

• Fix deterministic behavior in move_agent_to_one_of with selection="closest" by @OrenBochman in #2118

📜 Documentation improvements

• docs: Fix Visualization Tutorial (main branch) by @EwoutH in #2271
• 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 viz tutorial to the new API by @Corvince in #2289

🔧 Maintenance

• Resolve multiprocessing warning, state Python 3.13 support by @rht in #2246

New Contributors

• @OrenBochman made their first contribution in #2118

Full Changelog: v3.0.0a3...v3.0.0a4

v2.3.4

Highlights

Two fixes in our docs: The visualization tutorial started using an example model that wasn't compatible with Mesa 2.x anymore, and some relative links were broken. This release fixes both.

What's Changed

📜 Documentation improvements

• docs: Fix Visualization Tutorial (2.x branch) by @EwoutH in #2272
• Docs: Fix broken relative links by removing .html suffix by @EwoutH in #2274

Full Changelog: v2.3.3...v2.3.4

v2.3.3

Highlights

Mesa v2.3.3 is a small patch release with documentation and maintenance updates backported from our main branch.

We do have included one feature as preview for Mesa 3.0: The AgentSet got a convenient set method to quickly set a variable value to (a subset of) agents. See #2254 for some examples.

What's Changed

🎉 New features added

• AgentSet: Add set method by @EwoutH in #2254

📜 Documentation improvements

• Fix image on landing page of docs. by @jackiekazil in #2146
• Replace links in docs - google group to matrix. by @jackiekazil in #2148
• Add experimental features to documentation as per #2122 by @stephenfmann in #2154
• Update visualisation docs by @EwoutH in #2162
• Add original conference paper link to docs by @ENUMERA8OR in #2160
• docs/conf.py: Use modern intersphinx_mapping format by @EwoutH in #2206
• Contribution: Add "I have no idea where to start" section by @EwoutH in #2258

Full Changelog: v2.3.2...v2.3.3

v3.0 alpha 3 (pre-release)

Highlights

Developments toward Mesa 3.0 are steaming ahead, and our fourth alpha release is packed with features and updates - only 8 days after our third.

Mesa 3.0.0a3 contains one breaking change: We now automatically increase the steps counter by one at the beginning of each Model.steps() call. That means increasing steps by hand isn't necessary anymore.

The big new features is the experimental Voronoi grid that @vitorfrois implemented in #2084. It allows creating cells in a Voronoi layout as part of the experimental cell space. An example using it to model Cholera spread can be found here.

The AgentSet got a lot of love with two brand new methods: .groupby() to split in groups (#2220) and .set() to easily assign variables to all agents in that set (#2254). The select() method is improved by allowing to select at most a fraction of the agents (#2253), and we split the do() method in do() and map() to make a distinction between the return types (#2237).

Furthermore, we improved the performance of accessing Model.agents, squashed a bug in SolaraViz, started testing on Python 3.13 and added a new benchmark model.

Our example models also got more love: We removed the RandomActivation scheduler in 14 models and removed SimultaneousActivation in 3 models (examples#183). They now use the automatic step increase and AgentSet functionality. We started testing our GIS model in CI (examples#171) and resolved a lot of bugs in them (examples#172, help appreciated!).

Finally, we have two brand new examples: An Ant Colony Optimization model using an Ant System approach to the Traveling Salesman problem, a Mesa NetworkGrid, and a custom visualisation with SolaraViz (examples#157 by @zjost). The first example using the PropertyLayer was added, a very fast implementation of Conway's Game of Life (examples#182).

To help the transition to Mesa 3.0, we started writing a migration guide. Progress is tracked in #2233, feedback and help is appreciated! Finally, we also added a new section to our contributor guide to get new contributors up to speed.

This pre-release can be installed as always with pip install --pre mesa

What's Changed

⚠️ Breaking changes

• model: Automatically increase steps counter by @EwoutH in #2223

🧪 Experimental features

• Voronoi Tessellation based Discrete Space by @vitorfrois in #2084

🎉 New features added

• Add AgentSet.groupby by @quaquel in #2220
• AgentSet: Add set method by @EwoutH in #2254

🛠 Enhancements made

• 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

🐛 Bugs fixed

• SolaraViz: Reset components when params are changed by @rht in #2240

📜 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

🔧 Maintenance

• CI: Add test job for Python 3.13 by @EwoutH in #2173
• Add pull request templates by @EwoutH in #2217
• benchmarks: Add BoltzmannWealth model by @EwoutH in #2252
• CI: Add optional dependency for examples by @EwoutH in #2261

New Contributors

• @vitorfrois made their first contribution in #2084

Full Changelog: v3.0.0a2...v3.0.0a3

v3.0 alpha 2 (pre-release)

Highlights

In Mesa 3.0 alpha 2 (v3.0.0a2) we've done more clean-up in preparation for Mesa 3.0. We now require super().__init__() to run on initializing a Mesa model subclass and fixed a bug in our Solara space_drawer.

A new feature was added in #2219, which now also allows AgentSet.do() to take any callable function, instead of only a string referencing to an Agent method. The argument name was changed from method_name to method.

We're also working hard on our example models. All model warnings were resolved and we've replaced a lot of schedulers with simpler and more flexible AgentSet functionality. Checkout our open issues if you want to help improve our example models further!

You can update to this version as usual with pip install mesa --upgrade --pre.

What's Changed

⚠️ Breaking changes

• Allow AgentSet.do() to take Callable function by @quaquel in #2219
• Require Mesa models to be initialized with super().__init__() by @EwoutH in #2218
• breaking: Add dependencies argument to custom space_drawer by @rht in #2209

🧪 Experimental enhancement

• devs/eventlist: Add repr method to print EventList pretty by @EwoutH in #2195

📜 Documentation improvements

• docs: Update Readme and tutorials to mention Mesa 3.0 pre-releases by @EwoutH in #2203

🔧 Maintenance

• CI: Let pytest treat warnings as errors for examples by @EwoutH in #2204
• docs/conf.py: Use modern intersphinx_mapping format by @EwoutH in #2206

Full Changelog: v3.0.0a1...v3.0.0a2

v3.0 alpha 1 (pre-release)

Highlights

Mesa 3.0 alpha 1 (v3.0.0a1) is another step towards our next major version. This release introduces a name change from JupyterViz (jupyter_viz) to SolaraViz (solara_viz), to better represent the tech stack being used. It also includes two bugfixes also present in 2.3.2.

What's Changed

⚠️ Breaking changes

• viz: Combine code for rendering in browser and Jupyter by @rht in #2180
• refactor: Rename jupyter_viz namespace to solara_viz by @rht in #2188

🛠 Enhancements made

• Rename JupyterViz to SolaraViz by @rht in #2187

🐛 Bugs fixed

• fix: Render agent marker radius correctly by @rht in #2181
• fix: Use model.schedule.steps -> mode._steps for batch_run by @rht in #2183

📜 Documentation improvements

• Add original conference paper link to docs by @ENUMERA8OR in #2160

New Contributors

• @ENUMERA8OR made their first contribution in #2160

Full Changelog: v3.0.0a0...v3.0.0a1

v2.3.2

Highlights

Mesa 2.3.2 is a small patch release which fixes two bugs, one to the batch_run function still depending on schedule.steps, and one in the agent marker visualisation.

What's Changed

🐛 Bugs fixed

• fix: Render agent marker radius correctly by @rht in #2181
• fix: Use model.schedule.steps -> model._steps for batch_run by @rht in #2183

Full Changelog: v2.3.1...v2.3.2

v3.0 alpha 0 (pre-release)

Highlights

This is the first pre-release in the Mesa 3.0 series, which is still in active development. The v3.0.0a0 pre-release can help active Mesa developers help starting to test the latest features in their models.

Since it's in active development, more breaking changes may follow and it's not recommended for general usage.

There are two major breaking changes at this point:

• The old visualisation is removed, in favor of the new, Solara based, Jupyter Viz. This was already available in the 2.3.x release series, but is now stabilized. Checkout out our new Visualization Tutorial. More examples and a migration guide will follow later in the Mesa 3.0 development.
• The mesa.flat namespace is removed, since was not used very often.

Mesa 3.0 will require Python 3.10+.

This pre-release can be installed with pip install mesa --upgrade --pre.

What's Changed

⚠️ Breaking changes

• Remove mesa.flat namespace by @rht in #2091
• breaking: Remove visualization_old (mesa-viz-tornado) by @rht in #2133

🎉 New features added

• Set JupyterViz as stable by @rht in #2090

🐛 Bugs fixed

• Jupyter_viz: Allow measures to be None by @EwoutH in #2163
• Jupyter Viz: Don't avoid interactive backend by @EwoutH in #2165

📜 Documentation improvements

• Fix image on landing page of docs. by @jackiekazil in #2146
• Replace links in docs - google group to matrix. by @jackiekazil in #2148
• Update visualisation docs by @EwoutH in #2162

🔧 Maintenance

• CI: Add weekly scheduled run to all CI workflows by @EwoutH in #2130
• Drop support for Python 3.9, require Python >= 3.10 by @EwoutH in #2132
• Add script to list unlabeled PR's since latest release by @rht in #2047

New Contributors

• @stephenfmann made their first contribution in #2154

Full Changelog: v2.3.1...v3.0.0a0