Mesa 2.3.0.dev0__py3-none-any.whl → 2.3.0rc1__py3-none-any.whl

mesa/__init__.py

@@ -3,6 +3,7 @@ Mesa Agent-Based Modeling Framework
 
 Core Objects: Model, and Agent.
 """
+
 import datetime
 
 import mesa.space as space
@@ -25,7 +26,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "2.3.0-dev"
+__version__ = "2.3.0-rc1"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -3,6 +3,7 @@ The agent class for Mesa framework.
 
 Core Objects: Agent
 """
+
 # Mypy; for the `|` operator purpose
 # Remove this __future__ import once the oldest supported Python is 3.10
 from __future__ import annotations
@@ -81,12 +82,6 @@ class Agent:
 
 class AgentSet(MutableSet, Sequence):
     """
-    .. warning::
-        The AgentSet is experimental. It may be changed or removed in any and all future releases, including
-        patch releases.
-        We would love to hear what you think about this new feature. If you have any thoughts, share them with
-        us here: https://github.com/projectmesa/mesa/discussions/1919
-
     A collection class that represents an ordered set of agents within an agent-based model (ABM). This class
     extends both MutableSet and Sequence, providing set-like functionality with order preservation and
     sequence operations.
@@ -115,17 +110,8 @@ class AgentSet(MutableSet, Sequence):
             agents (Iterable[Agent]): An iterable of Agent objects to be included in the set.
             model (Model): The ABM model instance to which this AgentSet belongs.
         """
-        self.model = model
-
-        if not self.__class__.agentset_experimental_warning_given:
-            self.__class__.agentset_experimental_warning_given = True
-            warnings.warn(
-                "The AgentSet is experimental. It may be changed or removed in any and all future releases, including patch releases.\n"
-                "We would love to hear what you think about this new feature. If you have any thoughts, share them with us here: https://github.com/projectmesa/mesa/discussions/1919",
-                FutureWarning,
-                stacklevel=2,
-            )
 
+        self.model = model
         self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
 
     def __len__(self) -> int:

mesa/datacollection.py

@@ -32,6 +32,7 @@ The default DataCollector here makes several assumptions:
     * The model has an agent list called agents
     * For collecting agent-level variables, agents must have a unique_id
 """
+
 import contextlib
 import itertools
 import types

mesa/experimental/__init__.py

@@ -1 +1,5 @@
 from .jupyter_viz import JupyterViz, make_text, Slider  # noqa
+from mesa.experimental import cell_space
+
+
+__all__ = ["JupyterViz", "make_text", "Slider", "cell_space"]

mesa/experimental/cell_space/__init__.py

@@ -0,0 +1,23 @@
+from mesa.experimental.cell_space.cell import Cell
+from mesa.experimental.cell_space.cell_agent import CellAgent
+from mesa.experimental.cell_space.cell_collection import CellCollection
+from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+from mesa.experimental.cell_space.grid import (
+    Grid,
+    HexGrid,
+    OrthogonalMooreGrid,
+    OrthogonalVonNeumannGrid,
+)
+from mesa.experimental.cell_space.network import Network
+
+__all__ = [
+    "CellCollection",
+    "Cell",
+    "CellAgent",
+    "DiscreteSpace",
+    "Grid",
+    "HexGrid",
+    "OrthogonalMooreGrid",
+    "OrthogonalVonNeumannGrid",
+    "Network",
+]

mesa/experimental/cell_space/cell.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from functools import cache
+from random import Random
+from typing import TYPE_CHECKING
+
+from mesa.experimental.cell_space.cell_collection import CellCollection
+
+if TYPE_CHECKING:
+    from mesa.experimental.cell_space.cell_agent import CellAgent
+
+
+class Cell:
+    """The cell represents a position in a discrete space.
+
+    Attributes:
+        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",
+        "agents",
+        "capacity",
+        "properties",
+        "random",
+    ]
+
+    # 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: tuple[int, ...],
+        capacity: float | None = None,
+        random: Random | None = None,
+    ) -> None:
+        """ "
+
+        Args:
+            coordinate:
+            capacity (int) : the capacity of the cell. If None, the capacity is infinite
+            random (Random) : the random number generator to use
+
+        """
+        super().__init__()
+        self.coordinate = coordinate
+        self._connections: list[Cell] = []  # TODO: change to CellCollection?
+        self.agents = []  # TODO:: change to AgentSet or weakrefs? (neither is very performant, )
+        self.capacity = capacity
+        self.properties: dict[str, object] = {}
+        self.random = random
+
+    def connect(self, other: Cell) -> None:
+        """Connects this cell to another cell.
+
+        Args:
+            other (Cell): other cell to connect to
+
+        """
+        self._connections.append(other)
+
+    def disconnect(self, other: Cell) -> None:
+        """Disconnects this cell from another cell.
+
+        Args:
+            other (Cell): other cell to remove from connections
+
+        """
+        self._connections.remove(other)
+
+    def add_agent(self, agent: CellAgent) -> None:
+        """Adds an agent to the cell.
+
+        Args:
+            agent (CellAgent): agent to add to this Cell
+
+        """
+        n = len(self.agents)
+
+        if self.capacity and n >= self.capacity:
+            raise Exception(
+                "ERROR: Cell is full"
+            )  # FIXME we need MESA errors or a proper error
+
+        self.agents.append(agent)
+
+    def remove_agent(self, agent: CellAgent) -> None:
+        """Removes an agent from the cell.
+
+        Args:
+            agent (CellAgent): agent to remove from this cell
+
+        """
+        self.agents.remove(agent)
+        agent.cell = None
+
+    @property
+    def is_empty(self) -> bool:
+        """Returns a bool of the contents of a cell."""
+        return len(self.agents) == 0
+
+    @property
+    def is_full(self) -> bool:
+        """Returns a bool of the contents of a cell."""
+        return len(self.agents) == self.capacity
+
+    def __repr__(self):
+        return f"Cell({self.coordinate}, {self.agents})"
+
+    # FIXME: Revisit caching strategy on methods
+    @cache  # noqa: B019
+    def neighborhood(self, radius=1, include_center=False):
+        return CellCollection(
+            self._neighborhood(radius=radius, include_center=include_center),
+            random=self.random,
+        )
+
+    # FIXME: Revisit caching strategy on methods
+    @cache  # noqa: B019
+    def _neighborhood(self, radius=1, include_center=False):
+        # if radius == 0:
+        #     return {self: self.agents}
+        if radius < 1:
+            raise ValueError("radius must be larger than one")
+        if radius == 1:
+            neighborhood = {neighbor: neighbor.agents for neighbor in self._connections}
+            if not include_center:
+                return neighborhood
+            else:
+                neighborhood[self] = self.agents
+                return neighborhood
+        else:
+            neighborhood = {}
+            for neighbor in self._connections:
+                neighborhood.update(
+                    neighbor._neighborhood(radius - 1, include_center=True)
+                )
+            if not include_center:
+                neighborhood.pop(self, None)
+            return neighborhood

mesa/experimental/cell_space/cell_agent.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mesa import Agent, Model
+
+if TYPE_CHECKING:
+    from mesa.experimental.cell_space.cell import Cell
+
+
+class CellAgent(Agent):
+    """Cell Agent is an extension of the Agent class and adds behavior for moving in discrete spaces
+
+
+    Attributes:
+        unique_id (int): A unique identifier for this agent.
+        model (Model): The model instance to which the agent belongs
+        pos: (Position | None): The position of the agent in the space
+        cell: (Cell | None): the cell which the agent occupies
+    """
+
+    def __init__(self, unique_id: int, model: Model) -> None:
+        """
+        Create a new agent.
+
+        Args:
+            unique_id (int): A unique identifier for this agent.
+            model (Model): The model instance in which the agent exists.
+        """
+        super().__init__(unique_id, model)
+        self.cell: Cell | None = None
+
+    def move_to(self, cell) -> None:
+        if self.cell is not None:
+            self.cell.remove_agent(self)
+        self.cell = cell
+        cell.add_agent(self)

mesa/experimental/cell_space/cell_collection.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import itertools
+from collections.abc import Iterable, Mapping
+from functools import cached_property
+from random import Random
+from typing import TYPE_CHECKING, Callable, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from mesa.experimental.cell_space.cell import Cell
+    from mesa.experimental.cell_space.cell_agent import CellAgent
+
+T = TypeVar("T", bound="Cell")
+
+
+class CellCollection(Generic[T]):
+    """An immutable collection of cells
+
+    Attributes:
+        cells (List[Cell]): The list of cells this collection represents
+        agents (List[CellAgent]) : List of agents occupying the cells in this collection
+        random (Random) : The random number generator
+
+    """
+
+    def __init__(
+        self,
+        cells: Mapping[T, list[CellAgent]] | Iterable[T],
+        random: Random | None = None,
+    ) -> None:
+        if isinstance(cells, dict):
+            self._cells = cells
+        else:
+            self._cells = {cell: cell.agents for cell in cells}
+
+        #
+        self._capacity: int = next(iter(self._cells.keys())).capacity
+
+        if random is None:
+            random = Random()  # FIXME
+        self.random = random
+
+    def __iter__(self):
+        return iter(self._cells)
+
+    def __getitem__(self, key: T) -> Iterable[CellAgent]:
+        return self._cells[key]
+
+    # @cached_property
+    def __len__(self) -> int:
+        return len(self._cells)
+
+    def __repr__(self):
+        return f"CellCollection({self._cells})"
+
+    @cached_property
+    def cells(self) -> list[T]:
+        return list(self._cells.keys())
+
+    @property
+    def agents(self) -> Iterable[CellAgent]:
+        return itertools.chain.from_iterable(self._cells.values())
+
+    def select_random_cell(self) -> T:
+        return self.random.choice(self.cells)
+
+    def select_random_agent(self) -> CellAgent:
+        return self.random.choice(list(self.agents))
+
+    def select(self, filter_func: Callable[[T], bool] | None = None, n=0):
+        # FIXME: n is not considered
+        if filter_func is None and n == 0:
+            return self
+
+        return CellCollection(
+            {
+                cell: agents
+                for cell, agents in self._cells.items()
+                if filter_func is None or filter_func(cell)
+            }
+        )

mesa/experimental/cell_space/discrete_space.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from functools import cached_property
+from random import Random
+from typing import Generic, TypeVar
+
+from mesa.experimental.cell_space.cell import Cell
+from mesa.experimental.cell_space.cell_collection import CellCollection
+
+T = TypeVar("T", bound=Cell)
+
+
+class DiscreteSpace(Generic[T]):
+    """Base class for all discrete spaces.
+
+    Attributes:
+        capacity (int): The capacity of the cells in the discrete space
+        all_cells (CellCollection): The cells composing the discrete space
+        random (Random): The random number generator
+        cell_klass (Type) : the type of cell class
+        empties (CellCollection) : collecction of all cells that are empty
+
+    """
+
+    def __init__(
+        self,
+        capacity: int | None = None,
+        cell_klass: type[T] = Cell,
+        random: Random | None = None,
+    ):
+        super().__init__()
+        self.capacity = capacity
+        self._cells: dict[tuple[int, ...], T] = {}
+        if random is None:
+            random = Random()  # FIXME should default to default rng from model
+        self.random = random
+        self.cell_klass = cell_klass
+
+        self._empties: dict[tuple[int, ...], None] = {}
+        self._empties_initialized = False
+
+    @property
+    def cutoff_empties(self):
+        return 7.953 * len(self._cells) ** 0.384
+
+    def _connect_single_cell(self, cell: T): ...
+
+    @cached_property
+    def all_cells(self):
+        return CellCollection({cell: cell.agents for cell in self._cells.values()})
+
+    def __iter__(self):
+        return iter(self._cells.values())
+
+    def __getitem__(self, key):
+        return self._cells[key]
+
+    @property
+    def empties(self) -> CellCollection:
+        return self.all_cells.select(lambda cell: cell.is_empty)
+
+    def select_random_empty_cell(self) -> T:
+        """select random empty cell"""
+        return self.random.choice(list(self.empties))

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])