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

mesa/experimental/cell_space/cell_agent.py

@@ -1,37 +1,133 @@
+"""An agent with movement methods for cell spaces."""
+
 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."""
 
+    cell: Cell
 
-    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
-    """
 
-    def __init__(self, model: Model) -> None:
-        """
-        Create a new agent.
+class HasCell:
+    """Descriptor for cell movement behavior."""
 
-        Args:
-            unique_id (int): A unique identifier for this agent.
-            model (Model): The model instance in which the agent exists.
-        """
-        super().__init__(model)
-        self.cell: Cell | None = None
+    _mesa_cell: Cell | None = None
 
-    def move_to(self, cell) -> None:
+    @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/cell_collection.py

@@ -1,3 +1,5 @@
+"""CellCollection class."""
+
 from __future__ import annotations
 
 import itertools
@@ -14,7 +16,7 @@ T = TypeVar("T", bound="Cell")
 
 
 class CellCollection(Generic[T]):
-    """An immutable collection of cells
+    """An immutable collection of cells.
 
     Attributes:
         cells (List[Cell]): The list of cells this collection represents
@@ -28,6 +30,12 @@ class CellCollection(Generic[T]):
         cells: Mapping[T, list[CellAgent]] | Iterable[T],
         random: Random | None = None,
     ) -> None:
+        """Initialize a CellCollection.
+
+        Args:
+            cells: cells to add to the collection
+            random: a seeded random number generator.
+        """
         if isinstance(cells, dict):
             self._cells = cells
         else:
@@ -40,42 +48,71 @@ class CellCollection(Generic[T]):
             random = Random()  # FIXME
         self.random = random
 
-    def __iter__(self):
+    def __iter__(self):  # noqa
         return iter(self._cells)
 
-    def __getitem__(self, key: T) -> Iterable[CellAgent]:
+    def __getitem__(self, key: T) -> Iterable[CellAgent]:  # noqa
         return self._cells[key]
 
     # @cached_property
-    def __len__(self) -> int:
+    def __len__(self) -> int:  # noqa
         return len(self._cells)
 
-    def __repr__(self):
+    def __repr__(self):  # noqa
         return f"CellCollection({self._cells})"
 
     @cached_property
-    def cells(self) -> list[T]:
+    def cells(self) -> list[T]:  # noqa
         return list(self._cells.keys())
 
     @property
-    def agents(self) -> Iterable[CellAgent]:
+    def agents(self) -> Iterable[CellAgent]:  # noqa
         return itertools.chain.from_iterable(self._cells.values())
 
     def select_random_cell(self) -> T:
+        """Select a random cell."""
         return self.random.choice(self.cells)
 
     def select_random_agent(self) -> CellAgent:
+        """Select a random agent.
+
+        Returns:
+            CellAgent instance
+
+
+        """
         return self.random.choice(list(self.agents))
 
-    def select(self, filter_func: Callable[[T], bool] | None = None, n=0):
-        # FIXME: n is not considered
-        if filter_func is None and n == 0:
+    def select(
+        self,
+        filter_func: Callable[[T], bool] | None = None,
+        at_most: int | float = float("inf"),
+    ):
+        """Select cells based on filter function.
+
+        Args:
+            filter_func: filter function
+            at_most: The maximum amount of cells to select. Defaults to infinity.
+              - If an integer, at most the first number of matching cells is selected.
+              - If a float between 0 and 1, at most that fraction of original number of cells
+
+        Returns:
+            CellCollection
+
+        """
+        if filter_func is None and at_most == float("inf"):
             return self
 
-        return CellCollection(
-            {
-                cell: agents
-                for cell, agents in self._cells.items()
-                if filter_func is None or filter_func(cell)
-            }
-        )
+        if at_most <= 1.0 and isinstance(at_most, float):
+            at_most = int(len(self) * at_most)  # Note that it rounds down (floor)
+
+        def cell_generator(filter_func, at_most):
+            count = 0
+            for cell in self:
+                if count >= at_most:
+                    break
+                if not filter_func or filter_func(cell):
+                    yield cell
+                    count += 1
+
+        return CellCollection(cell_generator(filter_func, at_most))

mesa/experimental/cell_space/discrete_space.py

@@ -1,11 +1,15 @@
+"""DiscreteSpace base class."""
+
 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)
 
@@ -19,7 +23,7 @@ class DiscreteSpace(Generic[T]):
         random (Random): The random number generator
         cell_klass (Type) : the type of cell class
         empties (CellCollection) : collecction of all cells that are empty
