Mesa 3.0.2__py3-none-any.whl → 3.1.0__py3-none-any.whl

mesa/experimental/cell_space/discrete_space.py

@@ -1,17 +1,28 @@
-"""DiscreteSpace base class."""
+"""Base class for building cell-based spatial environments.
+
+DiscreteSpace provides the core functionality needed by all cell-based spaces:
+- Cell creation and tracking
+- Agent-cell relationship management
+- Property layer support
+- Random selection capabilities
+- Capacity management
+
+This serves as the foundation for specific space implementations like grids
+and networks, ensuring consistent behavior and shared functionality across
+different space types. All concrete cell space implementations (grids, networks, etc.)
+inherit from this class.
+"""
 
 from __future__ import annotations
 
 import warnings
-from collections.abc import Callable
 from functools import cached_property
 from random import Random
-from typing import Any, Generic, TypeVar
+from typing import 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
 
 T = TypeVar("T", bound=Cell)
 
@@ -61,8 +72,6 @@ class DiscreteSpace(Generic[T]):
         self.cell_klass = cell_klass
 
         self._empties: dict[tuple[int, ...], None] = {}
-        self._empties_initialized = False
-        self.property_layers: dict[str, PropertyLayer] = {}
 
     @property
     def cutoff_empties(self):  # noqa
