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

mesa/experimental/cell_space/discrete_space.py

@@ -1,28 +1,17 @@
-"""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.
-"""
+"""DiscreteSpace base class."""
 
 from __future__ import annotations
 
 import warnings
+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.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)
 
@@ -72,6 +61,8 @@ 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
@@ -107,6 +98,64 @@ 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,62 +1,18 @@
-"""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.
-"""
+"""Various Grid Spaces."""
 
 from __future__ import annotations
 
-import copyreg
 from collections.abc import Sequence
 from itertools import product
 from random import Random
-from typing import Any, Generic, TypeVar
+from typing import 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)
 
 
-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):
+class Grid(DiscreteSpace[T], Generic[T]):
     """Base class for all grid classes.
 
     Attributes:
@@ -104,23 +60,14 @@ class Grid(DiscreteSpace[T], Generic[T], HasPropertyLayers):
         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: self.cell_klass(coord, capacity, random=self.random)
+            coord: 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:
@@ -179,23 +126,6 @@ class Grid(DiscreteSpace[T], Generic[T], HasPropertyLayers):
             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,16 +1,4 @@
-"""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.
-"""
+"""A Network grid."""
 
 from random import Random
 from typing import Any

mesa/experimental/cell_space/voronoi.py

@@ -1,16 +1,4 @@
-"""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.
-"""
+"""Support for Voronoi meshed grids."""
 
 from collections.abc import Sequence
 from itertools import combinations

mesa/experimental/components/altair.py

@@ -0,0 +1,81 @@
+"""Altair components."""
+
+import contextlib
+
+import solara
+
+with contextlib.suppress(ImportError):
+    import altair as alt
+
+
+@solara.component
+def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+    """A component that renders a Space using Altair.
+
+    Args:
+        model: a model instance
+        agent_portrayal: agent portray specification
+        dependencies: optional list of dependencies (currently not used)
+
+    """
+    space = getattr(model, "grid", None)
+    if space is None:
+        # Sometimes the space is defined as model.space instead of model.grid
+        space = model.space
+    chart = _draw_grid(space, agent_portrayal)
+    solara.FigureAltair(chart)
+
+
+def _draw_grid(space, agent_portrayal):
+    def portray(g):
+        all_agent_data = []
+        for content, (x, y) in g.coord_iter():
+            if not content:
+                continue
+            if not hasattr(content, "__iter__"):
+                # Is a single grid
+                content = [content]  # noqa: PLW2901
+            for agent in content:
+                # use all data from agent portrayal, and add x,y coordinates
+                agent_data = agent_portrayal(agent)
+                agent_data["x"] = x
+                agent_data["y"] = y
+                all_agent_data.append(agent_data)
+        return all_agent_data
+
+    all_agent_data = portray(space)
+    invalid_tooltips = ["color", "size", "x", "y"]
+
+    encoding_dict = {
+        # no x-axis label
+        "x": alt.X("x", axis=None, type="ordinal"),
+        # no y-axis label
+        "y": alt.Y("y", axis=None, type="ordinal"),
+        "tooltip": [
+            alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
+            for key, value in all_agent_data[0].items()
+            if key not in invalid_tooltips
+        ],
+    }
+    has_color = "color" in all_agent_data[0]
+    if has_color:
+        encoding_dict["color"] = alt.Color("color", type="nominal")
+    has_size = "size" in all_agent_data[0]
+    if has_size:
+        encoding_dict["size"] = alt.Size("size", type="quantitative")
+
+    chart = (
+        alt.Chart(
+            alt.Data(values=all_agent_data), encoding=alt.Encoding(**encoding_dict)
+        )
+        .mark_point(filled=True)
+        .properties(width=280, height=280)
+        # .configure_view(strokeOpacity=0)  # hide grid/chart lines
+    )
+    # This is the default value for the marker size, which auto-scales
+    # according to the grid area.
+    if not has_size:
+        length = min(space.width, space.height)
+        chart = chart.mark_point(size=30000 / length**2, filled=True)
+
+    return chart

mesa/experimental/components/matplotlib.py

@@ -0,0 +1,242 @@
+"""Support for using matplotlib to draw spaces."""
+
+from collections import defaultdict
+
+import networkx as nx
+import solara
+from matplotlib.figure import Figure
+from matplotlib.ticker import MaxNLocator
+
+import mesa
+from mesa.experimental.cell_space import VoronoiGrid
+
+
+@solara.component
+def SpaceMatplotlib(model, agent_portrayal, dependencies: list[any] | None = None):
+    """A component for rendering a space using Matplotlib.
+
+    Args:
+        model: a model instance
+        agent_portrayal: a specification of how to portray an agent.
+        dependencies: list of dependencies.
+
+    """
+    space_fig = Figure()
+    space_ax = space_fig.subplots()
+    space = getattr(model, "grid", None)
+    if space is None:
+        # Sometimes the space is defined as model.space instead of model.grid
+        space = model.space
+    if isinstance(space, mesa.space.NetworkGrid):
+        _draw_network_grid(space, space_ax, agent_portrayal)
+    elif isinstance(space, mesa.space.ContinuousSpace):
+        _draw_continuous_space(space, space_ax, agent_portrayal)
+    elif isinstance(space, VoronoiGrid):
+        _draw_voronoi(space, space_ax, agent_portrayal)
+    else:
+        _draw_grid(space, space_ax, agent_portrayal)
+    solara.FigureMatplotlib(space_fig, format="png", dependencies=dependencies)
+
+
+# matplotlib scatter does not allow for multiple shapes in one call
+def _split_and_scatter(portray_data, space_ax):
+    grouped_data = defaultdict(lambda: {"x": [], "y": [], "s": [], "c": []})
+
+    # Extract data from the dictionary
+    x = portray_data["x"]
+    y = portray_data["y"]
+    s = portray_data["s"]
+    c = portray_data["c"]
+    m = portray_data["m"]
+
+    if not (len(x) == len(y) == len(s) == len(c) == len(m)):
+        raise ValueError(
+            "Length mismatch in portrayal data lists: "
+            f"x: {len(x)}, y: {len(y)}, size: {len(s)}, "
+            f"color: {len(c)}, marker: {len(m)}"
+        )
+
+    # Group the data by marker
+    for i in range(len(x)):
+        marker = m[i]
+        grouped_data[marker]["x"].append(x[i])
+        grouped_data[marker]["y"].append(y[i])
+        grouped_data[marker]["s"].append(s[i])
+        grouped_data[marker]["c"].append(c[i])
+
+    # Plot each group with the same marker
+    for marker, data in grouped_data.items():
+        space_ax.scatter(data["x"], data["y"], s=data["s"], c=data["c"], marker=marker)
+
+
+def _draw_grid(space, space_ax, agent_portrayal):
+    def portray(g):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+        m = []  # shape
+        for i in range(g.width):
+            for j in range(g.height):
+                content = g._grid[i][j]
+                if not content:
+                    continue
+                if not hasattr(content, "__iter__"):
+                    # Is a single grid
+                    content = [content]
+                for agent in content:
+                    data = agent_portrayal(agent)
+                    x.append(i)
+                    y.append(j)
+
+                    # This is the default value for the marker size, which auto-scales
+                    # according to the grid area.
+                    default_size = (180 / max(g.width, g.height)) ** 2
+                    # establishing a default prevents misalignment if some agents are not given size, color, etc.
+                    size = data.get("size", default_size)
+                    s.append(size)
+                    color = data.get("color", "tab:blue")
+                    c.append(color)
+                    mark = data.get("shape", "o")
+                    m.append(mark)
+        out = {"x": x, "y": y, "s": s, "c": c, "m": m}
+        return out
+
+    space_ax.set_xlim(-1, space.width)
+    space_ax.set_ylim(-1, space.height)
+    _split_and_scatter(portray(space), space_ax)
+
+
+def _draw_network_grid(space, space_ax, agent_portrayal):
+    graph = space.G
+    pos = nx.spring_layout(graph, seed=0)
+    nx.draw(
+        graph,
+        ax=space_ax,
+        pos=pos,
+        **agent_portrayal(graph),
+    )
+
+
+def _draw_continuous_space(space, space_ax, agent_portrayal):
+    def portray(space):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+        m = []  # shape
+        for agent in space._agent_to_index:
+            data = agent_portrayal(agent)
+            _x, _y = agent.pos
+            x.append(_x)
+            y.append(_y)
+
+            # This is matplotlib's default marker size
+            default_size = 20
+            # establishing a default prevents misalignment if some agents are not given size, color, etc.
+            size = data.get("size", default_size)
+            s.append(size)
+            color = data.get("color", "tab:blue")
+            c.append(color)
+            mark = data.get("shape", "o")
+            m.append(mark)
+        out = {"x": x, "y": y, "s": s, "c": c, "m": m}
+        return out
+
+    # Determine border style based on space.torus
+    border_style = "solid" if not space.torus else (0, (5, 10))
+
+    # Set the border of the plot
+    for spine in space_ax.spines.values():
+        spine.set_linewidth(1.5)
+        spine.set_color("black")
+        spine.set_linestyle(border_style)
+
+    width = space.x_max - space.x_min
+    x_padding = width / 20
+    height = space.y_max - space.y_min
+    y_padding = height / 20
+    space_ax.set_xlim(space.x_min - x_padding, space.x_max + x_padding)
+    space_ax.set_ylim(space.y_min - y_padding, space.y_max + y_padding)
+
+    # Portray and scatter the agents in the space
+    _split_and_scatter(portray(space), space_ax)
+
+
+def _draw_voronoi(space, space_ax, agent_portrayal):
+    def portray(g):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+
+        for cell in g.all_cells:
+            for agent in cell.agents:
+                data = agent_portrayal(agent)
+                x.append(cell.coordinate[0])
+                y.append(cell.coordinate[1])
+                if "size" in data:
+                    s.append(data["size"])
+                if "color" in data:
+                    c.append(data["color"])
+        out = {"x": x, "y": y}
+        # This is the default value for the marker size, which auto-scales
+        # according to the grid area.
+        out["s"] = s
+        if len(c) > 0:
+            out["c"] = c
+
+        return out
+
+    x_list = [i[0] for i in space.centroids_coordinates]
+    y_list = [i[1] for i in space.centroids_coordinates]
+    x_max = max(x_list)
+    x_min = min(x_list)
+    y_max = max(y_list)
+    y_min = min(y_list)
+
+    width = x_max - x_min
+    x_padding = width / 20
+    height = y_max - y_min
+    y_padding = height / 20
+    space_ax.set_xlim(x_min - x_padding, x_max + x_padding)
+    space_ax.set_ylim(y_min - y_padding, y_max + y_padding)
+    space_ax.scatter(**portray(space))
+
+    for cell in space.all_cells:
+        polygon = cell.properties["polygon"]
+        space_ax.fill(
+            *zip(*polygon),
+            alpha=min(1, cell.properties[space.cell_coloring_property]),
+            c="red",
+        )  # Plot filled polygon
+        space_ax.plot(*zip(*polygon), color="black")  # Plot polygon edges in red
+
+
+@solara.component
+def PlotMatplotlib(model, measure, dependencies: list[any] | None = None):
+    """A solara component for creating a matplotlib figure.
+
+    Args:
+        model: Model instance
+        measure: measure to plot
+        dependencies: list of additional dependencies
+
+    """
+    fig = Figure()
+    ax = fig.subplots()
+    df = model.datacollector.get_model_vars_dataframe()
+    if isinstance(measure, str):
+        ax.plot(df.loc[:, measure])
+        ax.set_ylabel(measure)
+    elif isinstance(measure, dict):
+        for m, color in measure.items():
+            ax.plot(df.loc[:, m], label=m, color=color)
+        fig.legend()
+    elif isinstance(measure, list | tuple):
+        for m in measure:
+            ax.plot(df.loc[:, m], label=m)
+        fig.legend()
+    # Set integer x axis
+    ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+    solara.FigureMatplotlib(fig, dependencies=dependencies)

mesa/experimental/devs/__init__.py

@@ -1,24 +1,6 @@
-"""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.
-"""
+"""Support for event scheduling."""
 
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator
 
-__all__ = ["ABMSimulator", "DEVSimulator", "Priority", "SimulationEvent"]
+__all__ = ["ABMSimulator", "DEVSimulator", "SimulationEvent", "Priority"]

mesa/experimental/devs/eventlist.py

@@ -1,22 +1,4 @@
-"""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.
-"""
+"""Eventlist which is at the core of event scheduling."""
 
 from __future__ import annotations