-
+        property_layers (dict[str, PropertyLayer]): the property layers of the discrete space
     """
 
     def __init__(
@@ -28,6 +32,13 @@ class DiscreteSpace(Generic[T]):
         cell_klass: type[T] = Cell,
         random: Random | None = None,
     ):
+        """Instantiate a DiscreteSpace.
+
+        Args:
+            capacity: capacity of cells
+            cell_klass: base class for all cells
+            random: random number generator
+        """
         super().__init__()
         self.capacity = capacity
         self._cells: dict[tuple[int, ...], T] = {}
@@ -38,27 +49,88 @@ 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):
+    def cutoff_empties(self):  # noqa
         return 7.953 * len(self._cells) ** 0.384
 
     def _connect_single_cell(self, cell: T): ...
 
     @cached_property
     def all_cells(self):
+        """Return all cells in space."""
         return CellCollection({cell: cell.agents for cell in self._cells.values()})
 
-    def __iter__(self):
+    def __iter__(self):  # noqa
         return iter(self._cells.values())
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: tuple[int, ...]) -> T:  # noqa: D105
         return self._cells[key]
 
     @property
-    def empties(self) -> CellCollection:
+    def empties(self) -> CellCollection[T]:
+        """Return all empty in spaces."""
         return self.all_cells.select(lambda cell: cell.is_empty)
 
     def select_random_empty_cell(self) -> T:
-        """select random empty cell"""
+        """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)

mesa/experimental/cell_space/grid.py

@@ -1,3 +1,5 @@
+"""Various Grid Spaces."""
+
 from __future__ import annotations
 
 from collections.abc import Sequence
@@ -10,8 +12,8 @@ from mesa.experimental.cell_space import Cell, DiscreteSpace
 T = TypeVar("T", bound=Cell)
 
 
-class Grid(DiscreteSpace, Generic[T]):
-    """Base class for all grid classes
+class Grid(DiscreteSpace[T], Generic[T]):
+    """Base class for all grid classes.
 
     Attributes:
         dimensions (Sequence[int]): the dimensions of the grid
@@ -30,6 +32,15 @@ class Grid(DiscreteSpace, Generic[T]):
         random: Random | None = None,
         cell_klass: type[T] = Cell,
     ) -> None:
+        """Initialise the grid class.
+
+        Args:
+            dimensions: the dimensions of the space
+            torus: whether the space wraps
+            capacity: capacity of the grid cell
+            random: a random number generator
+            cell_klass: the base class to use for the cells
+        """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
         self.torus = torus
         self.dimensions = dimensions
@@ -63,7 +74,7 @@ class Grid(DiscreteSpace, Generic[T]):
         if self.capacity is not None and not isinstance(self.capacity, float | int):
             raise ValueError("Capacity must be a number or None.")
 
-    def select_random_empty_cell(self) -> T:
+    def select_random_empty_cell(self) -> T:  # noqa
         # FIXME:: currently just a simple boolean to control behavior
         # FIXME:: basically if grid is close to 99% full, creating empty list can be faster
         # FIXME:: note however that the old results don't apply because in this implementation
@@ -89,7 +100,7 @@ class Grid(DiscreteSpace, Generic[T]):
             if self.torus:
                 n_coord = tuple(nc % d for nc, d in zip(n_coord, self.dimensions))
             if all(0 <= nc < d for nc, d in zip(n_coord, self.dimensions)):
-                cell.connect(self._cells[n_coord])
+                cell.connect(self._cells[n_coord], d_coord)
 
     def _connect_single_cell_2d(self, cell: T, offsets: list[tuple[int, int]]) -> None:
         i, j = cell.coordinate
@@ -100,7 +111,7 @@ class Grid(DiscreteSpace, Generic[T]):
             if self.torus:
                 ni, nj = ni % height, nj % width
             if 0 <= ni < height and 0 <= nj < width:
-                cell.connect(self._cells[ni, nj])
+                cell.connect(self._cells[ni, nj], (di, dj))
 
 
 class OrthogonalMooreGrid(Grid[T]):
@@ -122,7 +133,6 @@ class OrthogonalMooreGrid(Grid[T]):
             ( 1, -1), ( 1, 0), ( 1, 1),
         ]
         # fmt: on
-        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
@@ -154,13 +164,12 @@ class OrthogonalVonNeumannGrid(Grid[T]):
                     ( 1, 0),
         ]
         # fmt: on
-        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
 
     def _connect_cells_nd(self) -> None:
