Merge remote-tracking branch 'upstream/main' into signal

HISTORY.md

@@ -19,7 +19,8 @@ self.datacollector = DataCollector(
 ```
 
 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)).
-<!--- TODO: Add #2307, #2308, #2309  --->
+
+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.
 
@@ -34,13 +35,17 @@ While the Mesa 3.0 timeline is still being discussed, we're aiming at the first
 * 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

docs/migration_guide.md

@@ -3,11 +3,22 @@ This guide contains breaking changes between major Mesa versions and how to reso
 
 Non-breaking changes aren't included, for those see our [Release history](https://github.com/projectmesa/mesa/releases).
 
+
 ## Mesa 3.0
-<!-- TODO small introduction-->
+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 -->
 
@@ -17,6 +28,7 @@ Currently, we have reserved the following variables:
   - 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.
 
@@ -75,11 +87,27 @@ In Mesa 3.0, `unique_id` for agents is now automatically assigned, simplifying a
 
 
 ### AgentSet and `Model.agents`
-#### AgentSet
-<!-- TODO  -->
+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`
-<!-- TODO  -->
+- 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
@@ -99,12 +127,12 @@ You can access it by `Model.steps`, and it's internally in the datacollector, ba
 #### Removal of `Model._advance_time()`
 - The `Model._advance_time()` method is removed. This now happens automatically.
 
-### Replacing Schedulers with AgentSet functionality
+#### 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
+##### BaseScheduler
 Replace:
 ```python
 self.schedule = BaseScheduler(self)
@@ -115,7 +143,7 @@ With:
 self.agents.do("step")
 ```
 
-#### RandomActivation
+##### RandomActivation
 Replace:
 ```python
 self.schedule = RandomActivation(self)
@@ -126,7 +154,7 @@ With:
 self.agents.shuffle_do("step")
 ```
 
-#### SimultaneousActivation
+##### SimultaneousActivation
 Replace:
 ```python
 self.schedule = SimultaneousActivation(self)
@@ -138,7 +166,7 @@ self.agents.do("step")
 self.agents.do("advance")
 ```
 
-#### StagedActivation
+##### StagedActivation
 Replace:
 ```python
 self.schedule = StagedActivation(self, ["stage1", "stage2", "stage3"])
@@ -162,7 +190,7 @@ for stage in stages:
         self.agents.do(stage)
 ```
 
-#### RandomActivationByType
+##### RandomActivationByType
 Replace:
 ```python
 self.schedule = RandomActivationByType(self)
@@ -174,7 +202,7 @@ for agent_class in self.agent_types:
     self.agents_by_type[agent_class].shuffle_do("step")
 ```
 
-##### Replacing `step_type`
+###### 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:
@@ -187,7 +215,7 @@ With:
 self.agents_by_type[AgentType].shuffle_do("step")
 ```
 
-#### General Notes
+##### 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`.