Mesa 3.0.0a2__py3-none-any.whl → 3.0.0a3__py3-none-any.whl

mesa/__init__.py

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

mesa/agent.py

@@ -11,7 +11,9 @@ from __future__ import annotations
 import contextlib
 import copy
 import operator
+import warnings
 import weakref
+from collections import defaultdict
 from collections.abc import Callable, Iterable, Iterator, MutableSet, Sequence
 from random import Random
 
@@ -47,19 +49,12 @@ class Agent:
         self.model = model
         self.pos: Position | None = None
 
-        # register agent
-        try:
-            self.model.agents_[type(self)][self] = None
-        except AttributeError as err:
-            # model super has not been called
-            raise RuntimeError(
-                "The Mesa Model class was not initialized. You must explicitly initialize the Model by calling super().__init__() on initialization."
-            ) from err
+        self.model.register_agent(self)
 
     def remove(self) -> None:
         """Remove and delete the agent from the model."""
         with contextlib.suppress(KeyError):
-            self.model.agents_[type(self)].pop(self)
+            self.model.deregister_agent(self)
 
     def step(self) -> None:
         """A single step of the agent."""
@@ -119,9 +114,10 @@ class AgentSet(MutableSet, Sequence):
     def select(
         self,
         filter_func: Callable[[Agent], bool] | None = None,
-        n: int = 0,
+        at_most: int | float = float("inf"),
         inplace: bool = False,
         agent_type: type[Agent] | None = None,
+        n: int | None = None,
     ) -> AgentSet:
         """
         Select a subset of agents from the AgentSet based on a filter function and/or quantity limit.
@@ -129,29 +125,47 @@ class AgentSet(MutableSet, Sequence):
         Args:
             filter_func (Callable[[Agent], bool], optional): A function that takes an Agent and returns True if the
                 agent should be included in the result. Defaults to None, meaning no filtering is applied.
-            n (int, optional): The number of agents to select. If 0, all matching agents are selected. Defaults to 0.
+            at_most (int | float, optional): The maximum amount of agents to select. Defaults to infinity.
+              - If an integer, at most the first number of matching agents are selected.
+              - If a float between 0 and 1, at most that fraction of original the agents are selected.
             inplace (bool, optional): If True, modifies the current AgentSet; otherwise, returns a new AgentSet. Defaults to False.
             agent_type (type[Agent], optional): The class type of the agents to select. Defaults to None, meaning no type filtering is applied.
 
         Returns:
             AgentSet: A new AgentSet containing the selected agents, unless inplace is True, in which case the current AgentSet is updated.
+
+        Notes:
+            - at_most just return the first n or fraction of agents. To take a random sample, shuffle() beforehand.
+            - at_most is an upper limit. When specifying other criteria, the number of agents returned can be smaller.
         """
