Mesa 3.0.0b0__py3-none-any.whl → 3.0.0b2__py3-none-any.whl

mesa/experimental/cell_space/discrete_space.py

@@ -7,6 +7,7 @@ from functools import cached_property
 from random import Random
 from typing import Any, Generic, TypeVar
 
+from mesa.agent import AgentSet
 from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.cell_collection import CellCollection
 from mesa.space import PropertyLayer
@@ -22,7 +23,7 @@ class DiscreteSpace(Generic[T]):
         all_cells (CellCollection): The cells composing the discrete space
         random (Random): The random number generator
         cell_klass (Type) : the type of cell class
-        empties (CellCollection) : collecction of all cells that are empty
+        empties (CellCollection) : collection of all cells that are empty
         property_layers (dict[str, PropertyLayer]): the property layers of the discrete space
     """
 
@@ -55,6 +56,12 @@ class DiscreteSpace(Generic[T]):
     def cutoff_empties(self):  # noqa
         return 7.953 * len(self._cells) ** 0.384
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        return AgentSet(self.all_cells.agents, random=self.random)
+
+    def _connect_cells(self): ...
     def _connect_single_cell(self, cell: T): ...
 
     @cached_property
@@ -134,3 +141,8 @@ class DiscreteSpace(Generic[T]):
             condition: a function that takes a cell and returns a boolean (used to filter cells)
         """
         self.property_layers[property_name].modify_cells(operation, value, condition)
+
+    def __setstate__(self, state):
+        """Set the state of the discrete space and rebuild the connections."""
+        self.__dict__ = state
+        self._connect_cells()

mesa/experimental/cell_space/grid.py

@@ -22,8 +22,21 @@ class Grid(DiscreteSpace[T], Generic[T]):
         random (Random): the random number generator
         _try_random (bool): whether to get empty cell be repeatedly trying random cell
 
+    Notes:
+        width and height are accessible via properties, higher dimensions can be retrieved via dimensions
+
     """
 
+    @property
+    def width(self) -> int:
+        """Convenience access to the width of the grid."""
+        return self.dimensions[0]
+
+    @property
+    def height(self) -> int:
+        """Convenience access to the height of the grid."""
+        return self.dimensions[1]
+
     def __init__(
         self,
         dimensions: Sequence[int],

mesa/experimental/cell_space/network.py

@@ -34,6 +34,9 @@ class Network(DiscreteSpace[Cell]):
                 node_id, capacity, random=self.random
             )
 
+        self._connect_cells()
+
+    def _connect_cells(self) -> None:
         for cell in self.all_cells:
             self._connect_single_cell(cell)
 

mesa/experimental/devs/eventlist.py

@@ -33,6 +33,12 @@ class SimulationEvent:
         function_args (list[Any]): Argument for the function
         function_kwargs (Dict[str, Any]): Keyword arguments for the function
 
+
+    Notes:
+        simulation events use a weak reference to the callable. Therefore, you cannot pass a lambda function in fn.
+        A simulation event where the callable no longer exists (e.g., because the agent has been removed from the model)
+        will fail silently.
+
     """
 
     _ids = itertools.count()

mesa/model.py

@@ -8,14 +8,21 @@ Core Objects: Model
 from __future__ import annotations
 
 import random
+import sys
 import warnings
+from collections.abc import Sequence
 
 # mypy
 from typing import Any
 
+import numpy as np
+
 from mesa.agent import Agent, AgentSet
 from mesa.datacollection import DataCollector
 
+SeedLike = int | np.integer | Sequence[int] | np.random.SeedSequence
+RNGLike = np.random.Generator | np.random.BitGenerator
+
 
 class Model:
     """Base class for models in the Mesa ABM library.
@@ -28,7 +35,8 @@ class Model:
         running: A boolean indicating if the model should continue running.
         schedule: An object to manage the order and execution of agent steps.
         steps: the number of times `model.step()` has been called.
-        random: a seeded random number generator.
+        random: a seeded python.random number generator.
+        rng : a seeded numpy.random.Generator
 
     Notes:
         Model.agents returns the AgentSet containing all agents registered with the model. Changing
@@ -37,7 +45,13 @@ class Model:
 
     """
 
-    def __init__(self, *args: Any, seed: float | None = None, **kwargs: Any) -> None:
+    def __init__(
+        self,
+        *args: Any,
+        seed: float | None = None,
+        rng: RNGLike | SeedLike | None = None,
+        **kwargs: Any,
+    ) -> None:
         """Create a new model.
 
         Overload this method with the actual code to initialize the model. Always start with super().__init__()
@@ -46,25 +60,51 @@ class Model:
         Args:
             args: arguments to pass onto super
             seed: the seed for the random number generator
+            rng : Pseudorandom number generator state. When `rng` is None, a new `numpy.random.Generator` is created
+                  using entropy from the operating system. Types other than `numpy.random.Generator` are passed to
+                  `numpy.random.default_rng` to instantiate a `Generator`.
             kwargs: keyword arguments to pass onto super
+
+        Notes:
+            you have to pass either seed or rng, but not both.
+
         """
         super().__init__(*args, **kwargs)
         self.running = True
         self.steps: int = 0
 
-        self._setup_agent_registration()
-
-        self._seed = seed
-        if self._seed is None:
-            # We explicitly specify the seed here so that we know its value in
-            # advance.
-            self._seed = random.random()
-        self.random = random.Random(self._seed)
+        if (seed is not None) and (rng is not None):
+            raise ValueError("you have to pass either rng or seed, not both")
+        elif seed is None:
+            self.rng: np.random.Generator = np.random.default_rng(rng)
+            self._rng = (
+                self.rng.bit_generator.state
+            )  # this allows for reproducing the rng
+
+            try:
+                self.random = random.Random(rng)
+            except TypeError:
+                seed = int(self.rng.integers(np.iinfo(np.int32).max))
+                self.random = random.Random(seed)
+            self._seed = seed  # this allows for reproducing stdlib.random
+        elif rng is None:
+            self.random = random.Random(seed)
+            self._seed = seed  # this allows for reproducing stdlib.random
+
+            try:
+                self.rng: np.random.Generator = np.random.default_rng(rng)
+            except TypeError:
+                rng = self.random.randint(0, sys.maxsize)
+                self.rng: np.random.Generator = np.random.default_rng(rng)
+            self._rng = self.rng.bit_generator.state
 
         # Wrap the user-defined step method
         self._user_step = self.step
         self.step = self._wrapped_step
 
+        # setup agent registration data structures
+        self._setup_agent_registration()
+
     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
@@ -119,7 +159,9 @@ class Model:
         self._agents_by_type: dict[
             type[Agent], AgentSet
         ] = {}  # a dict with an agentset for each class of agents
