Mesa 3.0.0a5__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

mesa/experimental/cell_space/cell_agent.py

@@ -2,41 +2,132 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
 
-from mesa import Agent, Model
+from mesa.agent import Agent
 
 if TYPE_CHECKING:
-    from mesa.experimental.cell_space.cell import Cell
+    from mesa.experimental.cell_space import Cell
 
 
-class CellAgent(Agent):
-    """Cell Agent is an extension of the Agent class and adds behavior for moving in discrete spaces.
+class HasCellProtocol(Protocol):
+    """Protocol for discrete space cell holders."""
 
-    Attributes:
-        unique_id (int): A unique identifier for this agent.
-        model (Model): The model instance to which the agent belongs
-        pos: (Position | None): The position of the agent in the space
-        cell: (Cell | None): the cell which the agent occupies
-    """
+    cell: Cell
 
-    def __init__(self, model: Model) -> None:
-        """Create a new agent.
 
-        Args:
-            model (Model): The model instance in which the agent exists.
-        """
-        super().__init__(model)
-        self.cell: Cell | None = None
+class HasCell:
+    """Descriptor for cell movement behavior."""
 
-    def move_to(self, cell) -> None:
-        """Move agent to cell.
+    _mesa_cell: Cell | None = None
 
-        Args:
-            cell: cell to which agent is to move
+    @property
+    def cell(self) -> Cell | None:  # noqa: D102
+        return self._mesa_cell
 
-        """
+    @cell.setter
+    def cell(self, cell: Cell | None) -> None:
+        # remove from current cell
         if self.cell is not None:
             self.cell.remove_agent(self)
+
+        # update private attribute
+        self._mesa_cell = cell
+
+        # add to new cell
+        if cell is not None:
+            cell.add_agent(self)
+
+
+class BasicMovement:
+    """Mixin for moving agents in discrete space."""
+
+    def move_to(self: HasCellProtocol, cell: Cell) -> None:
+        """Move to a new cell."""
         self.cell = cell
+
+    def move_relative(self: HasCellProtocol, direction: tuple[int, ...]):
+        """Move to a cell relative to the current cell.
+
+        Args:
+            direction: The direction to move in.
+        """
+        new_cell = self.cell.connections.get(direction)
+        if new_cell is not None:
+            self.cell = new_cell
+        else:
+            raise ValueError(f"No cell in direction {direction}")
+
+
+class FixedCell(HasCell):
+    """Mixin for agents that are fixed to a cell."""
+
+    @property
+    def cell(self) -> Cell | None:  # noqa: D102
+        return self._mesa_cell
+
+    @cell.setter
+    def cell(self, cell: Cell) -> None:
+        if self.cell is not None:
+            raise ValueError("Cannot move agent in FixedCell")
+        self._mesa_cell = cell
+
         cell.add_agent(self)
+
+
+class CellAgent(Agent, HasCell, BasicMovement):
+    """Cell Agent is an extension of the Agent class and adds behavior for moving in discrete spaces.
+
+    Attributes:
+        cell (Cell): The cell the agent is currently in.
+    """
+
+    def remove(self):
+        """Remove the agent from the model."""
+        super().remove()
+        self.cell = None  # ensures that we are also removed from cell
+
+
+class FixedAgent(Agent, FixedCell):
+    """A patch in a 2D grid."""
+
+    def remove(self):
+        """Remove the agent from the model."""
+        super().remove()
+
+        # fixme we leave self._mesa_cell on the original value
+        #  so you cannot hijack remove() to move patches
+        self.cell.remove_agent(self)
+
+
+class Grid2DMovingAgent(CellAgent):
+    """Mixin for moving agents in 2D grids."""
+
+    # fmt: off
+    DIRECTION_MAP = {
+        "n": (-1, 0), "north": (-1, 0), "up": (-1, 0),
+        "s": (1, 0), "south": (1, 0), "down": (1, 0),
+        "e": (0, 1), "east": (0, 1), "right": (0, 1),
+        "w": (0, -1), "west": (0, -1), "left": (0, -1),
+        "ne": (-1, 1), "northeast": (-1, 1), "upright": (-1, 1),
+        "nw": (-1, -1), "northwest": (-1, -1), "upleft": (-1, -1),
+        "se": (1, 1), "southeast": (1, 1), "downright": (1, 1),
+        "sw": (1, -1), "southwest": (1, -1), "downleft": (1, -1)
+    }
+    # fmt: on
+
+    def move(self, direction: str, distance: int = 1):
+        """Move the agent in a cardinal direction.
+
+        Args:
+            direction: The cardinal direction to move in.
+            distance: The distance to move.
+        """
+        direction = direction.lower()  # Convert direction to lowercase
+
+        if direction not in self.DIRECTION_MAP:
+            raise ValueError(f"Invalid direction: {direction}")
+
+        move_vector = self.DIRECTION_MAP[direction]
+        for _ in range(distance):
+            self.move_relative(move_vector)