@@ -98,64 +107,6 @@ class DiscreteSpace(Generic[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

mesa/experimental/cell_space/grid.py

@@ -1,18 +1,62 @@
-"""Various Grid Spaces."""
+"""Grid-based cell space implementations with different connection patterns.
+
+Provides several grid types for organizing cells:
+- OrthogonalMooreGrid: 8 neighbors in 2D, (3^n)-1 in nD
+- OrthogonalVonNeumannGrid: 4 neighbors in 2D, 2n in nD
+- HexGrid: 6 neighbors in hexagonal pattern (2D only)
+
+Each grid type supports optional wrapping (torus) and cell capacity limits.
+Choose based on how movement and connectivity should work in your model -
+Moore for unrestricted movement, Von Neumann for orthogonal-only movement,
+or Hex for more uniform distances.
+"""
 
 from __future__ import annotations
 
+import copyreg
 from collections.abc import Sequence
 from itertools import product
 from random import Random
-from typing import Generic, TypeVar
+from typing import Any, Generic, TypeVar
 
 from mesa.experimental.cell_space import Cell, DiscreteSpace
+from mesa.experimental.cell_space.property_layer import (
+    HasPropertyLayers,
+    PropertyDescriptor,
+)
 
 T = TypeVar("T", bound=Cell)
 
 
-class Grid(DiscreteSpace[T], Generic[T]):
+def pickle_gridcell(obj):
+    """Helper function for pickling GridCell instances."""
+    # we have the base class and the state via __getstate__
+    args = obj.__class__.__bases__[0], obj.__getstate__()
+    return unpickle_gridcell, args
+
+
+def unpickle_gridcell(parent, fields):
+    """Helper function for unpickling GridCell instances."""
+    # since the class is dynamically created, we recreate it here
+    cell_klass = type(
+        "GridCell",
+        (parent,),
+        {"_mesa_properties": set()},
+    )
+    instance = cell_klass(
+        (0, 0)
+    )  # we use a default coordinate and overwrite it with the correct value next
+
+    # __gestate__ returns a tuple with dict and slots, but slots contains the dict so we can just use the
+    # second item only
+    for k, v in fields[1].items():
+        if k != "__dict__":
+            setattr(instance, k, v)
+
+    return instance
+
+
+class Grid(DiscreteSpace[T], Generic[T], HasPropertyLayers):
     """Base class for all grid classes.
 
     Attributes:
@@ -60,14 +104,23 @@ class Grid(DiscreteSpace[T], Generic[T]):
         self._try_random = True
         self._ndims = len(dimensions)
         self._validate_parameters()
+        self.cell_klass = type(
+            "GridCell",
+            (self.cell_klass,),
+            {"_mesa_properties": set()},
+        )
+
+        # we register the pickle_gridcell helper function
+        copyreg.pickle(self.cell_klass, pickle_gridcell)
 
         coordinates = product(*(range(dim) for dim in self.dimensions))
 
         self._cells = {
-            coord: cell_klass(coord, capacity, random=self.random)
+            coord: self.cell_klass(coord, capacity, random=self.random)
             for coord in coordinates
         }
         self._connect_cells()
+        self.create_property_layer("empty", default_value=True, dtype=bool)
 
     def _connect_cells(self) -> None:
         if self._ndims == 2:
@@ -126,6 +179,23 @@ class Grid(DiscreteSpace[T], Generic[T]):
             if 0 <= ni < height and 0 <= nj < width:
                 cell.connect(self._cells[ni, nj], (di, dj))
 
+    def __getstate__(self) -> dict[str, Any]:
+        """Custom __getstate__ for handling dynamic GridCell class and PropertyDescriptors."""
+        state = super().__getstate__()
+        state = {k: v for k, v in state.items() if k != "cell_klass"}
+        return state
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        """Custom __setstate__ for handling dynamic GridCell class and PropertyDescriptors."""
+        self.__dict__ = state
+        self._connect_cells()  # using super fails for this for some reason, so we repeat ourselves
+
+        self.cell_klass = type(
+            self._cells[(0, 0)]
+        )  # the __reduce__ function handles this for us nicely
+        for layer in self._mesa_property_layers.values():
+            setattr(self.cell_klass, layer.name, PropertyDescriptor(layer))
+
 
 class OrthogonalMooreGrid(Grid[T]):
     """Grid where cells are connected to their 8 neighbors.

mesa/experimental/cell_space/network.py

@@ -1,4 +1,16 @@
-"""A Network grid."""
+"""Network-based cell space using arbitrary connection patterns.
+
+Creates spaces where cells connect based on network relationships rather than
+spatial proximity. Built on NetworkX graphs, this enables:
+- Arbitrary connectivity patterns between cells
+- Graph-based neighborhood definitions
+- Logical rather than physical distances
+- Dynamic connectivity changes
+- Integration with NetworkX's graph algorithms
+
+Useful for modeling systems like social networks, transportation systems,
+or any environment where connectivity matters more than physical location.
+"""
 
 from random import Random
 from typing import Any

mesa/experimental/cell_space/property_layer.py

@@ -0,0 +1,444 @@
+"""Efficient storage and manipulation of cell properties across spaces.
+
+PropertyLayers provide a way to associate properties with cells in a space efficiently.
+The module includes:
+- PropertyLayer class for managing grid-wide properties
+- Property access descriptors for cells
+- Batch operations for property modification
+- Property-based cell selection
+- Integration with numpy for efficient operations
+
+This system separates property storage from cells themselves, enabling
+fast bulk operations and sophisticated property-based behaviors while
+maintaining an intuitive interface through cell attributes. Properties
+can represent environmental factors, cell states, or any other grid-wide
+attributes.
+"""
+
+import warnings
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+import numpy as np
+
+from mesa.experimental.cell_space import Cell
+
+Coordinate = Sequence[int]
+T = TypeVar("T", bound=Cell)
+
+
+class PropertyLayer:
+    """A class representing a layer of properties in a two-dimensional grid.
+
+    Each cell in the grid can store a value of a specified data type.
+
+    Attributes:
+        name: The name of the property layer.
+        dimensions: The width of the grid (number of columns).
+        data: A NumPy array representing the grid data.
+
+    """
+
+    # Fixme
+    #  can't we simplify this a lot
+    #  in essence, this is just a numpy array with a name and fixed dimensions
+    #  all other functionality seems redundant to me?
+
+    @property
+    def data(self):  # noqa: D102
+        return self._mesa_data
+
+    @data.setter
+    def data(self, value):
+        self.set_cells(value)
+
+    propertylayer_experimental_warning_given = False
+
+    def __init__(
+        self, name: str, dimensions: Sequence[int], default_value=0.0, dtype=float
+    ):
+        """Initializes a new PropertyLayer instance.
+
+        Args:
+            name: The name of the property layer.
+            dimensions: the dimensions of the property layer.
+            default_value: The default value to initialize each cell in the grid. Should ideally
+                           be of the same type as specified by the dtype parameter.
+            dtype (data-type, optional): The desired data-type for the grid's elements. Default is float.
+
+        Notes:
+            A UserWarning is raised if the default_value is not of a type compatible with dtype.
+            The dtype parameter can accept both Python data types (like bool, int or float) and NumPy data types
+            (like np.int64 or np.float64).
+        """
+        self.name = name
+        self.dimensions = dimensions
+
+        # Check if the dtype is suitable for the data
+        if not isinstance(default_value, dtype):
+            warnings.warn(
+                f"Default value {default_value} ({type(default_value).__name__}) might not be best suitable with dtype={dtype.__name__}.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        # fixme why not initialize with empty?
+        self._mesa_data = np.full(self.dimensions, default_value, dtype=dtype)
+
+        if not self.__class__.propertylayer_experimental_warning_given:
+            warnings.warn(
+                "The property layer functionality and associated classes are experimental. It may be changed or removed in any and all future releases, including patch releases.\n"
+                "We would love to hear what you think about this new feature. If you have any thoughts, share them with us here: https://github.com/projectmesa/mesa/discussions/1932",
+                FutureWarning,
+                stacklevel=2,
+            )
+            self.__class__.propertylayer_experimental_warning_given = True
+
+    @classmethod
+    def from_data(cls, name: str, data: np.ndarray):
+        """Create a property layer from a NumPy array.
+
+        Args:
+            name: The name of the property layer.
+            data: A NumPy array representing the grid data.
+
+        """
+        layer = cls(
+            name,
+            data.shape,
+            default_value=data[*[0 for _ in range(len(data.shape))]],
+            dtype=data.dtype.type,
+        )
+        layer.set_cells(data)
+        return layer
+
+    def set_cells(self, value, condition: Callable | None = None):
+        """Perform a batch update either on the entire grid or conditionally, in-place.
+
+        Args:
+            value: The value to be used for the update.
+            condition: (Optional) A callable that returns a boolean array when applied to the data.
+        """
+        if condition is None:
+            np.copyto(self._mesa_data, value)  # In-place update
+        else:
+            vectorized_condition = np.vectorize(condition)
+            condition_result = vectorized_condition(self._mesa_data)
+            np.copyto(self._mesa_data, value, where=condition_result)
+
+    def modify_cells(
+        self,
+        operation: Callable,
+        value=None,
+        condition: Callable | None = None,
+    ):
+        """Modify cells using an operation, which can be a lambda function or a NumPy ufunc.
+
+        If a NumPy ufunc is used, an additional value should be provided.
+
+        Args:
+            operation: A function to apply. Can be a lambda function or a NumPy ufunc.
+            value: The value to be used if the operation is a NumPy ufunc. Ignored for lambda functions.
+            condition: (Optional) A callable that returns a boolean array when applied to the data.
+        """
+        condition_array = np.ones_like(
+            self._mesa_data, dtype=bool
+        )  # Default condition (all cells)
+        if condition is not None:
+            vectorized_condition = np.vectorize(condition)
+            condition_array = vectorized_condition(self._mesa_data)
+
+        # Check if the operation is a lambda function or a NumPy ufunc
+        if isinstance(operation, np.ufunc):
+            if ufunc_requires_additional_input(operation):
+                if value is None:
+                    raise ValueError("This ufunc requires an additional input value.")
+                modified_data = operation(self._mesa_data, value)
+            else:
+                modified_data = operation(self._mesa_data)
+        else:
+            # Vectorize non-ufunc operations
+            vectorized_operation = np.vectorize(operation)
+            modified_data = vectorized_operation(self._mesa_data)
+
+        self._mesa_data = np.where(condition_array, modified_data, self._mesa_data)
+
+    def select_cells(self, condition: Callable, return_list=True):
+        """Find cells that meet a specified condition using NumPy's boolean indexing, in-place.
+
+        Args:
+            condition: A callable that returns a boolean array when applied to the data.
+            return_list: (Optional) If True, return a list of (x, y) tuples. Otherwise, return a boolean array.
+
+        Returns:
+            A list of (x, y) tuples or a boolean array.
+        """
+        # fixme: consider splitting into two separate functions
+        #  select_cells_boolean
+        #  select_cells_index
+
+        condition_array = condition(self._mesa_data)
+        if return_list:
+            return list(zip(*np.where(condition_array)))
+        else:
+            return condition_array
+
+    def aggregate(self, operation: Callable):
+        """Perform an aggregate operation (e.g., sum, mean) on a property across all cells.
+
+        Args:
+            operation: A function to apply. Can be a lambda function or a NumPy ufunc.
+        """
+        return operation(self._mesa_data)
+
+
+class HasPropertyLayers:
+    """Mixin-like class to add property layer functionality to Grids.
+
+    Property layers can be added to a grid using create_property_layer or add_property_layer. Once created, property
+    layers can be accessed as attributes if the name used for the layer is a valid python identifier.
+
+    """
+
+    # fixme is there a way to indicate that a mixin only works with specific classes?
+    def __init__(self, *args, **kwargs):
+        """Initialize a HasPropertyLayers instance."""
+        super().__init__(*args, **kwargs)
+        self._mesa_property_layers = {}
+
+    def create_property_layer(
+        self,
+        name: str,
+        default_value=0.0,
+        dtype=float,
+    ):
+        """Add a property layer to the grid.
+
+        Args:
+            name: The name of the property layer.
+            default_value: The default value of the property layer.
+            dtype: The data type of the property layer.
+
+        Returns:
+              Property layer instance.
+
+        """
+        layer = PropertyLayer(
+            name, self.dimensions, default_value=default_value, dtype=dtype
+        )
+        self.add_property_layer(layer)
+        return layer
+
+    def add_property_layer(self, layer: PropertyLayer):
+        """Add a predefined property layer to the grid.
+
+        Args:
+            layer: The property layer to add.
+
+        Raises:
+            ValueError: If the dimensions of the layer and the grid are not the same.
+
+        """
+        if layer.dimensions != self.dimensions:
+            raise ValueError(
+                "Dimensions of property layer do not match the dimensions of the grid"
+            )
+        if layer.name in self._mesa_property_layers:
+            raise ValueError(f"Property layer {layer.name} already exists.")
+        if (
+            layer.name in self.cell_klass.__slots__
+            or layer.name in self.cell_klass.__dict__
+        ):
+            raise ValueError(
+                f"Property layer {layer.name} clashes with existing attribute in {self.cell_klass.__name__}"
+            )
+
+        self._mesa_property_layers[layer.name] = layer
+        setattr(self.cell_klass, layer.name, PropertyDescriptor(layer))
+        self.cell_klass._mesa_properties.add(layer.name)
+
+    def remove_property_layer(self, property_name: str):
+        """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._mesa_property_layers[property_name]
+        delattr(self.cell_klass, property_name)
+        self.cell_klass._mesa_properties.remove(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._mesa_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._mesa_property_layers[property_name].modify_cells(
+            operation, value, condition
+        )
+
+    def get_neighborhood_mask(
+        self, coordinate: Coordinate, include_center: bool = True, radius: int = 1
+    ) -> np.ndarray:
+        """Generate a boolean mask representing the neighborhood.
+
+        Args:
+            coordinate: Center of the neighborhood.
+            include_center: Include the central cell in the neighborhood.
+            radius: The radius of the neighborhood.
+
+        Returns:
+            np.ndarray: A boolean mask representing the neighborhood.
+        """
+        cell = self._cells[coordinate]
+        neighborhood = cell.get_neighborhood(
+            include_center=include_center, radius=radius
+        )
+        mask = np.zeros(self.dimensions, dtype=bool)
+
+        # Convert the neighborhood list to a NumPy array and use advanced indexing
+        coords = np.array([c.coordinate for c in neighborhood])
+        indices = [coords[:, i] for i in range(coords.shape[1])]
+        mask[*indices] = True
+        return mask
+
+    def select_cells(
+        self,
+        conditions: dict | None = None,
+        extreme_values: dict | None = None,
+        masks: np.ndarray | list[np.ndarray] = None,
+        only_empty: bool = False,
+        return_list: bool = True,
+    ) -> list[Coordinate] | np.ndarray:
+        """Select cells based on property conditions, extreme values, and/or masks, with an option to only select empty cells.
+
+        Args:
+            conditions (dict): A dictionary where keys are property names and values are callables that return a boolean when applied.
+            extreme_values (dict): A dictionary where keys are property names and values are either 'highest' or 'lowest'.
+            masks (np.ndarray | list[np.ndarray], optional): A mask or list of masks to restrict the selection.
+            only_empty (bool, optional): If True, only select cells that are empty. Default is False.
+            return_list (bool, optional): If True, return a list of coordinates, otherwise return a mask.
+
+        Returns:
+            Union[list[Coordinate], np.ndarray]: Coordinates where conditions are satisfied or the combined mask.
+        """
+        # fixme: consider splitting into two separate functions
+        #  select_cells_boolean
+        #  select_cells_index
+        #  also we might want to change the naming to avoid classes with PropertyLayer
+
+        # Initialize the combined mask
+        combined_mask = np.ones(self.dimensions, dtype=bool)
+
+        # Apply the masks
+        if masks is not None:
+            if isinstance(masks, list):
+                for mask in masks:
+                    combined_mask = np.logical_and(combined_mask, mask)
+            else:
+                combined_mask = np.logical_and(combined_mask, masks)
+
+        # Apply the empty mask if only_empty is True
+        if only_empty:
+            combined_mask = np.logical_and(
+                combined_mask, self._mesa_property_layers["empty"]
+            )
+
+        # Apply conditions
+        if conditions:
+            for prop_name, condition in conditions.items():
+                prop_layer = self._mesa_property_layers[prop_name].data
+                prop_mask = condition(prop_layer)
+                combined_mask = np.logical_and(combined_mask, prop_mask)
+
+        # Apply extreme values
+        if extreme_values:
+            for property_name, mode in extreme_values.items():
+                prop_values = self._mesa_property_layers[property_name].data
+
+                # Create a masked array using the combined_mask
+                masked_values = np.ma.masked_array(prop_values, mask=~combined_mask)
+
+                if mode == "highest":
+                    target_value = masked_values.max()
+                elif mode == "lowest":
+                    target_value = masked_values.min()
+                else:
+                    raise ValueError(
+                        f"Invalid mode {mode}. Choose from 'highest' or 'lowest'."
+                    )
+
+                extreme_value_mask = prop_values == target_value
+                combined_mask = np.logical_and(combined_mask, extreme_value_mask)
+
+        # Generate output
+        if return_list:
+            selected_cells = list(zip(*np.where(combined_mask)))
+            return selected_cells
+        else:
+            return combined_mask
+
+    def __getattr__(self, name: str) -> Any:  # noqa: D105
+        try:
+            return self._mesa_property_layers[name]
+        except KeyError as e:
+            raise AttributeError(
+                f"'{type(self).__name__}' object has no property layer called '{name}'"
+            ) from e
+
+    def __setattr__(self, key, value):  # noqa: D105
+        # fixme
+        #  this might be done more elegantly, the main problem is that _mesa_property_layers must already be defined to avoid infinite recursion errors from happening
+        #  also, this protection only works if the attribute is added after the layer, not the other way around
+        try:
+            layers = self.__dict__["_mesa_property_layers"]
+        except KeyError:
+            super().__setattr__(key, value)
+        else:
+            if key in layers:
+                raise AttributeError(
+                    f"'{type(self).__name__}' object already has a property layer with name '{key}'"
+                )
+            else:
+                super().__setattr__(key, value)
+
+
+class PropertyDescriptor:
+    """Descriptor for giving cells attribute like access to values defined in property layers."""
+
+    def __init__(self, property_layer: PropertyLayer):  # noqa: D107
+        self.layer: PropertyLayer = property_layer
+
+    def __get__(self, instance: Cell, owner):  # noqa: D105
+        return self.layer.data[instance.coordinate]
+
+    def __set__(self, instance: Cell, value):  # noqa: D105
+        self.layer.data[instance.coordinate] = value
+
+
+def ufunc_requires_additional_input(ufunc):  # noqa: D103
+    # NumPy ufuncs have a 'nargs' attribute indicating the number of input arguments
+    # For binary ufuncs (like np.add), nargs is 2
+    return ufunc.nargs > 1