-        offsets = []
+        offsets: list[tuple[int, ...]] = []
         dimensions = len(self.dimensions)
         for dim in range(dimensions):
             for delta in [
@@ -176,6 +185,8 @@ class OrthogonalVonNeumannGrid(Grid[T]):
 
 
 class HexGrid(Grid[T]):
+    """A Grid with hexagonal tilling of the space."""
+
     def _connect_cells_2d(self) -> None:
         # fmt: off
         even_offsets = [

mesa/experimental/cell_space/network.py

@@ -1,3 +1,5 @@
+"""A Network grid."""
+
 from random import Random
 from typing import Any
 
@@ -5,8 +7,8 @@ from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 
 
-class Network(DiscreteSpace):
-    """A networked discrete space"""
+class Network(DiscreteSpace[Cell]):
+    """A networked discrete space."""
 
     def __init__(
         self,
@@ -15,13 +17,13 @@ class Network(DiscreteSpace):
         random: Random | None = None,
         cell_klass: type[Cell] = Cell,
     ) -> None:
-        """A Networked grid
+        """A Networked grid.
 
         Args:
             G: a NetworkX Graph instance.
             capacity (int) : the capacity of the cell
-            random (Random):
-            CellKlass (type[Cell]): The base Cell class to use in the Network
+            random (Random): a random number generator
+            cell_klass (type[Cell]): The base Cell class to use in the Network
 
         """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
@@ -35,6 +37,6 @@ class Network(DiscreteSpace):
         for cell in self.all_cells:
             self._connect_single_cell(cell)
 
-    def _connect_single_cell(self, cell):
+    def _connect_single_cell(self, cell: Cell):
         for node_id in self.G.neighbors(cell.coordinate):
-            cell.connect(self._cells[node_id])
+            cell.connect(self._cells[node_id], node_id)

mesa/experimental/cell_space/voronoi.py

@@ -1,3 +1,5 @@
+"""Support for Voronoi meshed grids."""
+
 from collections.abc import Sequence
 from itertools import combinations
 from random import Random
@@ -9,16 +11,17 @@ from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 
 
 class Delaunay:
-    """
-    Class to compute a Delaunay triangulation in 2D
+    """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.
+        """Init and create a new frame to contain the triangulation.
+
+        Args:
+            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
@@ -44,9 +47,7 @@ class Delaunay:
             self.circles[t] = self._circumcenter(t)
 
     def _circumcenter(self, triangle: list) -> tuple:
-        """
-        Compute circumcenter and circumradius of a triangle in 2D.
-        """
+        """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]]]])
@@ -60,16 +61,12 @@ class Delaunay:
         return (center, radius)
 
     def _in_circle(self, triangle: list, point: list) -> bool:
-        """
-        Check if point p is inside of precomputed circumcircle of triangle.
-        """
+        """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.
-        """
+        """Add a point to the current DT, and refine it using Bowyer-Watson."""
         point_index = len(self.coords)
         self.coords.append(np.asarray(point))
 
@@ -121,9 +118,7 @@ class Delaunay:
             self.triangles[triangle][2] = new_triangles[(i - 1) % n]  # previous
 
     def export_triangles(self) -> list:
-        """
-        Export the current list of Delaunay triangles
-        """
+        """Export the current list of Delaunay triangles."""
         triangles_list = [
             (a - 4, b - 4, c - 4)
             for (a, b, c) in self.triangles
@@ -132,9 +127,7 @@ class Delaunay:
         return triangles_list
 
     def export_voronoi_regions(self):
-        """
-        Export coordinates and regions of Voronoi diagram as indexed data.
-        """
+        """Export coordinates and regions of Voronoi diagram as indexed data."""
         use_vertex = {i: [] for i in range(len(self.coords))}
         vor_coors = []
         index = {}
@@ -163,11 +156,13 @@ class Delaunay:
         return vor_coors, regions
 
 
-def round_float(x: float) -> int:
+def round_float(x: float) -> int:  # noqa
     return int(x * 500)
 
 
 class VoronoiGrid(DiscreteSpace):
+    """Voronoi meshed GridSpace."""
+
     triangulation: Delaunay
     voronoi_coordinates: list
     regions: list
@@ -181,8 +176,7 @@ class VoronoiGrid(DiscreteSpace):
         capacity_function: callable = round_float,
         cell_coloring_property: str | None = None,
     ) -> None:
-        """
-        A Voronoi Tessellation Grid.
+        """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
@@ -192,7 +186,7 @@ class VoronoiGrid(DiscreteSpace):
             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
+            cell_klass (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
         """
@@ -215,17 +209,15 @@ class VoronoiGrid(DiscreteSpace):
         self._build_cell_polygons()
 
     def _connect_cells(self) -> None:
-        """
-        Connect cells to neighbors based on given centroids and using Delaunay Triangulation
-        """
+        """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])
+                self._cells[i].connect(self._cells[j], (i, j))
+                self._cells[j].connect(self._cells[i], (j, i))
 
     def _validate_parameters(self) -> None:
         if self.capacity is not None and not isinstance(self.capacity, float | int):
@@ -241,9 +233,10 @@ class VoronoiGrid(DiscreteSpace):
 
     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()
-            )
+            (
+                self.voronoi_coordinates,
+                self.regions,
+            ) = self.triangulation.export_voronoi_regions()
         return self.voronoi_coordinates, self.regions
 
     @staticmethod