-        self._all_agents = AgentSet([], self)  # an agenset with all agents
+        self._all_agents = AgentSet(
+            [], random=self.random
+        )  # an agenset with all agents
 
     def register_agent(self, agent):
         """Register the agent with the model.
@@ -153,7 +195,7 @@ class Model:
                 [
                     agent,
                 ],
-                self,
+                random=self.random,
             )
 
         self._all_agents.add(agent)
@@ -194,6 +236,15 @@ class Model:
         self.random.seed(seed)
         self._seed = seed
 
+    def reset_rng(self, rng: RNGLike | SeedLike | None = None) -> None:
+        """Reset the model random number generator.
+
+        Args:
+            rng: A new seed for the RNG; if None, reset using the current seed
+        """
+        self.rng = np.random.default_rng(rng)
+        self._rng = self.rng.bit_generator.state
+
     def initialize_data_collector(
         self,
         model_reporters=None,
@@ -225,3 +276,16 @@ class Model:
         )
         # Collect data for the first time during initialization.
         self.datacollector.collect(self)
+
+    def remove_all_agents(self):
+        """Remove all agents from the model.
+
+        Notes:
+            This method calls agent.remove for all agents in the model. If you need to remove agents from
+            e.g., a SingleGrid, you can either explicitly implement your own agent.remove method or clean this up
+            near where you are calling this method.
+
+        """
+        # we need to wrap keys in a list to avoid a RunTimeError: dictionary changed size during iteration
+        for agent in list(self._agents.keys()):
+            agent.remove()

mesa/space.py

@@ -2,10 +2,21 @@
 
 Objects used to add a spatial component to a model.
 
-* Grid: base grid, which creates a rectangular grid.
-* SingleGrid: extension to Grid which strictly enforces one agent per cell.
-* MultiGrid: extension to Grid where each cell can contain a set of agents.
-* HexGrid: extension to Grid to handle hexagonal neighbors.
+.. note::
+    All Grid classes (:class:`_Grid`, :class:`SingleGrid`, :class:`MultiGrid`,
+    :class:`HexGrid`, etc.) are now in maintenance-only mode. While these classes remain
+    fully supported, new development occurs in the experimental cell space module
+    (:mod:`mesa.experimental.cell_space`).
+
+    The :class:`PropertyLayer` and :class:`ContinuousSpace` classes remain fully supported
+    and actively developed.
+
+Classes
+-------
+* PropertyLayer: A data layer that can be added to Grids to store cell properties
+* SingleGrid: a Grid which strictly enforces one agent per cell.
+* MultiGrid: a Grid where each cell can contain a set of agents.
+* HexGrid: a Grid to handle hexagonal neighbors.
 * ContinuousSpace: a two-dimensional space where each agent has an arbitrary position of `float`'s.
 * NetworkGrid: a network where each node contains zero or more agents.
 """
@@ -32,7 +43,7 @@ import numpy as np
 import numpy.typing as npt
 
 # For Mypy
-from .agent import Agent
+from .agent import Agent, AgentSet
 
 # for better performance, we calculate the tuple to use in the is_integer function
 _types_integer = (int, np.integer)
