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

README.md

@@ -28,7 +28,7 @@ can be displayed in browser windows or Jupyter.*
 
 ## Using Mesa
 
-To install our latest stable release (2.3.x), run:
+To install our latest stable release (2.4.x), run:
 
 ``` bash
 pip install -U mesa
@@ -60,7 +60,7 @@ For resources or help on using Mesa, check out the following:
 -   [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/main/examples) (A repository of seminal ABMs using Mesa and
+-   [Mesa Examples](https://github.com/projectmesa/mesa-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/latest/) (the latest version docs if you're using a pre-release Mesa version)

docs/index.md

@@ -38,10 +38,16 @@ notebook.*
 
 ## Using Mesa
 
-Getting started quickly:
+To install our latest stable release (2.4.x), run:
 
-```bash
-pip install mesa
+``` bash
+pip install -U mesa
+```
+
+To install our latest pre-release (3.0 alpha), run:
+
+``` bash
+pip install -U --pre mesa
 ```
 
 To launch an example model, clone the [repository](https://github.com/projectmesa/mesa) folder and invoke `mesa runserver` for one of the `examples/` subdirectories:
@@ -52,8 +58,10 @@ mesa runserver examples/wolf_sheep
 
 For more help on using Mesa, check out the following resources:
 
+- [Mesa Overview]
 - [Mesa Introductory Tutorial]
 - [Mesa Visualization Tutorial]
+- [Mesa Examples]
 - [GitHub Issue Tracker]
 - [Matrix chat room]
 - [PyPI]
@@ -99,6 +107,8 @@ Mesa Packages <packages>
 [github issue tracker]: https://github.com/projectmesa/mesa/issues
 [matrix chat room]: https://matrix.to/#/#project-mesa:matrix.org
 [mesa]: https://github.com/projectmesa/mesa/
+[mesa overview]: overview
+[mesa examples]: https://github.com/projectmesa/mesa-examples
 [mesa introductory tutorial]: tutorials/intro_tutorial
 [mesa visualization tutorial]: tutorials/visualization_tutorial
 [pypi]: https://pypi.python.org/pypi/Mesa/

docs/migration_guide.md

@@ -221,7 +221,10 @@ self.agents_by_type[AgentType].shuffle_do("step")
 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.
+5. Agents are now automatically added to or removed from the model's `AgentSet` (`model.agents`) when they are created or deleted, eliminating the need to manually call `self.schedule.add()` or `self.schedule.remove()`.
+   - However, you still need to explicitly remove the Agent itself by using `Agent.remove()`. Typically, this means:
+     - Replace `self.schedule.remove(agent)` with `agent.remove()` in the Model.
+     - Replace `self.model.schedule.remove(self)` with `self.remove()` within the Agent.
 
 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.
 

mesa/agent.py

@@ -46,39 +46,25 @@ class Agent:
     # so, unique_id is unique relative to a model, and counting starts from 1
     _ids = defaultdict(functools.partial(itertools.count, 1))
 
-    def __init__(self, *args, **kwargs) -> None:
+    def __init__(self, model: Model, *args, **kwargs) -> None:
         """Create a new agent.
 
         Args:
             model (Model): The model instance in which the agent exists.
-            args: currently ignored, to be fixed in 3.1
-            kwargs: currently ignored, to be fixed in 3.1
-        """
-        # TODO: Cleanup in future Mesa version (3.1+)
-        match args:
-            # Case 1: Only the model is provided. The new correct behavior.
-            case [model]:
-                self.model = model
-                self.unique_id = next(self._ids[model])
-            # Case 2: Both unique_id and model are provided, deprecated
-            case [_, model]:
-                warnings.warn(
-                    "unique ids are assigned automatically to Agents in Mesa 3. The use of custom unique_id is "
-                    "deprecated. Only input a model when calling `super()__init__(model)`. The unique_id inputted is not used.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
-                self.model = model
-                self.unique_id = next(self._ids[model])
-            # Case 3: Anything else, raise an error
-            case _:
-                raise ValueError(
-                    "Invalid arguments provided to initialize the Agent. Only input a model: `super()__init__(model)`."
-                )
+            args: passed on to super
+            kwargs: passed on to super
 
-        self.pos: Position | None = None
+        Notes:
+            to make proper use of python's super, in each class remove the arguments and
+            keyword arguments you need and pass on the rest to super
 
+        """
+        super().__init__(*args, **kwargs)
+
+        self.model: Model = model
         self.model.register_agent(self)
+        self.unique_id: int = next(self._ids[model])
+        self.pos: Position | None = None
 
     def remove(self) -> None:
         """Remove and delete the agent from the model."""

tests/test_agent.py

@@ -301,7 +301,7 @@ def remove_function(agent):
 def test_agentset_get():
     """Test AgentSet.get."""
     model = Model()
-    _ = [TestAgent(i, model) for i in range(10)]
+    _ = [TestAgent(model) for i in range(10)]
 
     agentset = model.agents
 
@@ -627,16 +627,3 @@ def custom_agg(values):
     assert custom_result[False] == custom_agg(
         [agent.value for agent in agents if not agent.even]
     )
-
-
-def test_oldstyle_agent_instantiation():
-    """Old behavior of Agent creation with unique_id and model as positional arguments.
-
-    Can be removed/updated in the future.
-    """
-    model = Model()
-    agent = Agent("some weird unique id", model)
-    assert isinstance(agent.unique_id, int)
-    assert agent.model == model
-    assert isinstance(agent.model, Model)
-    assert agent.unique_id == 1  # test that we ignore unique ID that is passed