Mesa 2.3.4__tar.gz → 2.4.0__tar.gz

{mesa-2.3.4 → mesa-2.4.0}/.github/workflows/build_lint.yml

@@ -33,6 +33,8 @@ jobs:
         os: [windows, ubuntu, macos]
         python-version: ["3.12"]
         include:
+          - os: ubuntu
+            python-version: "3.13"
           - os: ubuntu
             python-version: "3.11"
           - os: ubuntu
@@ -49,6 +51,7 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
         cache: 'pip'
     - name: Install uv
       run: pip install uv

{mesa-2.3.4 → mesa-2.4.0}/.readthedocs.yml

@@ -1,5 +1,5 @@
 # Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# See https://docs.readthedocs.io/stable/config-file/v2.html for details
 
 # Required
 version: 2

{mesa-2.3.4 → mesa-2.4.0}/CONTRIBUTING.md

@@ -53,7 +53,7 @@ Learn the tools, talk to us about what you want to change, and open a small PR.
 Awesome! You have the basics of open-source software development (if not check above), but not much modelling experience.
 
 First step is to start thinking like a modeller. To understand the fine details about our library and contribute meaningfully, get some modelling experience:
-- Go though our [Introductory Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does.
+- Go though our [Introductory Tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) and [Visualization Tutorial](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html). While going through them, dive into the source code to really see what everything does.
 - Follow an ABM course (if possible). They might be a bit outdated programming language wise, but conceptual they're sound.
   - This MOOC on ABM concepts: [Agent Based Modeling](https://ocw.tudelft.nl/course-lectures/agent-based-modeling/)
   - This MOOC on practical ABM modelling: [Agent-Based Models with Python: An Introduction to Mesa](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa)

{mesa-2.3.4 → mesa-2.4.0}/HISTORY.md

@@ -1,6 +1,70 @@
 ---
 title: Release History
 ---
+# 2.4.0 (2024-09-24)
+## 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](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"}
+    }
+)
+```
+
+The AgentSet class, which underpins `model.agents`, has received major enhancements:
+- A new `groupby()` method to split agents into groups ([#2220](https://github.com/projectmesa/mesa/pull/2220))
+- An `agg()` method to quickly compute aggregate values ([#2266](https://github.com/projectmesa/mesa/pull/2266))
+- A faster `shuffle_do()` method for more efficient random agent activation ([#2283](https://github.com/projectmesa/mesa/pull/2283))
+- The `select()` method now allows choosing a fraction of agents ([#2253](https://github.com/projectmesa/mesa/pull/2253))
+- The `do()` method can now take any callable function, not just string method names ([#2219](https://github.com/projectmesa/mesa/pull/2219))
+
+Other notable improvements include:
+- The Model class now exposes an `agents_by_type` property for easier access to agents of specific types ([#2267](https://github.com/projectmesa/mesa/pull/2267))
+- Performance enhancements for `Model.agents` ([#2251](https://github.com/projectmesa/mesa/pull/2251))
+- The `AgentSet.get()` method now handles missing values with optional default value ([#2279](https://github.com/projectmesa/mesa/pull/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](https://github.com/projectmesa/mesa/pull/2118)).
+
+Finally, we've made significant documentation improvements, including the addition of a new [Migration guide](https://mesa.readthedocs.io/latest/migration_guide.html) to help users transition to future Mesa versions ([#2257](https://github.com/projectmesa/mesa/pull/2257)).
+
+## What's Changed
+### 🎉 New features added
+* Add AgentSet.groupby by @quaquel in [#2220](https://github.com/projectmesa/mesa/pull/2220)
+* AgentSet: Add `agg` method by @EwoutH in [#2266](https://github.com/projectmesa/mesa/pull/2266)
+* GroupBy: Add `count` and `agg` methods by @EwoutH in [#2290](https://github.com/projectmesa/mesa/pull/2290)
+* datacollector: Allow collecting data from Agent (sub)classes by @EwoutH in [#2300](https://github.com/projectmesa/mesa/pull/2300)
+* Add optimized shuffle_do() method to AgentSet by @EwoutH in [#2283](https://github.com/projectmesa/mesa/pull/2283)
+
+### 🛠 Enhancements made
+* Allow AgentSet.do() to take Callable function by @quaquel in [#2219](https://github.com/projectmesa/mesa/pull/2219)
+* Split AgentSet into map and do to separate return types by @quaquel in [#2237](https://github.com/projectmesa/mesa/pull/2237)
+* Performance enhancements for Model.agents by @quaquel in [#2251](https://github.com/projectmesa/mesa/pull/2251)
+* AgentSet: Allow selecting a fraction of agents in the AgentSet by @EwoutH in [#2253](https://github.com/projectmesa/mesa/pull/2253)
+* Model: Replace `get_agents_of_type` method with `agents_by_type` property by @EwoutH in [#2267](https://github.com/projectmesa/mesa/pull/2267)
+* Add default values and missing value handling to `agentset.get` by @quaquel in [#2279](https://github.com/projectmesa/mesa/pull/2279)
+
+### 🐛 Bugs fixed
+* Jupyter_viz: Allow measures to be None by @EwoutH in [#2163](https://github.com/projectmesa/mesa/pull/2163)
+* Fix deterministic behavior in `move_agent_to_one_of` with `selection="closest"` by @OrenBochman in [#2118](https://github.com/projectmesa/mesa/pull/2118)
+
+### 📜 Documentation improvements
+* Contribution: Add "I have no idea where to start" section by @EwoutH in [#2258](https://github.com/projectmesa/mesa/pull/2258)
+* Write initial Mesa Migration guide by @EwoutH in [#2257](https://github.com/projectmesa/mesa/pull/2257)
+* Docs: Fix broken relative links by removing `.html` suffix by @EwoutH in [#2274](https://github.com/projectmesa/mesa/pull/2274)
+* Readthedocs: Don't let notebook failures pass silently by @EwoutH in [#2276](https://github.com/projectmesa/mesa/pull/2276)
+* update migration guide to describe solaraviz updates by @Corvince in [#2297](https://github.com/projectmesa/mesa/pull/2297)
+* Migration Guide: Add Model initialization requirement and automatic Agent.unique_id assignment by @EwoutH in [#2302](https://github.com/projectmesa/mesa/pull/2302)
+
+### 🔧 Maintenance
+* make typing behavior of AgentSet.get explicit by @quaquel in [#2293](https://github.com/projectmesa/mesa/pull/2293)
+
+**Full Changelog**: [https://github.com/projectmesa/mesa/compare/v2.3.4...v2.4.0](https://github.com/projectmesa/mesa/compare/v2.3.4...v2.4.0)
+
 # 2.3.4 (2024-09-04)
 ## 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.

{mesa-2.3.4 → mesa-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 2.3.4
+Version: 2.4.0
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Artificial Life
@@ -55,7 +56,7 @@ Description-Content-Type: text/markdown
 | Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) |
 | Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
 
-*This is the `2.3.x-maintenance` branch. Example models for Mesa 2.x can be found [here](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples).*
+*This is the `2.4.x-maintenance` branch. Example models for Mesa 2.x can be found [here](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples).*
 
 Mesa allows users to quickly create agent-based models using built-in
 core components (such as spatial grids and agent schedulers) or
@@ -101,13 +102,13 @@ For resources or help on using Mesa, check out the following:
 
 -   [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann
     Wealth Model, for beginners or those new to Mesa.)
--   [Visualization Tutorial](https://mesa.readthedocs.io/en/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
+-   [Visualization Tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
 -   [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
     SugarScape with Traders, with instructional videos)
 -   [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples) (A repository of seminal ABMs using Mesa and
     examples of employing specific Mesa Features)
 -   [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
-    -   [Development version docs](https://mesa.readthedocs.io/en/latest/) (the latest version docs if you're using a pre-release Mesa version)
+    -   [Development version docs](https://mesa.readthedocs.io/latest/) (the latest version docs if you're using a pre-release Mesa version)
 -   [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)
 -   [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)
 

{mesa-2.3.4 → mesa-2.4.0}/README.md

@@ -7,7 +7,7 @@
 | Meta | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch) |
 | Chat | [![chat](https://img.shields.io/matrix/project-mesa:matrix.org?label=chat&logo=Matrix)](https://matrix.to/#/#project-mesa:matrix.org) |
 
-*This is the `2.3.x-maintenance` branch. Example models for Mesa 2.x can be found [here](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples).*
+*This is the `2.4.x-maintenance` branch. Example models for Mesa 2.x can be found [here](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples).*
 
 Mesa allows users to quickly create agent-based models using built-in
 core components (such as spatial grids and agent schedulers) or
@@ -53,13 +53,13 @@ For resources or help on using Mesa, check out the following:
 
 -   [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann
     Wealth Model, for beginners or those new to Mesa.)
--   [Visualization Tutorial](https://mesa.readthedocs.io/en/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
+-   [Visualization Tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
 -   [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
     SugarScape with Traders, with instructional videos)
 -   [Mesa Examples](https://github.com/projectmesa/mesa-examples/tree/mesa-2.x/examples) (A repository of seminal ABMs using Mesa and
     examples of employing specific Mesa Features)
 -   [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
-    -   [Development version docs](https://mesa.readthedocs.io/en/latest/) (the latest version docs if you're using a pre-release Mesa version)
+    -   [Development version docs](https://mesa.readthedocs.io/latest/) (the latest version docs if you're using a pre-release Mesa version)
 -   [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)
 -   [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)
 

{mesa-2.3.4 → mesa-2.4.0}/benchmarks/WolfSheep/wolf_sheep.py

@@ -227,8 +227,9 @@ class WolfSheep(Model):
             patch.move_to(cell)
 
     def step(self):
-        self.get_agents_of_type(Sheep).shuffle(inplace=True).do("step")
-        self.get_agents_of_type(Wolf).shuffle(inplace=True).do("step")
+        """Run one step of the model."""
+        self.agents_by_type[Sheep].shuffle_do("step")
+        self.agents_by_type[Wolf].shuffle_do("step")
 
 
 if __name__ == "__main__":

mesa-2.4.0/docs/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+    {
+        "name": "Stable",
+        "version": "stable",
+        "url": "https://mesa.readthedocs.io/stable/"
+    },
+    {
+        "name": "Latest",
+        "version": "latest",
+        "url": "https://mesa.readthedocs.io/latest/"
+    }
+]

{mesa-2.3.4 → mesa-2.4.0}/docs/conf.py

@@ -113,6 +113,8 @@ pygments_style = "gruvbox-dark"
 
 nb_execution_timeout = 60
 nb_execution_mode = "cache"
+nb_execution_allow_errors = False
+nb_execution_raise_on_error = True
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -123,7 +125,13 @@ html_theme = "pydata_sphinx_theme"
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "navbar_start": ["navbar-logo", "version-switcher"],  # Show switcher in navbar
+    "switcher": {
+        "json_url": "https://mesa.readthedocs.io/latest/_static/switcher.json",  # URL of your switcher.json file
+        "version_match": version  # Automatically matches the current version
+    }
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

{mesa-2.3.4 → mesa-2.4.0}/docs/index.md

@@ -81,6 +81,7 @@ ABM features users have shared that you may want to use in your model
 Mesa Overview <overview>
 tutorials/intro_tutorial
 tutorials/visualization_tutorial
+Migration guide <migration_guide>
 Best Practices <best-practices>
 How-to Guide <howto>
 API Documentation <apis/api_main>

mesa-2.4.0/docs/migration_guide.md

@@ -0,0 +1,294 @@
+# Mesa Migration guide
+This guide contains breaking changes between major Mesa versions and how to resolve them.
+
+Non-breaking changes aren't included, for those see our [Release history](https://github.com/projectmesa/mesa/releases).
+
+
+## Mesa 3.0
+Mesa 3.0 introduces significant changes to core functionalities, including agent and model initialization, scheduling, and visualization. The guide below outlines these changes and provides instructions for migrating your existing Mesa projects to version 3.0.
+
+_This guide is a work in progress. The development of it is tracked in [Issue #2233](https://github.com/projectmesa/mesa/issues/2233)._
+
+
+### Upgrade strategy
+We recommend the following upgrade strategy:
+- Update the the latest Mesa 2.x release (`mesa<3`).
+- Update the the latest Mesa 3.0.x release (`mesa<3.1`).
+- Update to the latest Mesa 3.x release (`mesa<4`).
+
+With each update, resolve all errors and warnings, before updating to the next one.
+
+
+### Reserved and private variables
+<!-- TODO: Update this section based on https://github.com/projectmesa/mesa/discussions/2230 -->
+
+#### Reserved variables
+Currently, we have reserved the following variables:
+  - Model: `agents`, `current_id`, `random`, `running`, `steps`, `time`.
+  - Agent: `unique_id`, `model`.
+
+You can use (read) any reserved variable, but Mesa may update them automatically and rely on them, so modify/update at your own risk.
+
+#### Private variables
+Any variables starting with an underscore (`_`) are considered private and for Mesa's internal use. We might use any of those. Modifying or overwriting any private variable is at your own risk.
+
+- Ref: [Discussion #2230](https://github.com/projectmesa/mesa/discussions/2230), [PR #2225](https://github.com/projectmesa/mesa/pull/2225)
+
+
+### Removal of `mesa.flat` namespace
+The `mesa.flat` namespace is removed. Use the full namespace for your imports.
+
+- Ref: [PR #2091](https://github.com/projectmesa/mesa/pull/2091)
+
+
+### Mandatory Model initialization with `super().__init__()`
+In Mesa 3.0, it is now mandatory to call `super().__init__()` when initializing your model class. This ensures that all necessary Mesa model variables are correctly set up and agents are properly added to the model.
+
+Make sure all your model classes explicitly call `super().__init__()` in their `__init__` method:
+
+```python
+class MyModel(mesa.Model):
+    def __init__(self, *args, **kwargs):
+        super().__init__()  # This is now required!
+        # Your model initialization code here
+```
+
+This change ensures that all Mesa models are properly initialized, which is crucial for:
+- Correctly adding agents to the model
+- Setting up other essential Mesa model variables
+- Maintaining consistency across all models
+
+If you forget to call `super().__init__()`, you'll now see this error:
+
+```
+RuntimeError: The Mesa Model class was not initialized. You must explicitly initialize the Model by calling super().__init__() on initialization.
+```
+
+- Ref: [PR #2218](https://github.com/projectmesa/mesa/pull/2218), [PR #1928](https://github.com/projectmesa/mesa/pull/1928), Mesa-examples [PR #83](https://github.com/projectmesa/mesa-examples/pull/83)
+
+
+### Automatic assignment of `unique_id` to Agents
+In Mesa 3.0, `unique_id` for agents is now automatically assigned, simplifying agent creation and ensuring unique IDs across all agents in a model.
+
+1. Remove `unique_id` from agent initialization:
+   ```python
+   # Old
+   agent = MyAgent(self.next_id(), self, ...)
+
+   # New
+   agent = MyAgent(self, ...)
+   ```
+2. `Model.next_id()` is deprecated and will always return 0. Remove any calls to this method.
+3. `unique_id` is now unique relative to a Model instance and starts from 1.
+4. If you previously used custom `unique_id` values, you'll need to store that information in a separate attribute.
+5. Deprecation warning: Initializing an agent with two arguments (`unique_id` and `model`) will raise a warning. The `unique_id` argument will be ignored.
+
+- Ref: [PR #2226](https://github.com/projectmesa/mesa/pull/2226), [PR #2260](https://github.com/projectmesa/mesa/pull/2260), Mesa-examples [PR #194](https://github.com/projectmesa/mesa-examples/pull/194), [Issue #2213](https://github.com/projectmesa/mesa/issues/2213)
+
+
+### AgentSet and `Model.agents`
+In Mesa 3.0, the Model class internally manages agents using several data structures:
+
+- `self._agents`: A dictionary containing hard references to all agents, indexed by their `unique_id`.
+- `self._agents_by_type`: A dictionary of AgentSets, organizing agents by their type.
+- `self._all_agents`: An AgentSet containing all agents in the model.
+
+These internal structures are used to efficiently manage and access agents. Users should interact with agents through the public `model.agents` property, which returns the `self._all_agents` AgentSet.
+
+#### `Model.agents`
+- Attempting to set `model.agents` now raises an `AttributeError` instead of a warning. This attribute is reserved for internal use by Mesa.
+- If you were previously setting `model.agents` in your code, you must update it to use a different attribute name for custom agent storage.
+
+For example, replace:
+```python
+model.agents = my_custom_agents
+```
+
+With:
+```python
+model.custom_agents = my_custom_agents
+```
+
+
+### Time and schedulers
+<!-- TODO general explanation-->
+
+#### Automatic increase of the `steps` counter
+The `steps` counter is now automatically increased. With each call to `Model.steps()` it's increased by 1, at the beginning of the step.
+
+You can access it by `Model.steps`, and it's internally in the datacollector, batchrunner and the visualisation.
+
+- Ref: [PR #2223](https://github.com/projectmesa/mesa/pull/2223), Mesa-examples [PR #161](https://github.com/projectmesa/mesa-examples/pull/161)
+
+#### Removal of `Model._time` and rename `._steps`
+- `Model._time` is removed. You can define your own time variable if needed.
+- `Model._steps` steps is renamed to `Model.steps`.
+
+#### Removal of `Model._advance_time()`
+- The `Model._advance_time()` method is removed. This now happens automatically.
+
+#### Replacing Schedulers with AgentSet functionality
+The whole Time module in Mesa is deprecated, and all schedulers are being replaced with AgentSet functionality and the internal `Model.steps` counter. This allows much more flexibility in how to activate Agents and makes it explicit what's done exactly.
+
+Here's how to replace each scheduler:
+
+##### BaseScheduler
+Replace:
+```python
+self.schedule = BaseScheduler(self)
+self.schedule.step()
+```
+With:
+```python
+self.agents.do("step")
+```
+
+##### RandomActivation
+Replace:
+```python
+self.schedule = RandomActivation(self)
+self.schedule.step()
+```
+With:
+```python
+self.agents.shuffle_do("step")
+```
+
+##### SimultaneousActivation
+Replace:
+```python
+self.schedule = SimultaneousActivation(self)
+self.schedule.step()
+```
+With:
+```python
+self.agents.do("step")
+self.agents.do("advance")
+```
+
+##### StagedActivation
+Replace:
+```python
+self.schedule = StagedActivation(self, ["stage1", "stage2", "stage3"])
+self.schedule.step()
+```
+With:
+```python
+for stage in ["stage1", "stage2", "stage3"]:
+    self.agents.do(stage)
+```
+
+If you were using the `shuffle` and/or `shuffle_between_stages` options:
+```python
+stages = ["stage1", "stage2", "stage3"]
+if shuffle:
+    self.random.shuffle(stages)
+for stage in stages:
+    if shuffle_between_stages:
+        self.agents.shuffle_do(stage)
+    else:
+        self.agents.do(stage)
+```
+
+##### RandomActivationByType
+Replace:
+```python
+self.schedule = RandomActivationByType(self)
+self.schedule.step()
+```
+With:
+```python
+for agent_class in self.agent_types:
+    self.agents_by_type[agent_class].shuffle_do("step")
+```
+
+###### Replacing `step_type`
+The `RandomActivationByType` scheduler had a `step_type` method that allowed stepping only agents of a specific type. To replicate this functionality using AgentSet:
+
+Replace:
+```python
+self.schedule.step_type(AgentType)
+```
+
+With:
+```python
+self.agents_by_type[AgentType].shuffle_do("step")
+```
+
+##### General Notes
+
+1. The `Model.steps` counter is now automatically incremented. You don't need to manage it manually.
+2. If you were using `self.schedule.agents`, replace it with `self.agents`.
+3. If you were using `self.schedule.get_agent_count()`, replace it with `len(self.agents)`.
+4. If you were using `self.schedule.agents_by_type`, replace it with `self.agents_by_type`.
+5. Instead of `self.schedule.add()` and `self.schedule.remove()`, agents are now automatically added to and removed from the model's AgentSet when they are created or removed.
+
+From now on you're now not bound by 5 distinct schedulers, but can mix and match any combination of AgentSet methods (`do`, `shuffle`, `select`, etc.) to get the desired Agent activation.
+
+Ref: Original discussion [#1912](https://github.com/projectmesa/mesa/discussions/1912), decision discussion [#2231](https://github.com/projectmesa/mesa/discussions/2231), example updates [#183](https://github.com/projectmesa/mesa-examples/pull/183) and [#201](https://github.com/projectmesa/mesa-examples/pull/201), PR [#2306](https://github.com/projectmesa/mesa/pull/2306)
+
+### Visualisation
+
+Mesa has adopted a new API for our frontend. If you already migrated to the experimental new SolaraViz you can still use
+the import from mesa.experimental. Otherwise here is a list of things you need to change.
+
+#### Model Initialization
+
+Previously SolaraViz was initialized by providing a `model_cls` and a `model_params`. This has changed to expect a model instance `model`. You can still provide (user-settable) `model_params`, but only if users should be able to change them. It is now also possible to pass in a "reactive model" by first calling `model = solara.reactive(model)`. This is useful for notebook environments. It allows you to pass the model to the SolaraViz Module, but continue to use the model. For example calling `model.value.step()` (notice the extra .value) will automatically update the plots. This currently only automatically works for the step method, you can force visualization updates by calling `model.value.force_update()`.
+
+#### Default space visualization
+
+Previously we included a default space drawer that you could configure with an `agent_portrayal` function. You now have to explicitly create a space drawer with the `agent_portrayal` function
+
+```python
+# old
+from mesa.experimental import SolaraViz
+
+SolaraViz(model_cls, model_params, agent_portrayal=agent_portrayal)
+
+# new
+from mesa.visualization import SolaraViz, make_space_matplotlib
+
+SolaraViz(model, components=[make_space_matplotlib(agent_portrayal)])
+```
+
+#### Plotting "measures"
+
+"Measure" plots also need to be made explicit here. Previously, measure could either be 1) A function that receives a model and returns a solara component or 2) A string or list of string of variables that are collected by the datacollector and are to be plotted as a line plot. 1) still works, but you can pass that function to "components" directly. 2) needs to explicitly call the `make_plot_measure()`function.
+
+```python
+# old
+from mesa.experimental import SolaraViz
+
+def make_plot(model):
+    ...
+
+SolaraViz(model_cls, model_params, measures=[make_plot, "foo", ["bar", "baz"]])
+
+# new
+from mesa.visualization import SolaraViz, make_plot_measure
+
+SolaraViz(model, components=[make_plot, make_plot_measure("foo"), make_plot_measure("bar", "baz")])
+```
+
+#### Plotting text
+
+To plot model-dependent text the experimental SolaraViz provided a `make_text` function that wraps another functions that receives the model and turns its string return value into a solara text component. Again, this other function can now be passed directly to the new SolaraViz components array. It is okay if your function just returns a string.
+
+```python
+# old
+from mesa.experimental import SolaraViz, make_text
+
+def show_steps(model):
+    return f"Steps: {model.steps}"
+
+SolaraViz(model_cls, model_params, measures=make_text(show_steps))
+
+# new
+from mesa.visualisation import SolaraViz
+
+def show_steps(model):
+    return f"Steps: {model.steps}"
+
+SolaraViz(model, components=[show_steps])
+```

{mesa-2.3.4 → mesa-2.4.0}/docs/overview.md

@@ -60,6 +60,55 @@ You should see agents 0-4, activated in random order. See the [tutorial](tutoria
 
 To bootstrap a new model install mesa and run `mesa startproject`
 
+### AgentSet and model.agents
+Mesa 3.0 makes `model.agents` and the AgentSet class central in managing and activating agents.
+
+#### model.agents
+`model.agents` is an AgentSet containing all agents in the model. It's automatically updated when agents are added or removed:
+
+```python
+# Get total number of agents
+num_agents = len(model.agents)
+
+# Iterate over all agents
+for agent in model.agents:
+    print(agent.unique_id)
+```
+
+#### AgentSet Functionality
+AgentSet offers several methods for efficient agent management:
+
+1. **Selecting**: Filter agents based on criteria.
+   ```python
+   high_energy_agents = model.agents.select(lambda a: a.energy > 50)
+   ```
+2. **Shuffling and Sorting**: Randomize or order agents.
+   ```python
+   shuffled_agents = model.agents.shuffle()
+   sorted_agents = model.agents.sort(key="energy", ascending=False)
+   ```
+3. **Applying methods**: Execute methods on all agents.
+   ```python
+   model.agents.do("step")
+   model.agents.shuffle_do("move")  # Shuffle then apply method
+   ```
+4. **Aggregating**: Compute aggregate values across agents.
+   ```python
+   avg_energy = model.agents.agg("energy", func=np.mean)
+   ```
+5. **Grouping**: Group agents by attributes.
+   ```python
+   grouped_agents = model.agents.groupby("species")
+
+   for _, agent_group in grouped_agents:
+      agent_group.shuffle_do()
+   species_counts = grouped_agents.count()
+   mean_age_by_group = grouped_agents.agg("age", np.mean)
+   ```
+`model.agents` can also be accessed within a model instance using `self.agents`.
+
+These are just some examples of using the AgentSet, there are many more possibilities
+
 ### Analysis modules
 
 If you're using modeling for research, you'll want a way to collect the data each model run generates. You'll probably also want to run the model multiple times, to see how some output changes with different parameters. Data collection and batch running are implemented in the appropriately-named analysis modules:

{mesa-2.3.4 → mesa-2.4.0}/docs/packages.md

@@ -73,9 +73,9 @@ Most likely you created an ABM that has the code that you want to share in it, w
 
 **Sharing your package**
 
-> 1. Layout a new file structure to move the code into and then make sure it is callable from Mesa, in a simple, easy to understand way. For example, `from example_package import foo`.  See [Creating the Scaffolding](https://python-packaging.readthedocs.io/en/latest/minimal.html#creating-the-scaffolding).
+> 1. Layout a new file structure to move the code into and then make sure it is callable from Mesa, in a simple, easy to understand way. For example, `from example_package import foo`.  See [Creating the Scaffolding](https://python-packaging.readthedocs.io/latest/minimal.html#creating-the-scaffolding).
 >
-> 2. [Pick a name](https://python-packaging.readthedocs.io/en/latest/minimal.html#picking-a-name).
+> 2. [Pick a name](https://python-packaging.readthedocs.io/latest/minimal.html#picking-a-name).
 >
 > 3. [Create a repo on GitHub](https://help.github.com/articles/create-a-repo/).
 >

{mesa-2.3.4 → mesa-2.4.0}/docs/tutorials/adv_tutorial_legacy.ipynb

@@ -29,7 +29,7 @@
    "source": [
     "#### Grid Visualization\n",
     "\n",
-    "To start with, let's have a visualization where we can watch the agents moving around the grid. For this, you will need to put your model code in a separate Python source file. For now, let us use the `MoneyModel` created in the [Introductory Tutorial](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html) saved to `MoneyModel.py` file provided.\n",
+    "To start with, let's have a visualization where we can watch the agents moving around the grid. For this, you will need to put your model code in a separate Python source file. For now, let us use the `MoneyModel` created in the [Introductory Tutorial](https://mesa.readthedocs.io/stable/tutorials/intro_tutorial.html) saved to `MoneyModel.py` file provided.\n",
     "Next, in a new source file (e.g. `MoneyModel_Viz.py`) include the code shown in the following cells to run and avoid Jupyter compatibility issue."
    ]
   },

{mesa-2.3.4 → mesa-2.4.0}/docs/tutorials/intro_tutorial.ipynb

@@ -29,9 +29,9 @@
     "\n",
     "### More Tutorials: \n",
     "\n",
-    "Visualization: There is a separate [visualization tutorial](https://mesa.readthedocs.io/en/stable/tutorials/visualization_tutorial.html) that will take users through building a visualization for this model (aka Boltzmann Wealth Model).\n",
+    "Visualization: There is a separate [visualization tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) that will take users through building a visualization for this model (aka Boltzmann Wealth Model).\n",
     "\n",
-    "Advanced Visualization (legacy): There is also an [advanced visualization tutorial](https://mesa.readthedocs.io/en/stable/tutorials/adv_tutorial_legacy.html) that will show users how to use the JavaScript based visualization option, which also uses this model as its base. "
+    "Advanced Visualization (legacy): There is also an [advanced visualization tutorial](https://mesa.readthedocs.io/stable/tutorials/adv_tutorial_legacy.html) that will show users how to use the JavaScript based visualization option, which also uses this model as its base. "
    ]
   },
   {

{mesa-2.3.4 → mesa-2.4.0}/docs/tutorials/visualization_tutorial.ipynb

@@ -28,7 +28,7 @@
    "source": [
     "#### Grid Visualization\n",
     "\n",
-    "To start with, let's have a visualization where we can watch the agents moving around the grid. Let us use the same `MoneyModel` created in the [Introductory Tutorial](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html).\n"
+    "To start with, let's have a visualization where we can watch the agents moving around the grid. Let us use the same `MoneyModel` created in the [Introductory Tutorial](https://mesa.readthedocs.io/stable/tutorials/intro_tutorial.html).\n"
    ]
   },
   {

{mesa-2.3.4 → mesa-2.4.0}/mesa/__init__.py

@@ -26,7 +26,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "2.3.4"
+__version__ = "2.4.0"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"