Mesa 3.0.0a4__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

@@ -1,3 +1,5 @@
+"""Altair components."""
+
 import contextlib
 
 import solara
@@ -8,6 +10,14 @@ with contextlib.suppress(ImportError):
 
 @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

mesa/experimental/components/matplotlib.py

@@ -1,3 +1,5 @@
+"""Support for using matplotlib to draw spaces."""
+
 from collections import defaultdict
 
 import networkx as nx
@@ -11,6 +13,14 @@ 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)
@@ -205,6 +215,14 @@ def _draw_voronoi(space, space_ax, agent_portrayal):
 
 @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()

mesa/experimental/devs/__init__.py

@@ -1,3 +1,5 @@
+"""Support for event scheduling."""
+
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator
 

mesa/experimental/devs/eventlist.py

@@ -1,3 +1,5 @@
+"""Eventlist which is at the core of event scheduling."""
+
 from __future__ import annotations
 
 import itertools
@@ -10,15 +12,17 @@ from weakref import WeakMethod, ref
 
 
 class Priority(IntEnum):
+    """Enumeration of priority levels."""
+
     LOW = 10
     DEFAULT = 5
     HIGH = 1
 
 
 class SimulationEvent:
-    """A simulation event
+    """A simulation event.
 
-    the callable is wrapped using weakref, so there is no need to explicitly cancel event if e.g., an agent
+    The callable is wrapped using weakref, so there is no need to explicitly cancel event if e.g., an agent
     is removed from the simulation.
 
     Attributes:
@@ -34,7 +38,7 @@ class SimulationEvent:
     _ids = itertools.count()
 
     @property
-    def CANCELED(self) -> bool:
+    def CANCELED(self) -> bool:  # noqa: D102
         return self._canceled
 
     def __init__(
@@ -45,6 +49,15 @@ class SimulationEvent:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> None:
+        """Initialize a simulation event.
+
+        Args:
+            time: the instant of time of the simulation event
+            function: the callable to invoke
+            priority: the priority of the event
+            function_args: arguments for callable
+            function_kwargs: keyword arguments for the callable
+        """
         super().__init__()
         if not callable(function):
             raise Exception()
@@ -64,20 +77,20 @@ class SimulationEvent:
         self.function_kwargs = function_kwargs if function_kwargs else {}
 
     def execute(self):
-        """execute this event"""
+        """Execute this event."""
         if not self._canceled:
             fn = self.fn()
             if fn is not None:
                 fn(*self.function_args, **self.function_kwargs)
 
     def cancel(self) -> None:
-        """cancel this event"""
+        """Cancel this event."""
         self._canceled = True
         self.fn = None
         self.function_args = []
         self.function_kwargs = {}
 
-    def __lt__(self, other):
+    def __lt__(self, other):  # noqa
         # Define a total ordering for events to be used by the heapq
         return (self.time, self.priority, self.unique_id) < (
             other.time,
@@ -87,30 +100,31 @@ class SimulationEvent:
 
 
 class EventList:
-    """An event list
+    """An event list.
 
     This is a heap queue sorted list of events. Events are always removed from the left, so heapq is a performant and
     appropriate data structure. Events are sorted based on their time stamp, their priority, and their unique_id
     as a tie-breaker, guaranteeing a complete ordering.
 
+
     """
 
     def __init__(self):
+        """Initialize an event list."""
         self._events: list[SimulationEvent] = []
         heapify(self._events)
 
     def add_event(self, event: SimulationEvent):
-        """Add the event to the event list
+        """Add the event to the event list.
 
         Args:
             event (SimulationEvent): The event to be added
 
         """
-
         heappush(self._events, event)
 
     def peak_ahead(self, n: int = 1) -> list[SimulationEvent]:
-        """Look at the first n non-canceled event in the event list
+        """Look at the first n non-canceled event in the event list.
 
         Args:
             n (int): The number of events to look ahead
@@ -139,7 +153,7 @@ class EventList:
         return peek
 
     def pop_event(self) -> SimulationEvent:
-        """pop the first element from the event list"""
+        """Pop the first element from the event list."""
         while self._events:
             event = heappop(self._events)
             if not event.CANCELED:
@@ -147,16 +161,17 @@ class EventList:
         raise IndexError("Event list is empty")
 
     def is_empty(self) -> bool:
+        """Return whether the event list is empty."""
         return len(self) == 0
 
-    def __contains__(self, event: SimulationEvent) -> bool:
+    def __contains__(self, event: SimulationEvent) -> bool:  # noqa
         return event in self._events
 
-    def __len__(self) -> int:
+    def __len__(self) -> int:  # noqa
         return len(self._events)
 
     def __repr__(self) -> str:
-        """Return a string representation of the event list"""
+        """Return a string representation of the event list."""
         events_str = ", ".join(
             [
                 f"Event(time={e.time}, priority={e.priority}, id={e.unique_id})"
@@ -167,7 +182,12 @@ class EventList:
         return f"EventList([{events_str}])"
 
     def remove(self, event: SimulationEvent) -> None:
-        """remove an event from the event list"""
+        """Remove an event from the event list.
+
+        Args:
+            event (SimulationEvent): The event to be removed
+
+        """
         # we cannot simply remove items from _eventlist because this breaks
         # heap structure invariant. So, we use a form of lazy deletion.
         # SimEvents have a CANCELED flag that we set to True, while popping and peak_ahead
@@ -175,4 +195,5 @@ class EventList:
         event.cancel()
 
     def clear(self):
+        """Clear the event list."""
         self._events.clear()