Mesa 3.1.0.dev0__py3-none-any.whl → 3.1.1__py3-none-any.whl

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

mesa/experimental/cell_space/voronoi.py

@@ -1,4 +1,16 @@
-"""Support for Voronoi meshed grids."""
+"""Cell spaces based on Voronoi tessellation around seed points.
+
+Creates irregular spatial divisions by building cells around seed points,
+where each cell contains the area closer to its seed than any other.
+Features:
+- Organic-looking spaces from point sets
+- Automatic neighbor determination
+- Area-based cell capacities
+- Natural regional divisions
+
+Useful for models requiring irregular but mathematically meaningful spatial
+divisions, like territories, service areas, or natural regions.
+"""
 
 from collections.abc import Sequence
 from itertools import combinations

mesa/experimental/devs/__init__.py

@@ -1,6 +1,24 @@
-"""Support for event scheduling."""
+"""Core event management functionality for Mesa's discrete event simulation system.
+
+This module provides the foundational data structures and classes needed for event-based
+simulation in Mesa. The EventList class is a priority queue implementation that maintains
+simulation events in chronological order while respecting event priorities. Key features:
+
+- Priority-based event ordering
+- Weak references to prevent memory leaks from canceled events
+- Efficient event insertion and removal using a heap queue
+- Support for event cancellation without breaking the heap structure
+
+The module contains three main components:
+- Priority: An enumeration defining event priority levels (HIGH, DEFAULT, LOW)
+- SimulationEvent: A class representing individual events with timing and execution details
+- EventList: A heap-based priority queue managing the chronological ordering of events
+
+The implementation supports both pure discrete event simulation and hybrid approaches
+combining agent-based modeling with event scheduling.
+"""
 
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator
 
-__all__ = ["ABMSimulator", "DEVSimulator", "SimulationEvent", "Priority"]
+__all__ = ["ABMSimulator", "DEVSimulator", "Priority", "SimulationEvent"]

mesa/experimental/devs/eventlist.py

@@ -1,4 +1,22 @@
-"""Eventlist which is at the core of event scheduling."""
+"""Core event management functionality for Mesa's discrete event simulation system.
+
+This module provides the foundational data structures and classes needed for event-based
+simulation in Mesa. The EventList class is a priority queue implementation that maintains
+simulation events in chronological order while respecting event priorities. Key features:
+
+- Priority-based event ordering
+- Weak references to prevent memory leaks from canceled events
+- Efficient event insertion and removal using a heap queue
+- Support for event cancellation without breaking the heap structure
+
+The module contains three main components:
+- Priority: An enumeration defining event priority levels (HIGH, DEFAULT, LOW)
+- SimulationEvent: A class representing individual events with timing and execution details
+- EventList: A heap-based priority queue managing the chronological ordering of events
+
+The implementation supports both pure discrete event simulation and hybrid approaches
+combining agent-based modeling with event scheduling.
+"""
 
 from __future__ import annotations
 

mesa/experimental/devs/simulator.py

@@ -1,20 +1,36 @@
-"""Provides several simulator classes.
-
-A Simulator is responsible for executing a simulation model. It controls time advancement and enables event scheduling.
-
-
+"""Simulator implementations for different time advancement approaches in Mesa.
+
+This module provides simulator classes that control how simulation time advances and how
+events are executed. It supports both discrete-time and continuous-time simulations through
+three main classes:
+
+- Simulator: Base class defining the core simulation control interface
+- ABMSimulator: A simulator for agent-based models that combines fixed time steps with
+  event scheduling. Uses integer time units and automatically schedules model.step()
+- DEVSimulator: A pure discrete event simulator using floating-point time units for
+  continuous time simulation
+
+Key features:
+- Flexible time units (integer or float)
+- Event scheduling using absolute or relative times
+- Priority-based event execution
+- Support for running simulations for specific durations or until specific end times
+
+The simulators enable Mesa models to use traditional time-step based approaches, pure
+event-driven approaches, or hybrid combinations of both.
 """
 
 from __future__ import annotations
 
 import numbers
 from collections.abc import Callable
-from typing import Any
-
-from mesa import Model
+from typing import TYPE_CHECKING, Any
 
 from .eventlist import EventList, Priority, SimulationEvent
 
+if TYPE_CHECKING:
+    from mesa import Model
+
 
 class Simulator:
     """The Simulator controls the time advancement of the model.

mesa/experimental/mesa_signals/__init__.py

@@ -0,0 +1,23 @@
+"""Mesa Signals (Observables) package that provides reactive programming capabilities.
+
+This package enables tracking changes to properties and state in Mesa models through a
+reactive programming paradigm. It enables building models where components can observe
+and react to changes in other components' state.
+
+The package provides the core Observable classes and utilities needed to implement
+reactive patterns in agent-based models. This includes capabilities for watching changes
+to attributes, computing derived values, and managing collections that emit signals
+when modified.
+"""
+
+from .mesa_signal import All, Computable, Computed, HasObservables, Observable
+from .observable_collections import ObservableList
+
+__all__ = [
+    "All",
+    "Computable",
+    "Computed",
+    "HasObservables",
+    "Observable",
+    "ObservableList",
+]