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

mesa/examples/basic/schelling/analysis.ipynb

@@ -17,7 +17,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
     "import pandas as pd\n",
@@ -25,9 +27,7 @@
     "%matplotlib inline\n",
     "\n",
     "from model import Schelling"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -38,10 +38,14 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": "model = Schelling(height=10, width=10, homophily=3, density=0.8, minority_pc=0.2)",
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "schelling_model = Schelling(\n",
+    "    height=10, width=10, homophily=3, density=0.8, minority_pc=0.2\n",
+    ")"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -52,14 +56,14 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": [
-    "while model.running and model.steps < 100:\n",
-    "    model.step()\n",
-    "print(model.steps)  # Show how many steps have actually run"
-   ],
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "while schelling_model.running and schelling_model.steps < 100:\n",
+    "    schelling_model.step()\n",
+    "print(schelling_model.steps)  # Show how many steps have actually run"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -70,21 +74,21 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": [
-    "model_out = model.datacollector.get_model_vars_dataframe()"
-   ],
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "model_out = schelling_model.datacollector.get_model_vars_dataframe()"
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "model_out.head()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -95,12 +99,12 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "model_out.happy.plot()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
@@ -115,10 +119,12 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
-   "source": "from mesa.batchrunner import batch_run",
    "outputs": [],
-   "execution_count": null
+   "source": [
+    "from mesa.batchrunner import batch_run"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -129,18 +135,20 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "fixed_params = {\"height\": 10, \"width\": 10, \"density\": 0.8, \"minority_pc\": 0.2}\n",
     "variable_parms = {\"homophily\": range(1, 9)}\n",
     "all_params = fixed_params | variable_parms"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "results = batch_run(\n",
     "    Schelling,\n",
@@ -148,23 +156,23 @@
     "    iterations=10,\n",
     "    max_steps=200,\n",
     ")"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "df = pd.DataFrame(results)\n",
     "df"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
+   "outputs": [],
    "source": [
     "plt.scatter(df.homophily, df.happy)\n",
     "plt.xlabel(\"Homophily\")\n",
@@ -172,9 +180,7 @@
     "plt.grid()\n",
     "plt.title(\"Effect of Homophily on segregation\")\n",
     "plt.show()"
-   ],
-   "outputs": [],
-   "execution_count": null
+   ]
   }
  ],
  "metadata": {

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.4, 0.0, 1.0, 0.125),
     "width": 20,
     "height": 20,
 }

mesa/examples/basic/schelling/model.py

@@ -9,11 +9,11 @@ class Schelling(Model):
 
     def __init__(
         self,
-        height: int = 40,
-        width: int = 40,
+        height: int = 20,
+        width: int = 20,
         density: float = 0.8,
         minority_pc: float = 0.5,
-        homophily: int = 3,
+        homophily: float = 0.4,
         radius: int = 1,
         seed=None,
     ):

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