Mesa 2.2.4__py3-none-any.whl → 2.3.0__py3-none-any.whl

mesa/experimental/cell_space/grid.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from itertools import product
+from random import Random
+from typing import Generic, TypeVar
+
+from mesa.experimental.cell_space import Cell, DiscreteSpace
+
+T = TypeVar("T", bound=Cell)
+
+
+class Grid(DiscreteSpace, Generic[T]):
+    """Base class for all grid classes
+
+    Attributes:
+        dimensions (Sequence[int]): the dimensions of the grid
+        torus (bool): whether the grid is a torus
+        capacity (int): the capacity of a grid cell
+        random (Random): the random number generator
+        _try_random (bool): whether to get empty cell be repeatedly trying random cell
+
+    """
+
+    def __init__(
+        self,
+        dimensions: Sequence[int],
+        torus: bool = False,
+        capacity: float | None = None,
+        random: Random | None = None,
+        cell_klass: type[T] = Cell,
+    ) -> None:
+        super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
+        self.torus = torus
+        self.dimensions = dimensions
+        self._try_random = True
+        self._ndims = len(dimensions)
+        self._validate_parameters()
+
+        coordinates = product(*(range(dim) for dim in self.dimensions))
+
+        self._cells = {
+            coord: cell_klass(coord, capacity, random=self.random)
+            for coord in coordinates
+        }
+        self._connect_cells()
+
+    def _connect_cells(self) -> None:
+        if self._ndims == 2:
+            self._connect_cells_2d()
+        else:
+            self._connect_cells_nd()
+
+    def _connect_cells_2d(self) -> None: ...
+
+    def _connect_cells_nd(self) -> None: ...
+
+    def _validate_parameters(self):
+        if not all(isinstance(dim, int) and dim > 0 for dim in self.dimensions):
+            raise ValueError("Dimensions must be a list of positive integers.")
+        if not isinstance(self.torus, bool):
+            raise ValueError("Torus must be a boolean.")
+        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:
+        # 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
+        # FIXME:: because empties list needs to be rebuild each time
+        # This method is based on Agents.jl's random_empty() implementation. See
+        # https://github.com/JuliaDynamics/Agents.jl/pull/541. For the discussion, see
+        # https://github.com/projectmesa/mesa/issues/1052 and
+        # https://github.com/projectmesa/mesa/pull/1565. The cutoff value provided
+        # is the break-even comparison with the time taken in the else branching point.
+        if self._try_random:
+            while True:
+                cell = self.all_cells.select_random_cell()
+                if cell.is_empty:
+                    return cell
+        else:
+            return super().select_random_empty_cell()
+
+    def _connect_single_cell_nd(self, cell: T, offsets: list[tuple[int, ...]]) -> None:
+        coord = cell.coordinate
+
+        for d_coord in offsets:
+            n_coord = tuple(c + dc for c, dc in zip(coord, d_coord))
+            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])
+
+    def _connect_single_cell_2d(self, cell: T, offsets: list[tuple[int, int]]) -> None:
+        i, j = cell.coordinate
+        height, width = self.dimensions
+
+        for di, dj in offsets:
+            ni, nj = (i + di, j + dj)
+            if self.torus:
+                ni, nj = ni % height, nj % width
+            if 0 <= ni < height and 0 <= nj < width:
+                cell.connect(self._cells[ni, nj])
+
+
+class OrthogonalMooreGrid(Grid[T]):
+    """Grid where cells are connected to their 8 neighbors.
+
+    Example for two dimensions:
+    directions = [
+        (-1, -1), (-1, 0), (-1, 1),
+        ( 0, -1),          ( 0, 1),
+        ( 1, -1), ( 1, 0), ( 1, 1),
+    ]
+    """
+
+    def _connect_cells_2d(self) -> None:
+        # fmt: off
+        offsets = [
+            (-1, -1), (-1, 0), (-1, 1),
+            ( 0, -1),          ( 0, 1),
+            ( 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)
+
+    def _connect_cells_nd(self) -> None:
+        offsets = list(product([-1, 0, 1], repeat=len(self.dimensions)))
+        offsets.remove((0,) * len(self.dimensions))  # Remove the central cell
+
+        for cell in self.all_cells:
+            self._connect_single_cell_nd(cell, offsets)
+
+
+class OrthogonalVonNeumannGrid(Grid[T]):
+    """Grid where cells are connected to their 4 neighbors.
+
+    Example for two dimensions:
+    directions = [
+                (0, -1),
+        (-1, 0),         ( 1, 0),
+                (0,  1),
+    ]
+    """
+
+    def _connect_cells_2d(self) -> None:
+        # fmt: off
+        offsets = [
+                    (-1, 0),
+            (0, -1),         (0, 1),
+                    ( 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 = []
+        dimensions = len(self.dimensions)
+        for dim in range(dimensions):
+            for delta in [
+                -1,
+                1,
+            ]:  # Move one step in each direction for the current dimension
+                offset = [0] * dimensions
+                offset[dim] = delta
+                offsets.append(tuple(offset))
+
+        for cell in self.all_cells:
+            self._connect_single_cell_nd(cell, offsets)
+
+
+class HexGrid(Grid[T]):
+    def _connect_cells_2d(self) -> None:
+        # fmt: off
+        even_offsets = [
+                        (-1, -1), (-1, 0),
+                    ( 0, -1),        ( 0, 1),
+                        ( 1, -1), ( 1, 0),
+                ]
+        odd_offsets = [
+                        (-1, 0), (-1, 1),
+                    ( 0, -1),       ( 0, 1),
+                        ( 1, 0), ( 1, 1),
+                ]
+        # fmt: on
+
+        for cell in self.all_cells:
+            i = cell.coordinate[0]
+            offsets = even_offsets if i % 2 == 0 else odd_offsets
+            self._connect_single_cell_2d(cell, offsets=offsets)
+
+    def _connect_cells_nd(self) -> None:
+        raise NotImplementedError("HexGrids are only defined for 2 dimensions")
+
+    def _validate_parameters(self):
+        super()._validate_parameters()
+        if len(self.dimensions) != 2:
+            raise ValueError("HexGrid must have exactly 2 dimensions.")

mesa/experimental/cell_space/network.py

@@ -0,0 +1,40 @@
+from random import Random
+from typing import Any, Optional
+
+from mesa.experimental.cell_space.cell import Cell
+from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+
+
+class Network(DiscreteSpace):
+    """A networked discrete space"""
+
+    def __init__(
+        self,
+        G: Any,  # noqa: N803
+        capacity: Optional[int] = None,
+        random: Optional[Random] = None,
+        cell_klass: type[Cell] = Cell,
+    ) -> None:
+        """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
+
+        """
+        super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
+        self.G = G
+
+        for node_id in self.G.nodes:
+            self._cells[node_id] = self.cell_klass(
+                node_id, capacity, random=self.random
+            )
+
+        for cell in self.all_cells:
+            self._connect_single_cell(cell)
+
+    def _connect_single_cell(self, cell):
+        for node_id in self.G.neighbors(cell.coordinate):
+            cell.connect(self._cells[node_id])

mesa/experimental/components/altair.py

@@ -0,0 +1,72 @@
+import contextlib
+from typing import Optional
+
+import solara
+
+with contextlib.suppress(ImportError):
+    import altair as alt
+
+
+@solara.component
+def SpaceAltair(model, agent_portrayal, dependencies: Optional[list[any]] = None):
+    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

@@ -48,6 +48,9 @@ def _draw_grid(space, space_ax, agent_portrayal):
                     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"] = (180 / min(g.width, g.height)) ** 2
         if len(s) > 0:
             out["s"] = s
         if len(c) > 0:
@@ -112,7 +115,8 @@ def _draw_continuous_space(space, space_ax, agent_portrayal):
     space_ax.scatter(**portray(space))
 
 
-def make_plot(model, measure):
+@solara.component
+def PlotMatplotlib(model, measure, dependencies: Optional[list[any]] = None):
     fig = Figure()
     ax = fig.subplots()
     df = model.datacollector.get_model_vars_dataframe()
@@ -129,4 +133,4 @@ def make_plot(model, measure):
         fig.legend()
     # Set integer x axis
     ax.xaxis.set_major_locator(MaxNLocator(integer=True))
-    solara.FigureMatplotlib(fig)
+    solara.FigureMatplotlib(fig, dependencies=dependencies)

mesa/experimental/devs/__init__.py

@@ -0,0 +1,4 @@
+from .eventlist import Priority, SimulationEvent
+from .simulator import ABMSimulator, DEVSimulator
+
+__all__ = ["ABMSimulator", "DEVSimulator", "SimulationEvent", "Priority"]

mesa/experimental/devs/eventlist.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import itertools
+from enum import IntEnum
+from heapq import heapify, heappop, heappush
+from types import MethodType
+from typing import Any, Callable
+from weakref import WeakMethod, ref
+
+
+class Priority(IntEnum):
+    LOW = 10
+    DEFAULT = 5
+    HIGH = 1
+
+
+class SimulationEvent:
+    """A simulation event
+
+    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:
+        time (float): The simulation time of the event
+        fn (Callable): The function to execute for this event
+        priority (Priority): The priority of the event
+        unique_id (int) the unique identifier of the event
+        function_args (list[Any]): Argument for the function
+        function_kwargs (Dict[str, Any]): Keyword arguments for the function
+
+    """
+
+    _ids = itertools.count()
+
+    @property
+    def CANCELED(self) -> bool:
+        return self._canceled
+
+    def __init__(
+        self,
+        time: int | float,
+        function: Callable,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__()
+        if not callable(function):
+            raise Exception()
+
+        self.time = time
+        self.priority = priority.value
+        self._canceled = False
+
+        if isinstance(function, MethodType):
+            function = WeakMethod(function)
+        else:
+            function = ref(function)
+
+        self.fn = function
+        self.unique_id = next(self._ids)
+        self.function_args = function_args if function_args else []
+        self.function_kwargs = function_kwargs if function_kwargs else {}
+
+    def execute(self):
+        """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"""
+        self._canceled = True
+        self.fn = None
+        self.function_args = []
+        self.function_kwargs = {}
+
+    def __lt__(self, other):
+        # Define a total ordering for events to be used by the heapq
+        return (self.time, self.priority, self.unique_id) < (
+            other.time,
+            other.priority,
+            other.unique_id,
+        )
+
+
+class EventList:
+    """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):
+        self._events: list[SimulationEvent] = []
+        heapify(self._events)
+
+    def add_event(self, event: SimulationEvent):
+        """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
+
+        Args:
+            n (int): The number of events to look ahead
+
+        Returns:
+            list[SimulationEvent]
+
+        Raises:
+            IndexError: If the eventlist is empty
+
+        Notes:
+            this method can return a list shorted then n if the number of non-canceled events on the event list
+            is less than n.
+
+        """
+        # look n events ahead
+        if self.is_empty():
+            raise IndexError("event list is empty")
+
+        peek: list[SimulationEvent] = []
+        for event in self._events:
+            if not event.CANCELED:
+                peek.append(event)
+            if len(peek) >= n:
+                return peek
+        return peek
+
+    def pop_event(self) -> SimulationEvent:
+        """pop the first element from the event list"""
+        while self._events:
+            event = heappop(self._events)
+            if not event.CANCELED:
+                return event
+        raise IndexError("Event list is empty")
+
+    def is_empty(self) -> bool:
+        return len(self) == 0
+
+    def __contains__(self, event: SimulationEvent) -> bool:
+        return event in self._events
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def remove(self, event: SimulationEvent) -> None:
+        """remove an event from the event list"""
+        # 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
+        # silently ignore canceled events
+        event.cancel()
+
+    def clear(self):
+        self._events.clear()