mesa/experimental/cell_space/discrete_space.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from functools import cached_property
 from random import Random
-from typing import Generic, TypeVar
+from typing import Any, Generic, TypeVar
 
 from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.cell_collection import CellCollection
+from mesa.space import PropertyLayer
 
 T = TypeVar("T", bound=Cell)
 
@@ -20,8 +22,8 @@ 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
     """
 
     def __init__(
@@ -47,11 +49,13 @@ class DiscreteSpace(Generic[T]):
 
         self._empties: dict[tuple[int, ...], None] = {}
         self._empties_initialized = False
+        self.property_layers: dict[str, PropertyLayer] = {}
 
     @property
     def cutoff_empties(self):  # noqa
         return 7.953 * len(self._cells) ** 0.384
 
+    def _connect_cells(self): ...
     def _connect_single_cell(self, cell: T): ...
 
     @cached_property
@@ -73,3 +77,66 @@ class DiscreteSpace(Generic[T]):
     def select_random_empty_cell(self) -> T:
         """Select random empty cell."""
         return self.random.choice(list(self.empties))
+
+    # PropertyLayer methods
+    def add_property_layer(
+        self, property_layer: PropertyLayer, add_to_cells: bool = True
+    ):
+        """Add a property layer to the grid.
+
+        Args:
+            property_layer: the property layer to add
+            add_to_cells: whether to add the property layer to all cells (default: True)
+        """
+        if property_layer.name in self.property_layers:
+            raise ValueError(f"Property layer {property_layer.name} already exists.")
+        self.property_layers[property_layer.name] = property_layer
+        if add_to_cells:
+            for cell in self._cells.values():
+                cell._mesa_property_layers[property_layer.name] = property_layer
+
+    def remove_property_layer(self, property_name: str, remove_from_cells: bool = True):
+        """Remove a property layer from the grid.
+
+        Args:
+            property_name: the name of the property layer to remove
+            remove_from_cells: whether to remove the property layer from all cells (default: True)
+        """
+        del self.property_layers[property_name]
+        if remove_from_cells:
+            for cell in self._cells.values():
+                del cell._mesa_property_layers[property_name]
+
+    def set_property(
+        self, property_name: str, value, condition: Callable[[T], bool] | None = None
+    ):
+        """Set the value of a property for all cells in the grid.
+
+        Args:
+            property_name: the name of the property to set
+            value: the value to set
+            condition: a function that takes a cell and returns a boolean
+        """
+        self.property_layers[property_name].set_cells(value, condition)
+
+    def modify_properties(
+        self,
+        property_name: str,
+        operation: Callable,
+        value: Any = None,
+        condition: Callable[[T], bool] | None = None,
+    ):
+        """Modify the values of a specific property for all cells in the grid.
+
+        Args:
+            property_name: the name of the property to modify
+            operation: the operation to perform
+            value: the value to use in the operation
+            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/examples/wolf_sheep.py

@@ -1,6 +1,7 @@
 """Example of using ABM simulator for Wolf-Sheep Predation Model."""
 
 import mesa
+from mesa.experimental.cell_space import FixedAgent
 from mesa.experimental.devs.simulator import ABMSimulator
 
 
@@ -90,7 +91,7 @@ class Wolf(Animal):
             sheep_to_eat.die()
 
 
-class GrassPatch(mesa.Agent):
+class GrassPatch(FixedAgent):
     """A patch of grass that grows at a fixed rate and it is eaten by sheep."""
 
     @property

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.schedule = None
         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,
@@ -210,14 +261,13 @@ class Model:
             tables: tables to collect
 
         """
-        if not hasattr(self, "schedule") or self.schedule is None:
-            raise RuntimeError(
-                "You must initialize the scheduler (self.schedule) before initializing the data collector."
-            )
-        if self.schedule.get_agent_count() == 0:
-            raise RuntimeError(
-                "You must add agents to the scheduler before initializing the data collector."
-            )
+        warnings.warn(
+            "initialize_data_collector() is deprecated. Please use the DataCollector class directly. "
+            "by using `self.datacollector = DataCollector(...)`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         self.datacollector = DataCollector(
             model_reporters=model_reporters,
             agent_reporters=agent_reporters,

mesa/time.py

@@ -3,7 +3,7 @@
 .. warning::
     The time module and all its Schedulers are deprecated and will be removed in a future version.
     They can be replaced with AgentSet functionality. See the migration guide for details:
-    https://mesa.readthedocs.io/en/latest/migration_guide.html#time-and-schedulers
+    https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers
 
 Objects for handling the time component of a model. In particular, this module
 contains Schedulers, which handle agent activation. A Scheduler is an object
@@ -65,7 +65,7 @@ class BaseScheduler:
         warnings.warn(
             "The time module and all its Schedulers are deprecated and will be removed in a future version. "
             "They can be replaced with AgentSet functionality. See the migration guide for details. "
-            "https://mesa.readthedocs.io/en/latest/migration_guide.html#time-and-schedulers",
+            "https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -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.