+        if n is not None:
+            warnings.warn(
+                "The parameter 'n' is deprecated. Use 'at_most' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            at_most = n
 
-        if filter_func is None and agent_type is None and n == 0:
+        inf = float("inf")
+        if filter_func is None and agent_type is None and at_most == inf:
             return self if inplace else copy.copy(self)
 
-        def agent_generator(filter_func=None, agent_type=None, n=0):
+        # Check if at_most is of type float
+        if at_most <= 1.0 and isinstance(at_most, float):
+            at_most = int(len(self) * at_most)  # Note that it rounds down (floor)
+
+        def agent_generator(filter_func, agent_type, at_most):
             count = 0
             for agent in self:
+                if count >= at_most:
+                    break
                 if (not filter_func or filter_func(agent)) and (
                     not agent_type or isinstance(agent, agent_type)
                 ):
                     yield agent
                     count += 1
-                    if 0 < n <= count:
-                        break
 
-        agents = agent_generator(filter_func, agent_type, n)
+        agents = agent_generator(filter_func, agent_type, at_most)
 
         return AgentSet(agents, self.model) if not inplace else self._update(agents)
 
@@ -216,25 +230,64 @@ class AgentSet(MutableSet, Sequence):
         self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
         return self
 
-    def do(
-        self, method: str | Callable, *args, return_results: bool = False, **kwargs
-    ) -> AgentSet | list[Any]:
+    def do(self, method: str | Callable, *args, **kwargs) -> AgentSet:
         """
         Invoke a method or function on each agent in the AgentSet.
 
         Args:
-            method (str, callable): the callable to do on each agents
+            method (str, callable): the callable to do on each agent
 
                                         * in case of str, the name of the method to call on each agent.
                                         * in case of callable, the function to be called with each agent as first argument
 
-            return_results (bool, optional): If True, returns the results of the method calls; otherwise, returns the AgentSet itself. Defaults to False, so you can chain method calls.
             *args: Variable length argument list passed to the callable being called.
             **kwargs: Arbitrary keyword arguments passed to the callable being called.
 
         Returns:
             AgentSet | list[Any]: The results of the callable calls if return_results is True, otherwise the AgentSet itself.
         """
+        try:
+            return_results = kwargs.pop("return_results")
+        except KeyError:
+            return_results = False
+        else:
+            warnings.warn(
+                "Using return_results is deprecated. Use AgenSet.do in case of return_results=False, and "
+                "AgentSet.map in case of return_results=True",
+                stacklevel=2,
+            )
+
+        if return_results:
+            return self.map(method, *args, **kwargs)
+
+        # we iterate over the actual weakref keys and check if weakref is alive before calling the method
+        if isinstance(method, str):
+            for agentref in self._agents.keyrefs():
+                if (agent := agentref()) is not None:
+                    getattr(agent, method)(*args, **kwargs)
+        else:
+            for agentref in self._agents.keyrefs():
+                if (agent := agentref()) is not None:
+                    method(agent, *args, **kwargs)
+
+        return self
+
+    def map(self, method: str | Callable, *args, **kwargs) -> list[Any]:
+        """
+        Invoke a method or function on each agent in the AgentSet and return the results.
+
+        Args:
+            method (str, callable): the callable to apply on each agent
+
+                                        * in case of str, the name of the method to call on each agent.
+                                        * in case of callable, the function to be called with each agent as first argument
+
+            *args: Variable length argument list passed to the callable being called.
+            **kwargs: Arbitrary keyword arguments passed to the callable being called.
+
+        Returns:
+           list[Any]: The results of the callable calls
+        """
         # we iterate over the actual weakref keys and check if weakref is alive before calling the method
         if isinstance(method, str):
             res = [
@@ -249,7 +302,7 @@ class AgentSet(MutableSet, Sequence):
                 if (agent := agentref()) is not None
             ]
 
-        return res if return_results else self
+        return res
 
     def get(self, attr_names: str | list[str]) -> list[Any]:
         """
@@ -275,6 +328,21 @@ class AgentSet(MutableSet, Sequence):
                 for agent in self._agents
             ]
 
+    def set(self, attr_name: str, value: Any) -> AgentSet:
+        """
+        Set a specified attribute to a given value for all agents in the AgentSet.
+
+        Args:
+            attr_name (str): The name of the attribute to set.
+            value (Any): The value to set the attribute to.
+
+        Returns:
+            AgentSet: The AgentSet instance itself, after setting the attribute.
+        """
+        for agent in self:
+            setattr(agent, attr_name, value)
+        return self
+
     def __getitem__(self, item: int | slice) -> Agent:
         """
         Retrieve an agent or a slice of agents from the AgentSet.
@@ -357,7 +425,116 @@ class AgentSet(MutableSet, Sequence):
         """
         return self.model.random
 
+    def groupby(self, by: Callable | str, result_type: str = "agentset") -> GroupBy:
+        """
+        Group agents by the specified attribute or return from the callable
+
+        Args:
+            by (Callable, str): used to determine what to group agents by
+
+                                * if ``by`` is a callable, it will be called for each agent and the return is used
+                                  for grouping
+                                * if ``by`` is a str, it should refer to an attribute on the agent and the value
+                                  of this attribute will be used for grouping
+            result_type (str, optional): The datatype for the resulting groups {"agentset", "list"}
+        Returns:
+            GroupBy
+
+
+        Notes:
+        There might be performance benefits to using `result_type='list'` if you don't need the advanced functionality
+        of an AgentSet.
+
+        """
+        groups = defaultdict(list)
+
+        if isinstance(by, Callable):
+            for agent in self:
+                groups[by(agent)].append(agent)
+        else:
+            for agent in self:
+                groups[getattr(agent, by)].append(agent)
+
+        if result_type == "agentset":
+            return GroupBy(
+                {k: AgentSet(v, model=self.model) for k, v in groups.items()}
+            )
+        else:
+            return GroupBy(groups)
+
+    # consider adding for performance reasons
+    # for Sequence: __reversed__, index, and count
+    # for MutableSet clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
+
+
+class GroupBy:
+    """Helper class for AgentSet.groupby
+
+
+    Attributes:
+        groups (dict): A dictionary with the group_name as key and group as values
+
+    """
+
+    def __init__(self, groups: dict[Any, list | AgentSet]):
+        self.groups: dict[Any, list | AgentSet] = groups
+
+    def map(self, method: Callable | str, *args, **kwargs) -> dict[Any, Any]:
+        """Apply the specified callable to each group and return the results.
+
+        Args:
+            method (Callable, str): The callable to apply to each group,
+
+                                    * if ``method`` is a callable, it will be called it will be called with the group as first argument
+                                    * if ``method`` is a str, it should refer to a method on the group
+
+                                    Additional arguments and keyword arguments will be passed on to the callable.
+
+        Returns:
+            dict with group_name as key and the return of the method as value
+
+        Notes:
+            this method is useful for methods or functions that do return something. It
+            will break method chaining. For that, use ``do`` instead.
+
+        """
+        if isinstance(method, str):
+            return {
+                k: getattr(v, method)(*args, **kwargs) for k, v in self.groups.items()
+            }
+        else:
+            return {k: method(v, *args, **kwargs) for k, v in self.groups.items()}
+
+    def do(self, method: Callable | str, *args, **kwargs) -> GroupBy:
+        """Apply the specified callable to each group
+
+        Args:
+            method (Callable, str): The callable to apply to each group,
+
+                                    * if ``method`` is a callable, it will be called it will be called with the group as first argument
+                                    * if ``method`` is a str, it should refer to a method on the group
+
+                                    Additional arguments and keyword arguments will be passed on to the callable.
+
+        Returns:
+            the original GroupBy instance
+
+        Notes:
+            this method is useful for methods or functions that don't return anything and/or
+            if you want to chain multiple do calls
+
+        """
+        if isinstance(method, str):
+            for v in self.groups.values():
+                getattr(v, method)(*args, **kwargs)
+        else:
+            for v in self.groups.values():
+                method(v, *args, **kwargs)
+
+        return self
+
+    def __iter__(self):
+        return iter(self.groups.items())
 
-# consider adding for performance reasons
-# for Sequence: __reversed__, index, and count
-# for MutableSet clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
+    def __len__(self):
+        return len(self.groups)

mesa/batchrunner.py

@@ -132,14 +132,14 @@ def _model_run_func(
     """
     run_id, iteration, kwargs = run
     model = model_cls(**kwargs)
-    while model.running and model._steps <= max_steps:
+    while model.running and model.steps <= max_steps:
         model.step()
 
     data = []
 
-    steps = list(range(0, model._steps, data_collection_period))
-    if not steps or steps[-1] != model._steps - 1:
-        steps.append(model._steps - 1)
+    steps = list(range(0, model.steps, data_collection_period))
+    if not steps or steps[-1] != model.steps - 1:
+        steps.append(model.steps - 1)
 
     for step in steps:
         model_data, all_agents_data = _collect_data(model, step)

mesa/datacollection.py

@@ -180,7 +180,7 @@ class DataCollector:
         rep_funcs = self.agent_reporters.values()
 
         def get_reports(agent):
-            _prefix = (agent.model._steps, agent.unique_id)
+            _prefix = (agent.model.steps, agent.unique_id)
             reports = tuple(rep(agent) for rep in rep_funcs)
             return _prefix + reports
 
@@ -216,7 +216,7 @@ class DataCollector:
 
         if self.agent_reporters:
             agent_records = self._record_agents(model)
-            self._agent_records[model._steps] = list(agent_records)
+            self._agent_records[model.steps] = list(agent_records)
 
     def add_table_row(self, table_name, row, ignore_missing=False):
         """Add a row dictionary to a specific table.

mesa/experimental/cell_space/__init__.py

@@ -9,6 +9,7 @@ from mesa.experimental.cell_space.grid import (
     OrthogonalVonNeumannGrid,
 )
 from mesa.experimental.cell_space.network import Network
+from mesa.experimental.cell_space.voronoi import VoronoiGrid
 
 __all__ = [
     "CellCollection",
@@ -20,4 +21,5 @@ __all__ = [
     "OrthogonalMooreGrid",
     "OrthogonalVonNeumannGrid",
     "Network",
+    "VoronoiGrid",
 ]

mesa/experimental/cell_space/voronoi.py

@@ -0,0 +1,264 @@
+from collections.abc import Sequence
+from itertools import combinations
+from random import Random
+
+import numpy as np
+
+from mesa.experimental.cell_space.cell import Cell
+from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+
+
+class Delaunay:
+    """
+    Class to compute a Delaunay triangulation in 2D
+    ref: http://github.com/jmespadero/pyDelaunay2D
+    """
+
+    def __init__(self, center: tuple = (0, 0), radius: int = 9999) -> None:
+        """
+        Init and create a new frame to contain the triangulation
+        center: Optional position for the center of the frame. Default (0,0)
+        radius: Optional distance from corners to the center.
+        """
+        center = np.asarray(center)
+        # Create coordinates for the corners of the frame
+        self.coords = [
+            center + radius * np.array((-1, -1)),
+            center + radius * np.array((+1, -1)),
+            center + radius * np.array((+1, +1)),
+            center + radius * np.array((-1, +1)),
+        ]
+
+        # Create two dicts to store triangle neighbours and circumcircles.
+        self.triangles = {}
+        self.circles = {}
+
+        # Create two CCW triangles for the frame
+        triangle1 = (0, 1, 3)
+        triangle2 = (2, 3, 1)
+        self.triangles[triangle1] = [triangle2, None, None]
+        self.triangles[triangle2] = [triangle1, None, None]
+
+        # Compute circumcenters and circumradius for each triangle
+        for t in self.triangles:
+            self.circles[t] = self._circumcenter(t)
+
+    def _circumcenter(self, triangle: list) -> tuple:
+        """
+        Compute circumcenter and circumradius of a triangle in 2D.
+        """
+        points = np.asarray([self.coords[v] for v in triangle])
+        points2 = np.dot(points, points.T)
+        a = np.bmat([[2 * points2, [[1], [1], [1]]], [[[1, 1, 1, 0]]]])
+
+        b = np.hstack((np.sum(points * points, axis=1), [1]))
+        x = np.linalg.solve(a, b)
+        bary_coords = x[:-1]
+        center = np.dot(bary_coords, points)
+
+        radius = np.sum(np.square(points[0] - center))  # squared distance
+        return (center, radius)
+
+    def _in_circle(self, triangle: list, point: list) -> bool:
+        """
+        Check if point p is inside of precomputed circumcircle of triangle.
+        """
+        center, radius = self.circles[triangle]
+        return np.sum(np.square(center - point)) <= radius
+
+    def add_point(self, point: Sequence) -> None:
+        """
+        Add a point to the current DT, and refine it using Bowyer-Watson.
+        """
+        point_index = len(self.coords)
+        self.coords.append(np.asarray(point))
+
+        bad_triangles = []
+        for triangle in self.triangles:
+            if self._in_circle(triangle, point):
+                bad_triangles.append(triangle)
+
+        boundary = []
+        triangle = bad_triangles[0]
+        edge = 0
+
+        while True:
+            opposite_triangle = self.triangles[triangle][edge]
+            if opposite_triangle not in bad_triangles:
+                boundary.append(
+                    (
+                        triangle[(edge + 1) % 3],
+                        triangle[(edge - 1) % 3],
+                        opposite_triangle,
+                    )
+                )
+                edge = (edge + 1) % 3
+                if boundary[0][0] == boundary[-1][1]:
+                    break
+            else:
+                edge = (self.triangles[opposite_triangle].index(triangle) + 1) % 3
+                triangle = opposite_triangle
+
+        for triangle in bad_triangles:
+            del self.triangles[triangle]
+            del self.circles[triangle]
+
+        new_triangles = []
+        for e0, e1, opposite_triangle in boundary:
+            triangle = (point_index, e0, e1)
+            self.circles[triangle] = self._circumcenter(triangle)
+            self.triangles[triangle] = [opposite_triangle, None, None]
+            if opposite_triangle:
+                for i, neighbor in enumerate(self.triangles[opposite_triangle]):
+                    if neighbor and e1 in neighbor and e0 in neighbor:
+                        self.triangles[opposite_triangle][i] = triangle
+
+            new_triangles.append(triangle)
+
+        n = len(new_triangles)
+        for i, triangle in enumerate(new_triangles):
+            self.triangles[triangle][1] = new_triangles[(i + 1) % n]  # next
+            self.triangles[triangle][2] = new_triangles[(i - 1) % n]  # previous
+
+    def export_triangles(self) -> list:
+        """
+        Export the current list of Delaunay triangles
+        """
+        triangles_list = [
+            (a - 4, b - 4, c - 4)
+            for (a, b, c) in self.triangles
+            if a > 3 and b > 3 and c > 3
+        ]
+        return triangles_list
+
+    def export_voronoi_regions(self):
+        """
+        Export coordinates and regions of Voronoi diagram as indexed data.
+        """
+        use_vertex = {i: [] for i in range(len(self.coords))}
+        vor_coors = []
+        index = {}
+        for triangle_index, (a, b, c) in enumerate(sorted(self.triangles)):
+            vor_coors.append(self.circles[(a, b, c)][0])
+            use_vertex[a] += [(b, c, a)]
+            use_vertex[b] += [(c, a, b)]
+            use_vertex[c] += [(a, b, c)]
+
+            index[(a, b, c)] = triangle_index
+            index[(c, a, b)] = triangle_index
+            index[(b, c, a)] = triangle_index
+
+        regions = {}
+        for i in range(4, len(self.coords)):
+            vertex = use_vertex[i][0][0]
+            region = []
+            for _ in range(len(use_vertex[i])):
+                triangle = next(
+                    triangle for triangle in use_vertex[i] if triangle[0] == vertex
+                )
+                region.append(index[triangle])
+                vertex = triangle[1]
+            regions[i - 4] = region
+
+        return vor_coors, regions
+
+
+def round_float(x: float) -> int:
+    return int(x * 500)
+
+
+class VoronoiGrid(DiscreteSpace):
+    triangulation: Delaunay
+    voronoi_coordinates: list
+    regions: list
+
+    def __init__(
+        self,
+        centroids_coordinates: Sequence[Sequence[float]],
+        capacity: float | None = None,
+        random: Random | None = None,
+        cell_klass: type[Cell] = Cell,
+        capacity_function: callable = round_float,
+        cell_coloring_property: str | None = None,
+    ) -> None:
+        """
+        A Voronoi Tessellation Grid.
+
+        Given a set of points, this class creates a grid where a cell is centered in each point,
+        its neighbors are given by Voronoi Tessellation cells neighbors
+        and the capacity by the polygon area.
+
+        Args:
+            centroids_coordinates: coordinates of centroids to build the tessellation space
+            capacity (int) : capacity of the cells in the discrete space
+            random (Random): random number generator
+            CellKlass (type[Cell]): type of cell class
+            capacity_function (Callable): function to compute (int) capacity according to (float) area
+            cell_coloring_property (str): voronoi visualization polygon fill property
+        """
+        super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
+        self.centroids_coordinates = centroids_coordinates
+        self._validate_parameters()
+
+        self._cells = {
+            i: cell_klass(self.centroids_coordinates[i], capacity, random=self.random)
+            for i in range(len(self.centroids_coordinates))
+        }
+
+        self.regions = None
+        self.triangulation = None
+        self.voronoi_coordinates = None
+        self.capacity_function = capacity_function
+        self.cell_coloring_property = cell_coloring_property
+
+        self._connect_cells()
+        self._build_cell_polygons()
+
+    def _connect_cells(self) -> None:
+        """
+        Connect cells to neighbors based on given centroids and using Delaunay Triangulation
+        """
+        self.triangulation = Delaunay()
+        for centroid in self.centroids_coordinates:
+            self.triangulation.add_point(centroid)
+
+        for point in self.triangulation.export_triangles():
+            for i, j in combinations(point, 2):
+                self._cells[i].connect(self._cells[j])
+                self._cells[j].connect(self._cells[i])
+
+    def _validate_parameters(self) -> None:
+        if self.capacity is not None and not isinstance(self.capacity, float | int):
+            raise ValueError("Capacity must be a number or None.")
+        if not isinstance(self.centroids_coordinates, Sequence) or not isinstance(
+            self.centroids_coordinates[0], Sequence
+        ):
+            raise ValueError("Centroids should be a list of lists")
+        dimension_1 = len(self.centroids_coordinates[0])
+        for coordinate in self.centroids_coordinates:
+            if dimension_1 != len(coordinate):
+                raise ValueError("Centroid coordinates should be a homogeneous array")
+
+    def _get_voronoi_regions(self) -> tuple:
+        if self.voronoi_coordinates is None or self.regions is None:
+            self.voronoi_coordinates, self.regions = (
+                self.triangulation.export_voronoi_regions()
+            )
+        return self.voronoi_coordinates, self.regions
+
+    @staticmethod
+    def _compute_polygon_area(polygon: list) -> float:
+        polygon = np.array(polygon)
+        x = polygon[:, 0]
+        y = polygon[:, 1]
+        return 0.5 * np.abs(np.dot(x, np.roll(y, 1)) - np.dot(y, np.roll(x, 1)))
+
+    def _build_cell_polygons(self):
+        coordinates, regions = self._get_voronoi_regions()
+        for region in regions:
+            polygon = [coordinates[i] for i in regions[region]]
+            self._cells[region].properties["polygon"] = polygon
+            polygon_area = self._compute_polygon_area(polygon)
+            self._cells[region].properties["area"] = polygon_area
+            self._cells[region].capacity = self.capacity_function(polygon_area)
+            self._cells[region].properties[self.cell_coloring_property] = 0

mesa/model.py

@@ -8,9 +8,8 @@ Core Objects: Model
 # Remove this __future__ import once the oldest supported Python is 3.10
 from __future__ import annotations
 
-import itertools
 import random
-from collections import defaultdict
+import warnings
 
 # mypy
 from typing import Any
@@ -18,8 +17,6 @@ from typing import Any
 from mesa.agent import Agent, AgentSet
 from mesa.datacollection import DataCollector
 
-TimeT = float | int
-
 
 class Model:
     """Base class for models in the Mesa ABM library.
@@ -32,12 +29,12 @@ class Model:
         running: A boolean indicating if the model should continue running.
         schedule: An object to manage the order and execution of agent steps.
         current_id: A counter for assigning unique IDs to agents.
-        agents_: A defaultdict mapping each agent type to a dict of its instances.
-                 This private attribute is used internally to manage agents.
 
     Properties:
-        agents: An AgentSet containing all agents in the model, generated from the _agents attribute.
+        agents: An AgentSet containing all agents in the model
         agent_types: A list of different agent types present in the model.
+        steps: An integer representing the number of steps the model has taken.
+               It increases automatically at the start of each step() call.
 
     Methods:
         get_agents_of_type: Returns an AgentSet of agents of the specified type.
@@ -46,6 +43,14 @@ class Model:
         next_id: Generates and returns the next unique identifier for an agent.
         reset_randomizer: Resets the model's random number generator with a new or existing seed.
         initialize_data_collector: Sets up the data collector for the model, requiring an initialized scheduler and agents.
+        register_agent : register an agent with the model
+        deregister_agent : remove an agent from the model
+
+    Notes:
+        Model.agents returns the AgentSet containing all agents registered with the model. Changing
+        the content of the AgentSet directly can result in strange behavior. If you want change the
+        composition of this AgentSet, ensure you operate on a copy.
+
     """
 
     def __new__(cls, *args: Any, **kwargs: Any) -> Any:
@@ -57,9 +62,6 @@ class Model:
             # advance.
             obj._seed = random.random()
         obj.random = random.Random(obj._seed)
-        # TODO: Remove these 2 lines just before Mesa 3.0
-        obj._steps = 0
-        obj._time = 0
         return obj
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -71,39 +73,107 @@ class Model:
         self.running = True
         self.schedule = None
         self.current_id = 0
-        self.agents_: defaultdict[type, dict] = defaultdict(dict)
+        self.steps: int = 0
+
+        self._setup_agent_registration()
 
-        self._steps: int = 0
-        self._time: TimeT = 0  # the model's clock
+        # Wrap the user-defined step method
+        self._user_step = self.step
+        self.step = self._wrapped_step
+
+    def _wrapped_step(self, *args: Any, **kwargs: Any) -> None:
+        """Automatically increments time and steps after calling the user's step method."""
+        # Automatically increment time and step counters
+        self.steps += 1
+        # Call the original user-defined step method
+        self._user_step(*args, **kwargs)
 
     @property
     def agents(self) -> AgentSet:
         """Provides an AgentSet of all agents in the model, combining agents from all types."""
-
-        if hasattr(self, "_agents"):
-            return self._agents
-        else:
-            all_agents = itertools.chain.from_iterable(self.agents_.values())
-            return AgentSet(all_agents, self)
+        return self._all_agents
 
     @agents.setter
     def agents(self, agents: Any) -> None:
         raise AttributeError(
-            "You are trying to set model.agents. In Mesa 3.0 and higher, this attribute will be "
+            "You are trying to set model.agents. In Mesa 3.0 and higher, this attribute is "
             "used by Mesa itself, so you cannot use it directly anymore."
             "Please adjust your code to use a different attribute name for custom agent storage."
         )
 
-        self._agents = agents
-
     @property
     def agent_types(self) -> list[type]:
-        """Return a list of different agent types."""
-        return list(self.agents_.keys())
+        """Return a list of all unique agent types registered with the model."""
+        return list(self._agents_by_type.keys())
 
     def get_agents_of_type(self, agenttype: type[Agent]) -> AgentSet:
-        """Retrieves an AgentSet containing all agents of the specified type."""
-        return AgentSet(self.agents_[agenttype].keys(), self)
+        """Retrieves an AgentSet containing all agents of the specified type.
+
+        Args:
+            agenttype: The type of agent to retrieve.
+
+        Raises:
+            KeyError: If agenttype does not exist
+
+
+        """
+        return self._agents_by_type[agenttype]
+
+    def _setup_agent_registration(self):
+        """helper method to initialize the agent registration datastructures"""
+        self._agents = {}  # the hard references to all agents in the model
+        self._agents_by_type: dict[
+            type, AgentSet
+        ] = {}  # a dict with an agentset for each class of agents
+        self._all_agents = AgentSet([], self)  # an agenset with all agents
+
+    def register_agent(self, agent):
+        """Register the agent with the model
+
+        Args:
+            agent: The agent to register.
+
+        Notes:
+            This method is called automatically by ``Agent.__init__``, so there is no need to use this
+            if you are subclassing Agent and calling its super in the ``__init__`` method.
+
+        """
+        if not hasattr(self, "_agents"):
+            self._setup_agent_registration()
+
+            warnings.warn(
+                "The Mesa Model class was not initialized. In the future, you need to explicitly initialize "
+                "the Model by calling super().__init__() on initialization.",
+                FutureWarning,
+                stacklevel=2,
+            )
+
+        self._agents[agent] = None
+
+        # because AgentSet requires model, we cannot use defaultdict
+        # tricks with a function won't work because model then cannot be pickled
+        try:
+            self._agents_by_type[type(agent)].add(agent)
+        except KeyError:
+            self._agents_by_type[type(agent)] = AgentSet(
+                [
+                    agent,
+                ],
+                self,
+            )
+
+        self._all_agents.add(agent)
+
+    def deregister_agent(self, agent):
+        """Deregister the agent with the model
+
+        Notes::
+        This method is called automatically by ``Agent.remove``
+
+        """
+        del self._agents[agent]
+        self._agents_by_type[type(agent)].remove(agent)
+        self._all_agents.remove(agent)
 
     def run_model(self) -> None:
         """Run the model until the end condition is reached. Overload as
@@ -115,11 +185,6 @@ class Model:
     def step(self) -> None:
         """A single step. Fill in here."""
 
-    def _advance_time(self, deltat: TimeT = 1):
-        """Increment the model's steps counter and clock."""
-        self._steps += 1
-        self._time += deltat
-
     def next_id(self) -> int:
         """Return the next unique ID for agents, increment current_id"""
         self.current_id += 1

mesa/time.py

@@ -69,8 +69,6 @@ class BaseScheduler:
         self.model = model
         self.steps = 0
         self.time: TimeT = 0
-        self._original_step = self.step
-        self.step = self._wrapped_step
 
         if agents is None:
             agents = []
@@ -113,11 +111,6 @@ class BaseScheduler:
         self.steps += 1
         self.time += 1
 
-    def _wrapped_step(self):
-        """Wrapper for the step method to include time and step updating."""
-        self._original_step()
-        self.model._advance_time()
-
     def get_agent_count(self) -> int:
         """Returns the current number of agents in the queue."""
         return len(self._agents)

mesa/visualization/components/matplotlib.py

@@ -6,6 +6,7 @@ from matplotlib.figure import Figure
 from matplotlib.ticker import MaxNLocator
 
 import mesa
+from mesa.experimental.cell_space import VoronoiGrid
 
 
 @solara.component
@@ -20,6 +21,8 @@ def SpaceMatplotlib(model, agent_portrayal, dependencies: list[any] | None = Non
         _draw_network_grid(space, space_ax, agent_portrayal)
     elif isinstance(space, mesa.space.ContinuousSpace):
         _draw_continuous_space(space, space_ax, agent_portrayal)
+    elif isinstance(space, VoronoiGrid):
+        _draw_voronoi(space, space_ax, agent_portrayal)
     else:
         _draw_grid(space, space_ax, agent_portrayal)
     solara.FigureMatplotlib(space_fig, format="png", dependencies=dependencies)
@@ -150,6 +153,56 @@ def _draw_continuous_space(space, space_ax, agent_portrayal):
     _split_and_scatter(portray(space), space_ax)
 
 
+def _draw_voronoi(space, space_ax, agent_portrayal):
+    def portray(g):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+
+        for cell in g.all_cells:
+            for agent in cell.agents:
+                data = agent_portrayal(agent)
+                x.append(cell.coordinate[0])
+                y.append(cell.coordinate[1])
+                if "size" in data:
+                    s.append(data["size"])
+                if "color" in data:
+                    c.append(data["color"])
+        out = {"x": x, "y": y}
+        # This is the default value for the marker size, which auto-scales
+        # according to the grid area.
+        out["s"] = s
+        if len(c) > 0:
+            out["c"] = c
+
+        return out
+
+    x_list = [i[0] for i in space.centroids_coordinates]
+    y_list = [i[1] for i in space.centroids_coordinates]
+    x_max = max(x_list)
+    x_min = min(x_list)
+    y_max = max(y_list)
+    y_min = min(y_list)
+
+    width = x_max - x_min
+    x_padding = width / 20
+    height = y_max - y_min
+    y_padding = height / 20
+    space_ax.set_xlim(x_min - x_padding, x_max + x_padding)
+    space_ax.set_ylim(y_min - y_padding, y_max + y_padding)
+    space_ax.scatter(**portray(space))
+
+    for cell in space.all_cells:
+        polygon = cell.properties["polygon"]
+        space_ax.fill(
+            *zip(*polygon),
+            alpha=min(1, cell.properties[space.cell_coloring_property]),
+            c="red",
+        )  # Plot filled polygon
+        space_ax.plot(*zip(*polygon), color="black")  # Plot polygon edges in red
+
+
 @solara.component
 def PlotMatplotlib(model, measure, dependencies: list[any] | None = None):
     fig = Figure()

mesa/visualization/solara_viz.py

@@ -158,7 +158,11 @@ def SolaraViz(
         """Update the random seed for the model."""
         reactive_seed.value = model.random.random()
 
-    dependencies = [current_step.value, reactive_seed.value]
+    dependencies = [
+        *list(model_parameters.values()),
+        current_step.value,
+        reactive_seed.value,
+    ]
 
     # if space drawer is disabled, do not include it
     layout_types = [{"Space": "default"}] if space_drawer else []
@@ -240,7 +244,7 @@ def ModelController(model, play_interval, current_step, reset_counter):
         """Advance the model by one step."""
         model.step()
         previous_step.value = current_step.value
-        current_step.value = model._steps
+        current_step.value = model.steps
 
     def do_play():
         """Run the model continuously."""

{mesa-3.0.0a2.dist-info → mesa-3.0.0a3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Mesa
-Version: 3.0.0a2
+Version: 3.0.0a3
 Summary: Agent-based modeling (ABM) in Python
 Project-URL: homepage, https://github.com/projectmesa/mesa
 Project-URL: repository, https://github.com/projectmesa/mesa
@@ -42,6 +42,9 @@ Requires-Dist: myst-parser; extra == 'docs'
 Requires-Dist: pydata-sphinx-theme; extra == 'docs'
 Requires-Dist: seaborn; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: pytest>=4.6; extra == 'examples'
+Requires-Dist: scipy; extra == 'examples'
 Description-Content-Type: text/markdown
 
 # Mesa: Agent-based modeling in Python
@@ -98,15 +101,18 @@ Or any other (development) branch on this repo or your own fork:
 pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa
 ```
 
+## Resources
 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)
 -   [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
     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)
 -   [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-3.0.0a2.dist-info → mesa-3.0.0a3.dist-info}/RECORD

@@ -1,11 +1,11 @@
-mesa/__init__.py,sha256=MvmhX7S8OWq9FLM52bF7lnSUTTNZegQPsSheI37L2og,618
-mesa/agent.py,sha256=xqpjpMHii82nts-gO5DPpcUjujHQoaJB2fKi0VrrWHs,13067
-mesa/batchrunner.py,sha256=92MabDDR38XGTZw_IB7nNDNH0PX7zL_jGyZJ2grisaY,6023
-mesa/datacollection.py,sha256=CQ2QsW-mkEVbDVTsOkLy8NAQEKeoILdLB0zWS2sxnyk,11444
+mesa/__init__.py,sha256=fHbxauJqwzvD_Y--JHDC7qj52vdMSltmq1EdOf8963E,618
+mesa/agent.py,sha256=0V10JPHfgKmwduPi8eX6CrtJ2ergcT6Lw8uSLn-IcY8,19647
+mesa/batchrunner.py,sha256=iwsfitWFo-m7dm2hNFB8xFOlnXa43URypbxF-zebnws,6019
+mesa/datacollection.py,sha256=WUpZoFC2ZdLtKZ0oTwZTqraoP_yNx_yQY9pxO0TR8y0,11442
 mesa/main.py,sha256=7MovfNz88VWNnfXP0kcERB6C3GfkVOh0hb0o32hM9LU,1602
-mesa/model.py,sha256=Jqj6ob-zuTwAWwYAkbEsoC-bTA7ptoAD9qDvPfIX-80,5761
+mesa/model.py,sha256=kyWzDnnV_RI4Kef_p70Zz5ikxlFD7NeJl1OaS9hjh2w,8049
 mesa/space.py,sha256=zC96qoNjhLmBXY2ZaEQmF7w30WZAtPpEY4mwcet-Dio,62462
-mesa/time.py,sha256=9gNoyUqYkt_gUPFBMhm38pK87mcntwAZ1lJzxqW3BSA,15211
+mesa/time.py,sha256=53VX0x8zujaq32R6w_aBv1NmLpWO_h5K5BQTaK4mO3Q,14960
 mesa/cookiecutter-mesa/cookiecutter.json,sha256=tBSWli39fOWUXGfiDCTKd92M7uKaBIswXbkOdbUufYY,337
 mesa/cookiecutter-mesa/hooks/post_gen_project.py,sha256=8JoXZKIioRYEWJURC0udj8WS3rg0c4So62sOZSGbrMY,294
 mesa/cookiecutter-mesa/{{cookiecutter.snake}}/README.md,sha256=Yji4lGY-NtQSnW-oBj0_Jhs-XhCfZA8R1mBBM_IllGs,80
@@ -14,13 +14,14 @@ mesa/cookiecutter-mesa/{{cookiecutter.snake}}/setup.pytemplate,sha256=UtRpLM_Cke
 mesa/cookiecutter-mesa/{{cookiecutter.snake}}/{{cookiecutter.snake}}/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mesa/cookiecutter-mesa/{{cookiecutter.snake}}/{{cookiecutter.snake}}/model.pytemplate,sha256=Aml4Z6E1yj7E7DtHNSUqnKNRUdkxG9WWtJyW8fkxCng,1870
 mesa/experimental/__init__.py,sha256=MaSRE9cTFIWwMZsbRKfnCiCBkhvtzJdgWlg3Dls7Unw,67
-mesa/experimental/cell_space/__init__.py,sha256=trFVKf2l5RbkCUyxP09Kox_J3ak2YdM4o3t40Tsjjm4,628
+mesa/experimental/cell_space/__init__.py,sha256=gXntv_Ie13SIegBumJNaIPcTUmTQLb4LlGd1JxoIn9M,708
 mesa/experimental/cell_space/cell.py,sha256=AUnvVnXWhdgzr0bLKDRDO9c93v22Zkw6W-tWxhEhGdQ,4578
 mesa/experimental/cell_space/cell_agent.py,sha256=G4u9ht4gW9ns1y2L7pFumF3K4HiP6ROuxwrxHZ-mL1M,1107
 mesa/experimental/cell_space/cell_collection.py,sha256=4FmfDEg9LoFiJ0mF_nC8KUt9fCJ7Q21erjWPeBTQ_lw,2293
 mesa/experimental/cell_space/discrete_space.py,sha256=ta__YojsrrhWL4DgMzUqZpSgbeexKMrA6bxlYPJGfK0,1921
 mesa/experimental/cell_space/grid.py,sha256=gYDExuFBMF3OThUkhbXmolQFKBOqTukcibjfgXicP00,6948
 mesa/experimental/cell_space/network.py,sha256=mAaFHBdd4s9kxUWHbViovLW2-pU2yXH0dtY_vF8sCJg,1179
+mesa/experimental/cell_space/voronoi.py,sha256=swwfV1Hfi7wp3XfM-rb9Lq5H0yAPH9zohZnXzU8SiHM,9997
 mesa/experimental/devs/__init__.py,sha256=CWam15vCj-RD_biMyqv4sJfos1fsL823P7MDEGrbwW8,174
 mesa/experimental/devs/eventlist.py,sha256=nyUFNDWnnSPQnrMtj7Qj1PexxKyOwSJuIGBoxtSwVI0,5269
 mesa/experimental/devs/simulator.py,sha256=0SMC7daIOyL2rYfoQOOTaTOYDos0gLeBUbU1Krd42HA,9557
@@ -28,11 +29,11 @@ mesa/experimental/devs/examples/epstein_civil_violence.py,sha256=KqH9KI-A_BYt7oW
 mesa/experimental/devs/examples/wolf_sheep.py,sha256=h5z-eDqMpYeOjrq293N2BcQbs_LDVsgtg9vblXJM7XQ,7697
 mesa/visualization/UserParam.py,sha256=WgnY3Q0padtGqUCaezgYzd6cZ7LziuIQnGKP3DBuHZY,1641
 mesa/visualization/__init__.py,sha256=zsAzEY3-0O9CZUfiUL6p8zCR1mvvL5Sai2WzoiQ2pmY,127
-mesa/visualization/solara_viz.py,sha256=GuhDFcsHp6rSjaYMM7lgB-sWJGfEqJrYnmMxncnZF8A,15192
+mesa/visualization/solara_viz.py,sha256=hT-w4N32x5HUkk7AVYN6Ps_5JWrcaQWiyIo5ZyvYoJA,15256
 mesa/visualization/components/altair.py,sha256=V2CQ-Zr7PeijgWtYBNH3VklGVfrf1ee70XVh0DBBONQ,2366
-mesa/visualization/components/matplotlib.py,sha256=gUTteu_VEA4J2je760aq_esYto0Uj1DZP9gjev8TlcU,5851
-mesa-3.0.0a2.dist-info/METADATA,sha256=zAMPJhtCHtWiXvm6dl5iCqU048qhtZpBkGsKO6RtaEM,7862
-mesa-3.0.0a2.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-mesa-3.0.0a2.dist-info/entry_points.txt,sha256=IOcQtetGF8l4wHpOs_hGb19Rz-FS__BMXOJR10IBPsA,39
-mesa-3.0.0a2.dist-info/licenses/LICENSE,sha256=OGUgret9fRrm8J3pdsPXETIjf0H8puK_Nmy970ZzT78,572
-mesa-3.0.0a2.dist-info/RECORD,,
+mesa/visualization/components/matplotlib.py,sha256=J61gHkXd37XyZiNLGF1NaQPOYqDdh9tpSfbOzMqK3dI,7570
+mesa-3.0.0a3.dist-info/METADATA,sha256=r4qETS44Ho4RD37R5yxmUDeTE0LZXfQHrAmT2hRNioI,8288
+mesa-3.0.0a3.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+mesa-3.0.0a3.dist-info/entry_points.txt,sha256=IOcQtetGF8l4wHpOs_hGb19Rz-FS__BMXOJR10IBPsA,39
+mesa-3.0.0a3.dist-info/licenses/LICENSE,sha256=OGUgret9fRrm8J3pdsPXETIjf0H8puK_Nmy970ZzT78,572
+mesa-3.0.0a3.dist-info/RECORD,,