@@ -153,6 +164,26 @@ class _Grid:
     @overload
     def __getitem__(self, index: int | Sequence[Coordinate]) -> list[GridContent]: ...
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for entry in self:
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]  # noqa PLW2901
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @overload
     def __getitem__(
         self, index: tuple[int | slice, int | slice]
@@ -1333,6 +1364,19 @@ class ContinuousSpace:
         self._index_to_agent: dict[int, Agent] = {}
         self._agent_to_index: dict[Agent, int | None] = {}
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = list(self._agent_to_index)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     def _build_agent_cache(self):
         """Cache agents positions to speed up neighbors calculations."""
         self._index_to_agent = {}
@@ -1506,6 +1550,27 @@ class NetworkGrid:
         for node_id in self.G.nodes:
             g.nodes[node_id]["agent"] = self.default_val()
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for node_id in self.G.nodes:
+            entry = self.G.nodes[node_id]["agent"]
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @staticmethod
     def default_val() -> list:
         """Default value for a new node."""

mesa/time.py

@@ -77,7 +77,7 @@ class BaseScheduler:
         if agents is None:
             agents = []
 
-        self._agents: AgentSet = AgentSet(agents, model)
+        self._agents: AgentSet = AgentSet(agents, model.random)
 
         self._remove_warning_given = False
         self._agents_key_warning_given = False
@@ -312,7 +312,9 @@ class RandomActivationByType(BaseScheduler):
                 try:
                     self._agents_by_type[type(agent)].add(agent)
                 except KeyError:
-                    self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
+                    self._agents_by_type[type(agent)] = AgentSet(
+                        [agent], self.model.random
+                    )
 
     def add(self, agent: Agent) -> None:
         """Add an Agent object to the schedule.
@@ -325,7 +327,7 @@ class RandomActivationByType(BaseScheduler):
         try:
             self._agents_by_type[type(agent)].add(agent)
         except KeyError:
-            self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
+            self._agents_by_type[type(agent)] = AgentSet([agent], self.model.random)
 
     def remove(self, agent: Agent) -> None:
         """Remove all instances of a given agent from the schedule.

mesa/visualization/components/altair.py

@@ -7,6 +7,8 @@ import solara
 with contextlib.suppress(ImportError):
     import altair as alt
 
+from mesa.experimental.cell_space import DiscreteSpace, Grid
+from mesa.space import ContinuousSpace, _Grid
 from mesa.visualization.utils import update_counter
 
 
@@ -29,35 +31,101 @@ def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
     if space is None:
         # Sometimes the space is defined as model.space instead of model.grid
         space = model.space
+
     chart = _draw_grid(space, agent_portrayal)
     solara.FigureAltair(chart)
 
 
+def _get_agent_data_old__discrete_space(space, agent_portrayal):
+    """Format agent portrayal data for old-style discrete spaces.
+
+    Args:
+        space: the mesa.space._Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+    for content, (x, y) in space.coord_iter():
+        if not content:
+            continue
+        if not hasattr(content, "__iter__"):
+            # Is a single grid
+            content = [content]  # noqa: PLW2901
+        for agent in content:
+            # use all data from agent portrayal, and add x,y coordinates
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = x
+            agent_data["y"] = y
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_new_discrete_space(space: DiscreteSpace, agent_portrayal):
+    """Format agent portrayal data for new-style discrete spaces.
+
+    Args:
+        space: the mesa.experiment.cell_space.Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+
+    for cell in space.all_cells:
+        for agent in cell.agents:
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = cell.coordinate[0]
+            agent_data["y"] = cell.coordinate[1]
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_continuous_space(space: ContinuousSpace, agent_portrayal):
+    """Format agent portrayal data for continuous space.
+
+    Args:
+        space: the ContinuousSpace instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+    """
+    all_agent_data = []
+    for agent in space._agent_to_index:
+        agent_data = agent_portrayal(agent)
+        agent_data["x"] = agent.pos[0]
+        agent_data["y"] = agent.pos[1]
+        all_agent_data.append(agent_data)
+    return all_agent_data
+
+
 def _draw_grid(space, agent_portrayal):
-    def portray(g):
-        all_agent_data = []
-        for content, (x, y) in g.coord_iter():
-            if not content:
-                continue
-            if not hasattr(content, "__iter__"):
-                # Is a single grid
-                content = [content]  # noqa: PLW2901
-            for agent in content:
-                # use all data from agent portrayal, and add x,y coordinates
-                agent_data = agent_portrayal(agent)
-                agent_data["x"] = x
-                agent_data["y"] = y
-                all_agent_data.append(agent_data)
-        return all_agent_data
-
-    all_agent_data = portray(space)
+    match space:
+        case Grid():
+            all_agent_data = _get_agent_data_new_discrete_space(space, agent_portrayal)
+        case _Grid():
+            all_agent_data = _get_agent_data_old__discrete_space(space, agent_portrayal)
+        case ContinuousSpace():
+            all_agent_data = _get_agent_data_continuous_space(space, agent_portrayal)
+        case _:
+            raise NotImplementedError(
+                f"visualizing {type(space)} is currently not supported through altair"
+            )
+
     invalid_tooltips = ["color", "size", "x", "y"]
 
+    x_y_type = "ordinal" if not isinstance(space, ContinuousSpace) else "nominal"
+
     encoding_dict = {
         # no x-axis label
-        "x": alt.X("x", axis=None, type="ordinal"),
+        "x": alt.X("x", axis=None, type=x_y_type),
         # no y-axis label
-        "y": alt.Y("y", axis=None, type="ordinal"),
+        "y": alt.Y("y", axis=None, type=x_y_type),
         "tooltip": [
             alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
             for key, value in all_agent_data[0].items()

mesa/visualization/components/matplotlib.py

@@ -11,7 +11,7 @@ from matplotlib.colors import LinearSegmentedColormap, Normalize, to_rgba
 from matplotlib.figure import Figure
 
 import mesa
-from mesa.experimental.cell_space import VoronoiGrid
+from mesa.experimental.cell_space import Grid, VoronoiGrid
 from mesa.space import PropertyLayer
 from mesa.visualization.utils import update_counter
 
@@ -52,18 +52,26 @@ def SpaceMatplotlib(
     if space is None:
         space = getattr(model, "space", None)
 
-    if isinstance(space, mesa.space._Grid):
-        _draw_grid(space, space_ax, agent_portrayal, propertylayer_portrayal, model)
-    elif isinstance(space, mesa.space.ContinuousSpace):
-        _draw_continuous_space(space, space_ax, agent_portrayal, model)
-    elif isinstance(space, mesa.space.NetworkGrid):
-        _draw_network_grid(space, space_ax, agent_portrayal)
-    elif isinstance(space, VoronoiGrid):
-        _draw_voronoi(space, space_ax, agent_portrayal)
-    elif space is None and propertylayer_portrayal:
-        draw_property_layers(space_ax, space, propertylayer_portrayal, model)
-
-    solara.FigureMatplotlib(space_fig, format="png", dependencies=dependencies)
+    # https://stackoverflow.com/questions/67524641/convert-multiple-isinstance-checks-to-structural-pattern-matching
+    match space:
+        case mesa.space._Grid():
+            _draw_grid(space, space_ax, agent_portrayal, propertylayer_portrayal, model)
+        case mesa.space.ContinuousSpace():
+            _draw_continuous_space(space, space_ax, agent_portrayal, model)
+        case mesa.space.NetworkGrid():
+            _draw_network_grid(space, space_ax, agent_portrayal)
+        case VoronoiGrid():
+            _draw_voronoi(space, space_ax, agent_portrayal)
+        case Grid():  # matches OrthogonalMooreGrid, OrthogonalVonNeumannGrid, and Hexgrid
+            # fixme add a separate draw method for hexgrids in the future
+            _draw_discrete_space_grid(space, space_ax, agent_portrayal)
+        case None:
+            if propertylayer_portrayal:
+                draw_property_layers(space_ax, space, propertylayer_portrayal, model)
+
+    solara.FigureMatplotlib(
+        space_fig, format="png", bbox_inches="tight", dependencies=dependencies
+    )
 
 
 def draw_property_layers(ax, space, propertylayer_portrayal, model):
@@ -289,6 +297,44 @@ def _draw_voronoi(space, space_ax, agent_portrayal):
         space_ax.plot(*zip(*polygon), color="black")  # Plot polygon edges in black
 
 
+def _draw_discrete_space_grid(space: Grid, space_ax, agent_portrayal):
+    if space._ndims != 2:
+        raise ValueError("Space must be 2D")
+
+    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}
+        out["s"] = s
+        if len(c) > 0:
+            out["c"] = c
+
+        return out
+
+    space_ax.set_xlim(0, space.width)
+    space_ax.set_ylim(0, space.height)
+
+    # Draw grid lines
+    for x in range(space.width + 1):
+        space_ax.axvline(x, color="gray", linestyle=":")
+    for y in range(space.height + 1):
+        space_ax.axhline(y, color="gray", linestyle=":")
+
+    space_ax.scatter(**portray(space))
+
+
 def make_plot_measure(measure: str | dict[str, str] | list[str] | tuple[str]):
     """Create a plotting function for a specified measure.
 
@@ -327,11 +373,14 @@ def PlotMatplotlib(model, measure, dependencies: list[any] | None = None):
     elif isinstance(measure, dict):
         for m, color in measure.items():
             ax.plot(df.loc[:, m], label=m, color=color)
-        fig.legend()
+        ax.legend(loc="best")
     elif isinstance(measure, list | tuple):
         for m in measure:
             ax.plot(df.loc[:, m], label=m)
-        fig.legend()
+        ax.legend(loc="best")
+    ax.set_xlabel("Step")
     # Set integer x axis
     ax.xaxis.set_major_locator(plt.MaxNLocator(integer=True))
-    solara.FigureMatplotlib(fig, dependencies=dependencies)
+    solara.FigureMatplotlib(
+        fig, format="png", bbox_inches="tight", dependencies=dependencies
+    )