Mesa 3.0.0a3__py3-none-any.whl → 3.0.0a5__py3-none-any.whl

mesa/experimental/cell_space/discrete_space.py

@@ -1,3 +1,5 @@
+"""DiscreteSpace base class."""
+
 from __future__ import annotations
 
 from functools import cached_property
@@ -28,6 +30,13 @@ class DiscreteSpace(Generic[T]):
         cell_klass: type[T] = Cell,
         random: Random | None = None,
     ):
+        """Instantiate a DiscreteSpace.
+
+        Args:
+            capacity: capacity of cells
+            cell_klass: base class for all cells
+            random: random number generator
+        """
         super().__init__()
         self.capacity = capacity
         self._cells: dict[tuple[int, ...], T] = {}
@@ -40,25 +49,27 @@ class DiscreteSpace(Generic[T]):
         self._empties_initialized = False
 
     @property
-    def cutoff_empties(self):
+    def cutoff_empties(self):  # noqa
         return 7.953 * len(self._cells) ** 0.384
 
     def _connect_single_cell(self, cell: T): ...
 
     @cached_property
     def all_cells(self):
+        """Return all cells in space."""
         return CellCollection({cell: cell.agents for cell in self._cells.values()})
 
-    def __iter__(self):
+    def __iter__(self):  # noqa
         return iter(self._cells.values())
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: tuple[int, ...]) -> T:  # noqa: D105
         return self._cells[key]
 
     @property
-    def empties(self) -> CellCollection:
+    def empties(self) -> CellCollection[T]:
+        """Return all empty in spaces."""
         return self.all_cells.select(lambda cell: cell.is_empty)
 
     def select_random_empty_cell(self) -> T:
-        """select random empty cell"""
+        """Select random empty cell."""
         return self.random.choice(list(self.empties))

mesa/experimental/cell_space/grid.py

@@ -1,3 +1,5 @@
+"""Various Grid Spaces."""
+
 from __future__ import annotations
 
 from collections.abc import Sequence
@@ -10,8 +12,8 @@ from mesa.experimental.cell_space import Cell, DiscreteSpace
 T = TypeVar("T", bound=Cell)
 
 
-class Grid(DiscreteSpace, Generic[T]):
-    """Base class for all grid classes
+class Grid(DiscreteSpace[T], Generic[T]):
+    """Base class for all grid classes.
 
     Attributes:
         dimensions (Sequence[int]): the dimensions of the grid
@@ -30,6 +32,15 @@ class Grid(DiscreteSpace, Generic[T]):
         random: Random | None = None,
         cell_klass: type[T] = Cell,
     ) -> None:
+        """Initialise the grid class.
+
+        Args:
+            dimensions: the dimensions of the space
+            torus: whether the space wraps
+            capacity: capacity of the grid cell
+            random: a random number generator
+            cell_klass: the base class to use for the cells
+        """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
         self.torus = torus
         self.dimensions = dimensions
@@ -63,7 +74,7 @@ class Grid(DiscreteSpace, Generic[T]):
         if self.capacity is not None and not isinstance(self.capacity, float | int):
             raise ValueError("Capacity must be a number or None.")
 
-    def select_random_empty_cell(self) -> T:
+    def select_random_empty_cell(self) -> T:  # noqa
         # FIXME:: currently just a simple boolean to control behavior
         # FIXME:: basically if grid is close to 99% full, creating empty list can be faster
         # FIXME:: note however that the old results don't apply because in this implementation
@@ -89,7 +100,7 @@ class Grid(DiscreteSpace, Generic[T]):
             if self.torus:
                 n_coord = tuple(nc % d for nc, d in zip(n_coord, self.dimensions))
             if all(0 <= nc < d for nc, d in zip(n_coord, self.dimensions)):
-                cell.connect(self._cells[n_coord])
+                cell.connect(self._cells[n_coord], d_coord)
 
     def _connect_single_cell_2d(self, cell: T, offsets: list[tuple[int, int]]) -> None:
         i, j = cell.coordinate
@@ -100,7 +111,7 @@ class Grid(DiscreteSpace, Generic[T]):
             if self.torus:
                 ni, nj = ni % height, nj % width
             if 0 <= ni < height and 0 <= nj < width:
-                cell.connect(self._cells[ni, nj])
+                cell.connect(self._cells[ni, nj], (di, dj))
 
 
 class OrthogonalMooreGrid(Grid[T]):
@@ -122,7 +133,6 @@ class OrthogonalMooreGrid(Grid[T]):
             ( 1, -1), ( 1, 0), ( 1, 1),
         ]
         # fmt: on
-        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
@@ -154,13 +164,12 @@ class OrthogonalVonNeumannGrid(Grid[T]):
                     ( 1, 0),
         ]
         # fmt: on
-        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
 
     def _connect_cells_nd(self) -> None:
-        offsets = []
+        offsets: list[tuple[int, ...]] = []
         dimensions = len(self.dimensions)
         for dim in range(dimensions):
             for delta in [
@@ -176,6 +185,8 @@ class OrthogonalVonNeumannGrid(Grid[T]):
 
 
 class HexGrid(Grid[T]):
+    """A Grid with hexagonal tilling of the space."""
+
     def _connect_cells_2d(self) -> None:
         # fmt: off
         even_offsets = [

mesa/experimental/cell_space/network.py

@@ -1,3 +1,5 @@
+"""A Network grid."""
+
 from random import Random
 from typing import Any
 
@@ -5,8 +7,8 @@ from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 
 
-class Network(DiscreteSpace):
-    """A networked discrete space"""
+class Network(DiscreteSpace[Cell]):
+    """A networked discrete space."""
 
     def __init__(
         self,
@@ -15,13 +17,13 @@ class Network(DiscreteSpace):
         random: Random | None = None,
         cell_klass: type[Cell] = Cell,
     ) -> None:
-        """A Networked grid
+        """A Networked grid.
 
         Args:
             G: a NetworkX Graph instance.
             capacity (int) : the capacity of the cell
-            random (Random):
-            CellKlass (type[Cell]): The base Cell class to use in the Network
+            random (Random): a random number generator
+            cell_klass (type[Cell]): The base Cell class to use in the Network
 
         """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
@@ -35,6 +37,6 @@ class Network(DiscreteSpace):
         for cell in self.all_cells:
             self._connect_single_cell(cell)
 
-    def _connect_single_cell(self, cell):
+    def _connect_single_cell(self, cell: Cell):
         for node_id in self.G.neighbors(cell.coordinate):
-            cell.connect(self._cells[node_id])
+            cell.connect(self._cells[node_id], node_id)

mesa/experimental/cell_space/voronoi.py

@@ -1,3 +1,5 @@
+"""Support for Voronoi meshed grids."""
+
 from collections.abc import Sequence
 from itertools import combinations
 from random import Random
@@ -9,16 +11,17 @@ from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 
 
 class Delaunay:
-    """
-    Class to compute a Delaunay triangulation in 2D
+    """Class to compute a Delaunay triangulation in 2D.
+
     ref: http://github.com/jmespadero/pyDelaunay2D
     """
 
     def __init__(self, center: tuple = (0, 0), radius: int = 9999) -> None:
-        """
-        Init and create a new frame to contain the triangulation
-        center: Optional position for the center of the frame. Default (0,0)
-        radius: Optional distance from corners to the center.
+        """Init and create a new frame to contain the triangulation.
+
+        Args:
+            center: Optional position for the center of the frame. Default (0,0)
+            radius: Optional distance from corners to the center.
         """
         center = np.asarray(center)
         # Create coordinates for the corners of the frame
@@ -44,9 +47,7 @@ class Delaunay:
             self.circles[t] = self._circumcenter(t)
 
     def _circumcenter(self, triangle: list) -> tuple:
-        """
-        Compute circumcenter and circumradius of a triangle in 2D.
-        """
+        """Compute circumcenter and circumradius of a triangle in 2D."""
         points = np.asarray([self.coords[v] for v in triangle])
         points2 = np.dot(points, points.T)
         a = np.bmat([[2 * points2, [[1], [1], [1]]], [[[1, 1, 1, 0]]]])
@@ -60,16 +61,12 @@ class Delaunay:
         return (center, radius)
 
     def _in_circle(self, triangle: list, point: list) -> bool:
-        """
-        Check if point p is inside of precomputed circumcircle of triangle.
-        """
+        """Check if point p is inside of precomputed circumcircle of triangle."""
         center, radius = self.circles[triangle]
         return np.sum(np.square(center - point)) <= radius
 
     def add_point(self, point: Sequence) -> None:
-        """
-        Add a point to the current DT, and refine it using Bowyer-Watson.
-        """
+        """Add a point to the current DT, and refine it using Bowyer-Watson."""
         point_index = len(self.coords)
         self.coords.append(np.asarray(point))
 
@@ -121,9 +118,7 @@ class Delaunay:
             self.triangles[triangle][2] = new_triangles[(i - 1) % n]  # previous
 
     def export_triangles(self) -> list:
-        """
-        Export the current list of Delaunay triangles
-        """
+        """Export the current list of Delaunay triangles."""
         triangles_list = [
             (a - 4, b - 4, c - 4)
             for (a, b, c) in self.triangles
@@ -132,9 +127,7 @@ class Delaunay:
         return triangles_list
 
     def export_voronoi_regions(self):
-        """
-        Export coordinates and regions of Voronoi diagram as indexed data.
-        """
+        """Export coordinates and regions of Voronoi diagram as indexed data."""
         use_vertex = {i: [] for i in range(len(self.coords))}
         vor_coors = []
         index = {}
@@ -163,11 +156,13 @@ class Delaunay:
         return vor_coors, regions
 
 
-def round_float(x: float) -> int:
+def round_float(x: float) -> int:  # noqa
     return int(x * 500)
 
 
 class VoronoiGrid(DiscreteSpace):
+    """Voronoi meshed GridSpace."""
+
     triangulation: Delaunay
     voronoi_coordinates: list
     regions: list
@@ -181,8 +176,7 @@ class VoronoiGrid(DiscreteSpace):
         capacity_function: callable = round_float,
         cell_coloring_property: str | None = None,
     ) -> None:
-        """
-        A Voronoi Tessellation Grid.
+        """A Voronoi Tessellation Grid.
 
         Given a set of points, this class creates a grid where a cell is centered in each point,
         its neighbors are given by Voronoi Tessellation cells neighbors
@@ -192,7 +186,7 @@ class VoronoiGrid(DiscreteSpace):
             centroids_coordinates: coordinates of centroids to build the tessellation space
             capacity (int) : capacity of the cells in the discrete space
             random (Random): random number generator
-            CellKlass (type[Cell]): type of cell class
+            cell_klass (type[Cell]): type of cell class
             capacity_function (Callable): function to compute (int) capacity according to (float) area
             cell_coloring_property (str): voronoi visualization polygon fill property
         """
@@ -215,17 +209,15 @@ class VoronoiGrid(DiscreteSpace):
         self._build_cell_polygons()
 
     def _connect_cells(self) -> None:
-        """
-        Connect cells to neighbors based on given centroids and using Delaunay Triangulation
-        """
+        """Connect cells to neighbors based on given centroids and using Delaunay Triangulation."""
         self.triangulation = Delaunay()
         for centroid in self.centroids_coordinates:
             self.triangulation.add_point(centroid)
 
         for point in self.triangulation.export_triangles():
             for i, j in combinations(point, 2):
-                self._cells[i].connect(self._cells[j])
-                self._cells[j].connect(self._cells[i])
+                self._cells[i].connect(self._cells[j], (i, j))
+                self._cells[j].connect(self._cells[i], (j, i))
 
     def _validate_parameters(self) -> None:
         if self.capacity is not None and not isinstance(self.capacity, float | int):
@@ -241,9 +233,10 @@ class VoronoiGrid(DiscreteSpace):
 
     def _get_voronoi_regions(self) -> tuple:
         if self.voronoi_coordinates is None or self.regions is None:
-            self.voronoi_coordinates, self.regions = (
-                self.triangulation.export_voronoi_regions()
-            )
+            (
+                self.voronoi_coordinates,
+                self.regions,
+            ) = self.triangulation.export_voronoi_regions()
         return self.voronoi_coordinates, self.regions
 
     @staticmethod

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,3 +1,5 @@
+"""Support for event scheduling."""
+
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator