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

mesa/examples/basic/conways_game_of_life/app.py

@@ -20,6 +20,11 @@ def post_process(ax):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": {
         "type": "SliderInt",
         "value": 50,

mesa/examples/basic/conways_game_of_life/st_app.py

@@ -49,9 +49,9 @@ if run:
     for i in range(num_ticks):
         model.step()
         my_bar.progress((i / num_ticks), text="Simulation progress")
-        placeholder.text("Step = %d" % i)
+        placeholder.text(f"Step = {i}")
         for contents, (x, y) in model.grid.coord_iter():
-            # print('x:',x,'y:',y, 'state:',contents)
+            # print(f"x: {x}, y: {y}, state: {contents}")
             selected_row = df_grid[(df_grid["x"] == x) & (df_grid["y"] == y)]
             df_grid.loc[selected_row.index, "state"] = (
                 contents.state

mesa/examples/basic/schelling/agents.py

@@ -6,7 +6,6 @@ class SchellingAgent(Agent):
 
     def __init__(self, model, agent_type: int) -> None:
         """Create a new Schelling agent.
-
         Args:
             model: The model instance the agent belongs to
             agent_type: Indicator for the agent's type (minority=1, majority=0)
@@ -16,15 +15,22 @@ class SchellingAgent(Agent):
 
     def step(self) -> None:
         """Determine if agent is happy and move if necessary."""
-        neighbors = self.model.grid.iter_neighbors(
+        neighbors = self.model.grid.get_neighbors(
             self.pos, moore=True, radius=self.model.radius
         )
 
         # Count similar neighbors
-        similar = sum(neighbor.type == self.type for neighbor in neighbors)
+        similar_neighbors = len([n for n in neighbors if n.type == self.type])
+
+        # Calculate the fraction of similar neighbors
+        if (valid_neighbors := len(neighbors)) > 0:
+            similarity_fraction = similar_neighbors / valid_neighbors
+        else:
+            # If there are no neighbors, the similarity fraction is 0
+            similarity_fraction = 0.0
 
-        # If unhappy, move to a random empty cell:
-        if similar < self.model.homophily:
+        # Move if unhappy
+        if similarity_fraction < self.model.homophily:
             self.model.grid.move_to_empty(self)
         else:
             self.model.happy += 1

mesa/examples/basic/schelling/app.py

@@ -19,9 +19,14 @@ def agent_portrayal(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "density": Slider("Agent density", 0.8, 0.1, 1.0, 0.1),
     "minority_pc": Slider("Fraction minority", 0.2, 0.0, 1.0, 0.05),
-    "homophily": Slider("Homophily", 3, 0, 8, 1),
+    "homophily": Slider("Homophily", 0.3, 0.0, 0.8, 0.1),
     "width": 20,
     "height": 20,
 }

mesa/examples/basic/virus_on_network/app.py

@@ -35,6 +35,11 @@ def get_resistant_susceptible_ratio(model):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "num_nodes": Slider(
         label="Number of agents",
         value=10,

mesa/experimental/__init__.py

@@ -1,13 +1,20 @@
-"""Experimental init."""
+"""Experimental features package for Mesa.
 
-from mesa.experimental import cell_space
+This package contains modules that are under active development and testing. These
+features are provided to allow early access and feedback from the Mesa community, but
+their APIs may change between releases without following semantic versioning.
 
-try:
-    from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
+Current experimental modules:
+    cell_space: Alternative API for discrete spaces with cell-centric functionality
+    devs: Discrete event simulation system for scheduling events at arbitrary times
+    mesa_signals: Reactive programming capabilities for tracking state changes
 
-    __all__ = ["cell_space", "JupyterViz", "Slider", "SolaraViz", "make_text"]
-except ImportError:
-    print(
-        "Could not import SolaraViz. If you need it, install with 'pip install --pre mesa[viz]'"
-    )
-    __all__ = ["cell_space"]
+Notes:
+    - Features in this package may be changed or removed without notice
+    - APIs are not guaranteed to be stable between releases
+    - Features graduate from experimental status once their APIs are stabilized
+"""
+
+from mesa.experimental import cell_space, devs, mesa_signals
+
+__all__ = ["cell_space", "devs", "mesa_signals"]

mesa/experimental/cell_space/__init__.py

@@ -1,8 +1,18 @@
-"""Cell spaces.
+"""Cell spaces for active, property-rich spatial modeling in Mesa.
 
-Cell spaces offer an alternative API for discrete spaces. It is experimental and under development. The API is more
-expressive that the default grids available in `mesa.space`.
+Cell spaces extend Mesa's spatial modeling capabilities by making the space itself active -
+each position (cell) can have properties and behaviors rather than just containing agents.
+This enables more sophisticated environmental modeling and agent-environment interactions.
 
+Key components:
+- Cells: Active positions that can have properties and contain agents
+- CellAgents: Agents that understand how to interact with cells
+- Spaces: Different cell organization patterns (grids, networks, etc.)
+- PropertyLayers: Efficient property storage and manipulation
+
+This is particularly useful for models where the environment plays an active role,
+like resource growth, pollution diffusion, or infrastructure networks. The cell
+space system is experimental and under active development.
 """
 
 from mesa.experimental.cell_space.cell import Cell
@@ -20,19 +30,21 @@ from mesa.experimental.cell_space.grid import (
     OrthogonalVonNeumannGrid,
 )
 from mesa.experimental.cell_space.network import Network
+from mesa.experimental.cell_space.property_layer import PropertyLayer
 from mesa.experimental.cell_space.voronoi import VoronoiGrid
 
 __all__ = [
-    "CellCollection",
     "Cell",
     "CellAgent",
-    "Grid2DMovingAgent",
-    "FixedAgent",
+    "CellCollection",
     "DiscreteSpace",
+    "FixedAgent",
     "Grid",
+    "Grid2DMovingAgent",
     "HexGrid",
+    "Network",
     "OrthogonalMooreGrid",
     "OrthogonalVonNeumannGrid",
-    "Network",
+    "PropertyLayer",
     "VoronoiGrid",
 ]

mesa/experimental/cell_space/cell.py

@@ -1,15 +1,25 @@
-"""The Cell in a cell space."""
+"""Cells are positions in space that can have properties and contain agents.
+
+A cell represents a location that can:
+- Have properties (like temperature or resources)
+- Track and limit the agents it contains
+- Connect to neighboring cells
+- Provide neighborhood information
+
+Cells form the foundation of the cell space system, enabling rich spatial
+environments where both location properties and agent behaviors matter. They're
+useful for modeling things like varying terrain, infrastructure capacity, or
+environmental conditions.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Callable
 from functools import cache, cached_property
 from random import Random
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from mesa.experimental.cell_space.cell_agent import CellAgent
 from mesa.experimental.cell_space.cell_collection import CellCollection
-from mesa.space import PropertyLayer
 
 if TYPE_CHECKING:
     from mesa.agent import Agent
@@ -24,31 +34,20 @@ class Cell:
         coordinate (Tuple[int, int]) : the position of the cell in the discrete space
         agents (List[Agent]): the agents occupying the cell
         capacity (int): the maximum number of agents that can simultaneously occupy the cell
-        properties (dict[str, Any]): the properties of the cell
         random (Random): the random number generator
 
     """
 
     __slots__ = [
-        "coordinate",
-        "connections",
+        "__dict__",
         "agents",
         "capacity",
+        "connections",
+        "coordinate",
         "properties",
         "random",
-        "_mesa_property_layers",
-        "__dict__",
     ]
 
-    # def __new__(cls,
-    #     coordinate: tuple[int, ...],
-    #     capacity: float | None = None,
-    #     random: Random | None = None,):
-    #     if capacity != 1:
-    #         return object.__new__(cls)
-    #     else:
-    #         return object.__new__(SingleAgentCell)
-
     def __init__(
         self,
         coordinate: Coordinate,
@@ -70,9 +69,10 @@ class Cell:
             Agent
         ] = []  # TODO:: change to AgentSet or weakrefs? (neither is very performant, )
         self.capacity: int | None = capacity
-        self.properties: dict[Coordinate, object] = {}
+        self.properties: dict[
+            Coordinate, object
+        ] = {}  # fixme still used by voronoi mesh
         self.random = random
-        self._mesa_property_layers: dict[str, PropertyLayer] = {}
 
     def connect(self, other: Cell, key: Coordinate | None = None) -> None:
         """Connects this cell to another cell.
@@ -105,6 +105,7 @@ class Cell:
 
         """
         n = len(self.agents)
+        self.empty = False
 
         if self.capacity and n >= self.capacity:
             raise Exception(
@@ -121,6 +122,7 @@ class Cell:
 
         """
         self.agents.remove(agent)
+        self.empty = self.is_empty
 
     @property
     def is_empty(self) -> bool:
@@ -195,23 +197,6 @@ class Cell:
                 neighborhood.pop(self, None)
             return neighborhood
 
-    # PropertyLayer methods
-    def get_property(self, property_name: str) -> Any:
-        """Get the value of a property."""
-        return self._mesa_property_layers[property_name].data[self.coordinate]
-
-    def set_property(self, property_name: str, value: Any):
-        """Set the value of a property."""
-        self._mesa_property_layers[property_name].set_cell(self.coordinate, value)
-
-    def modify_property(
-        self, property_name: str, operation: Callable, value: Any = None
-    ):
-        """Modify the value of a property."""
-        self._mesa_property_layers[property_name].modify_cell(
-            self.coordinate, operation, value
-        )
-
     def __getstate__(self):
         """Return state of the Cell with connections set to empty."""
         # fixme, once we shift to 3.11, replace this with super. __getstate__

mesa/experimental/cell_space/cell_agent.py

@@ -1,4 +1,15 @@
-"""An agent with movement methods for cell spaces."""
+"""Agents that understand how to exist in and move through cell spaces.
+
+Provides specialized agent classes that handle cell occupation, movement, and
+proper registration:
+- CellAgent: Mobile agents that can move between cells
+- FixedAgent: Immobile agents permanently fixed to cells
+- Grid2DMovingAgent: Agents with grid-specific movement capabilities
+
+These classes ensure consistent agent-cell relationships and proper state management
+as agents move through the space. They can be used directly or as examples for
+creating custom cell-aware agents.
+"""
 
 from __future__ import annotations
 

mesa/experimental/cell_space/cell_collection.py

@@ -1,4 +1,17 @@
-"""CellCollection class."""
+"""Collection class for managing and querying groups of cells.
+
+The CellCollection class provides a consistent interface for operating on multiple
+cells, supporting:
+- Filtering and selecting cells based on conditions
+- Random cell and agent selection
+- Access to contained agents
+- Group operations
+
+This is useful for implementing area effects, zones, or any operation that needs
+to work with multiple cells as a unit. The collection handles efficient iteration
+and agent access across cells. The class is used throughout the cell space
+implementation to represent neighborhoods, selections, and other cell groupings.
+"""
 
 from __future__ import annotations
 
@@ -48,8 +61,10 @@ class CellCollection(Generic[T]):
         else:
             self._cells = {cell: cell.agents for cell in cells}
 
-        #
-        self._capacity: int = next(iter(self._cells.keys())).capacity
+        # Get capacity from first cell if collection is not empty
+        self._capacity: int | None = (
+            next(iter(self._cells.keys())).capacity if self._cells else None
+        )
 
         if random is None:
             warnings.warn(

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