Mesa

Highlights

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](https://github.com/projectmesa/mesa/pull/2328) and the [Migration guide](https://mesa.readthedocs.io/latest/migration_guide.html#automatic-assignment-of-unique-id-to-agents).
- PropertyLayers can now be visualized! See [2336](https://github.com/projectmesa/mesa/pull/2336) for details and some examples, and [mesa-examples#214](https://github.com/projectmesa/mesa-examples/pull/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](https://github.com/projectmesa/mesa/pull/2265) for details.
- The [Mesa Overview](https://mesa.readthedocs.io/latest/overview.html) 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](https://github.com/projectmesa/mesa/milestone/43) are the critical items on our todo-list.

You can install this pre-release as usual with:

bash
pip install --upgrade --pre mesa

We're very curious what you think, try it out and ask any questions or share any feedback [here](https://github.com/projectmesa/mesa/discussions/2338)!

What's Changed
⚠️ Breaking changes
* update `Agent.__init__` to remove deprecation warning by quaquel in https://github.com/projectmesa/mesa/pull/2328
🎉 New features added
* Visualize PropertyLayers by EwoutH in https://github.com/projectmesa/mesa/pull/2336
🧪 Experimental features
* Encapsulate cell movement in properties by quaquel in https://github.com/projectmesa/mesa/pull/2333
* experimental: Integrate PropertyLayers into cell space by EwoutH in https://github.com/projectmesa/mesa/pull/2319
* Generalize CellAgent by Corvince in https://github.com/projectmesa/mesa/pull/2292
🛠 Enhancements made
* Reduce core dependencies, split in optional dependencies by EwoutH in https://github.com/projectmesa/mesa/pull/2265
🐛 Bugs fixed
* viz: stop running and disable buttons when model.running is False by wang-boyu in https://github.com/projectmesa/mesa/pull/2332
📜 Documentation improvements
* docs: Update overview for Mesa 3.0 by EwoutH in https://github.com/projectmesa/mesa/pull/2317
* Readthedocs: Add version switch and update URL by EwoutH in https://github.com/projectmesa/mesa/pull/2324
🔧 Maintenance
* tests: Resolve warnings by removing scheduler and updating arguments by EwoutH in https://github.com/projectmesa/mesa/pull/2329
* add super call to Model and remove self.schedule by quaquel in https://github.com/projectmesa/mesa/pull/2334
Other changes
* Deprecate `initialize_data_collector` by EwoutH in https://github.com/projectmesa/mesa/pull/2327

**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a5...v3.0.0b0

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](https://github.com/projectmesa/mesa/pull/2306)). Users are encouraged to transition to AgentSet functionality for more flexible and explicit agent activation patterns. Check the [migration guide](https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers) on how to upgrade.

The DataCollector now supports collecting data from specific Agent subclasses using the new `agenttype_reporters` parameter ([2300](https://github.com/projectmesa/mesa/pull/2300)). This allows collecting different metrics for different agent types. For example:

python
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](https://github.com/projectmesa/mesa/pull/2283)). The GroupBy class gained `count()` and `agg()` methods to count the number of agents in groups and aggregate variables of them ([#2290](https://github.com/projectmesa/mesa/pull/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](https://github.com/projectmesa/mesa/pull/2307)). 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](https://github.com/projectmesa/mesa/pull/2309)).

Finally, SolaraViz received updates improving its interface and performance ([2299](https://github.com/projectmesa/mesa/pull/2299), [#2304](https://github.com/projectmesa/mesa/pull/2304)). Cell connections in grids and networks are now public and named for more intuitive agent movements ([#2296](https://github.com/projectmesa/mesa/pull/2296)). The Model class initialization process was simplified by moving random seed and random object creation to `__init__` ([#1940](https://github.com/projectmesa/mesa/pull/1940)). Documentation has been extensively updated, including enforcing Google docstrings ([#2294](https://github.com/projectmesa/mesa/pull/2294)) and reorganizing the API documentation ([#2298](https://github.com/projectmesa/mesa/pull/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 https://github.com/projectmesa/mesa/pull/2290
* datacollector: Allow collecting data from Agent (sub)classes by EwoutH in https://github.com/projectmesa/mesa/pull/2300
* Add optimized shuffle_do() method to AgentSet by EwoutH in https://github.com/projectmesa/mesa/pull/2283
🛠 Enhancements made
* Make cell connections public and named by Corvince in https://github.com/projectmesa/mesa/pull/2296
* SolaraViz Updates by Corvince in https://github.com/projectmesa/mesa/pull/2299
* Solara viz: use_task for non-threaded continuous play by Corvince in https://github.com/projectmesa/mesa/pull/2304
🧪 Experimental features
* Update to CellCollection.select by quaquel in https://github.com/projectmesa/mesa/pull/2307
* Have a dedicated neighborhood property and a get_neighborhood method on Cell by quaquel in https://github.com/projectmesa/mesa/pull/2309
📜 Documentation improvements
* Enforce google docstrings by quaquel in https://github.com/projectmesa/mesa/pull/2294
* Api docs by quaquel in https://github.com/projectmesa/mesa/pull/2298
* update migration guide to describe solaraviz updates by Corvince in https://github.com/projectmesa/mesa/pull/2297
* Migration Guide: Add Model initialization requirement and automatic Agent.unique_id assignment by EwoutH in https://github.com/projectmesa/mesa/pull/2302
* Deprecate Time module and all its Schedulers by EwoutH in https://github.com/projectmesa/mesa/pull/2306
* intro_tutorial: Don't initialize agents with an unique_id by EwoutH in https://github.com/projectmesa/mesa/pull/2315
* Migration guide: Intro, upgrade strategy, model.agents, headers by EwoutH in https://github.com/projectmesa/mesa/pull/2314
🔧 Maintenance
* make typing behavior of AgentSet.get explicit by quaquel in https://github.com/projectmesa/mesa/pull/2293
* model: Move random seed and random to __init__ by rht in https://github.com/projectmesa/mesa/pull/1940
* Remove schedulers from benchmark models. by quaquel in https://github.com/projectmesa/mesa/pull/2308

**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a4...v3.0.0a5

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:
diff
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-examples194](https://github.com/projectmesa/mesa-examples/pull/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](https://github.com/projectmesa/mesa/pull/2278).
- An initial update to the tutorial was made in [2289](https://github.com/projectmesa/mesa/pull/2289) and is [available here](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html).
- An initial example model was updated in [mesa-examples195](https://github.com/projectmesa/mesa-examples/pull/195), and more examples will be updated in [mesa-examples#195](https://github.com/projectmesa/mesa-examples/pull/193).
- 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](https://github.com/projectmesa/mesa/pull/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](https://github.com/projectmesa/mesa/pull/2267), [mesa-examples#190](https://github.com/projectmesa/mesa-examples/pull/190)) and the AgentSet get() methods can now handle missing values by replacing it with a default value ([#2279](https://github.com/projectmesa/mesa/pull/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](https://github.com/projectmesa/mesa/pull/2118)).

What's Changed
⚠️ Breaking changes
* move solara_viz back to experimental by Corvince in https://github.com/projectmesa/mesa/pull/2278
* track unique_id automatically by quaquel in https://github.com/projectmesa/mesa/pull/2260
🎉 New features added
* AgentSet: Add `agg` method by EwoutH in https://github.com/projectmesa/mesa/pull/2266
* Implement new SolaraViz API by Corvince in https://github.com/projectmesa/mesa/pull/2263
🛠 Enhancements made
* Model: Replace `get_agents_of_type` method with `agents_by_type` property by EwoutH in https://github.com/projectmesa/mesa/pull/2267
* add default SolaraViz by Corvince in https://github.com/projectmesa/mesa/pull/2280
* Simplify ModelController by Corvince in https://github.com/projectmesa/mesa/pull/2282
* Add default values and missing value handling to `agentset.get` by quaquel in https://github.com/projectmesa/mesa/pull/2279
🐛 Bugs fixed
* Fix deterministic behavior in `move_agent_to_one_of` with `selection="closest"` by OrenBochman in https://github.com/projectmesa/mesa/pull/2118
📜 Documentation improvements
* docs: Fix Visualization Tutorial (main branch) by EwoutH in https://github.com/projectmesa/mesa/pull/2271
* Docs: Fix broken relative links by removing `.html` suffix by EwoutH in https://github.com/projectmesa/mesa/pull/2274
* Readthedocs: Don't let notebook failures pass silently by EwoutH in https://github.com/projectmesa/mesa/pull/2276
* Update viz tutorial to the new API by Corvince in https://github.com/projectmesa/mesa/pull/2289
🔧 Maintenance
* Resolve multiprocessing warning, state Python 3.13 support by rht in https://github.com/projectmesa/mesa/pull/2246

New Contributors
* OrenBochman made their first contribution in https://github.com/projectmesa/mesa/pull/2118

**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a3...v3.0.0a4

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](https://en.wikipedia.org/wiki/Voronoi_diagram) layout as part of the experimental cell space. An example using it to model Cholera spread can be [found here](https://github.com/projectmesa/mesa-examples/pull/118).

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 ([examples183](https://github.com/projectmesa/mesa-examples/pull/183)). They now use the automatic step increase and AgentSet functionality. We started testing our GIS model in CI ([examples#171](https://github.com/projectmesa/mesa-examples/pull/171)) and resolved a lot of bugs in them ([examples#172](https://github.com/projectmesa/mesa-examples/issues/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 ([examples157](https://github.com/projectmesa/mesa-examples/pull/157) by zjost). The first example using the `PropertyLayer` was added, a very fast implementation of Conway's Game of Life ([examples#182](https://github.com/projectmesa/mesa-examples/pull/182)).

To help the transition to Mesa 3.0, we started writing a [migration guide](https://mesa.readthedocs.io/latest/migration_guide.html). Progress is tracked in #2233, feedback and help is appreciated! Finally, we also added a new section to our [contributor guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md#i-have-no-idea-where-to-start) 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 https://github.com/projectmesa/mesa/pull/2223
🧪 Experimental features
* Voronoi Tessellation based Discrete Space by vitorfrois in https://github.com/projectmesa/mesa/pull/2084
🎉 New features added
* Add AgentSet.groupby by quaquel in https://github.com/projectmesa/mesa/pull/2220
* AgentSet: Add `set` method by EwoutH in https://github.com/projectmesa/mesa/pull/2254
🛠 Enhancements made
* Split AgentSet into map and do to separate return types by quaquel in https://github.com/projectmesa/mesa/pull/2237
* Performance enhancements for Model.agents by quaquel in https://github.com/projectmesa/mesa/pull/2251
* AgentSet: Allow selecting a fraction of agents in the AgentSet by EwoutH in https://github.com/projectmesa/mesa/pull/2253
🐛 Bugs fixed
* SolaraViz: Reset components when params are changed by rht in https://github.com/projectmesa/mesa/pull/2240
📜 Documentation improvements
* Contribution: Add "I have no idea where to start" section by EwoutH in https://github.com/projectmesa/mesa/pull/2258
* Write initial Mesa Migration guide by EwoutH in https://github.com/projectmesa/mesa/pull/2257
🔧 Maintenance
* CI: Add test job for Python 3.13 by EwoutH in https://github.com/projectmesa/mesa/pull/2173
* Add pull request templates by EwoutH in https://github.com/projectmesa/mesa/pull/2217
* benchmarks: Add BoltzmannWealth model by EwoutH in https://github.com/projectmesa/mesa/pull/2252
* CI: Add optional dependency for examples by EwoutH in https://github.com/projectmesa/mesa/pull/2261

New Contributors
* vitorfrois made their first contribution in https://github.com/projectmesa/mesa/pull/2084

**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a2...v3.0.0a3

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](https://github.com/projectmesa/mesa/pull/2218) `super().__init__()` to run on initializing a Mesa model subclass, `Model.agents` is now fully reserved for the Model's internal AgentSet and we fixed a bug in our Solara space_drawer.

A new feature was added in [2219](https://github.com/projectmesa/mesa/pull/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`.

The new Solara visualisation now allows portraying agents in different shapes, checkout some examples in [2214](https://github.com/projectmesa/mesa/pull/2214).

We're also working hard on our [example models](https://github.com/projectmesa/mesa-examples). All model warnings were [resolved](https://github.com/projectmesa/mesa-examples/pull/153) and we've [replaced](https://github.com/projectmesa/mesa-examples/pull/161) a lot of schedulers with simpler and more flexible AgentSet functionality. Checkout our [open issues](https://github.com/projectmesa/mesa-examples/issues) if you want to help improve our example models further!

What's Changed
⚠️ Breaking changes
* breaking: Add dependencies argument to custom space_drawer by rht in https://github.com/projectmesa/mesa/pull/2209
* Require Mesa models to be initialized with `super().__init__()` by EwoutH in https://github.com/projectmesa/mesa/pull/2218
* Allow AgentSet.do() to take Callable function by quaquel in https://github.com/projectmesa/mesa/pull/2219
* Change warning when setting model.agents to error by EwoutH in https://github.com/projectmesa/mesa/pull/2225
🧪 Experimental features
* devs/eventlist: Add repr method to print EventList pretty by EwoutH in https://github.com/projectmesa/mesa/pull/2195
🛠 Enhancements made
* Visualisation: Allow specifying Agent shapes in agent_portrayal by rmhopkins4 in https://github.com/projectmesa/mesa/pull/2214
📜 Documentation improvements
* docs/conf.py: Use modern `intersphinx_mapping` format by EwoutH in https://github.com/projectmesa/mesa/pull/2206
* docs: Update Readme and tutorials to mention Mesa 3.0 pre-releases by EwoutH in https://github.com/projectmesa/mesa/pull/2203
🔧 Maintenance
* CI: Let pytest treat warnings as errors for examples by EwoutH in https://github.com/projectmesa/mesa/pull/2204

New Contributors
* rmhopkins4 made their first contribution in https://github.com/projectmesa/mesa/pull/2214

**Full Changelog**: https://github.com/projectmesa/mesa/compare/v3.0.0a1...v3.0.0a2