Mesa 2.2.4__py3-none-any.whl → 2.3.0__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.2.4"
+__version__ = "2.3.0"
 __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:
@@ -188,15 +174,21 @@ class AgentSet(MutableSet, Sequence):
 
         Returns:
             AgentSet: A shuffled AgentSet. Returns the current AgentSet if inplace is True.
-        """
-        shuffled_agents = list(self)
-        self.random.shuffle(shuffled_agents)
 
-        return (
-            AgentSet(shuffled_agents, self.model)
-            if not inplace
-            else self._update(shuffled_agents)
-        )
+        Note:
+            Using inplace = True is more performant
+
+        """
+        weakrefs = list(self._agents.keyrefs())
+        self.random.shuffle(weakrefs)
+
+        if inplace:
+            self._agents.data = {entry: None for entry in weakrefs}
+            return self
+        else:
+            return AgentSet(
+                (agent for ref in weakrefs if (agent := ref()) is not None), self.model
+            )
 
     def sort(
         self,
@@ -251,24 +243,36 @@ class AgentSet(MutableSet, Sequence):
         """
         # we iterate over the actual weakref keys and check if weakref is alive before calling the method
         res = [
-            getattr(agentref(), method_name)(*args, **kwargs)
+            getattr(agent, method_name)(*args, **kwargs)
             for agentref in self._agents.keyrefs()
-            if agentref()
+            if (agent := agentref()) is not None
         ]
 
         return res if return_results else self
 
-    def get(self, attr_name: str) -> list[Any]:
+    def get(self, attr_names: str | list[str]) -> list[Any]:
         """
-        Retrieve a specified attribute from each agent in the AgentSet.
+        Retrieve the specified attribute(s) from each agent in the AgentSet.
 
         Args:
-            attr_name (str): The name of the attribute to retrieve from each agent.
+            attr_names (str | list[str]): The name(s) of the attribute(s) to retrieve from each agent.
 
         Returns:
-            list[Any]: A list of attribute values from each agent in the set.
+            list[Any]: A list with the attribute value for each agent in the set if attr_names is a str
+            list[list[Any]]: A list with a list of attribute values for each agent in the set if attr_names is a list of str
+
+        Raises:
+            AttributeError if an agent does not have the specified attribute(s)
+
         """
-        return [getattr(agent, attr_name) for agent in self._agents]
+
+        if isinstance(attr_names, str):
+            return [getattr(agent, attr_names) for agent in self._agents]
+        else:
+            return [
+                [getattr(agent, attr_name) for attr_name in attr_names]
+                for agent in self._agents
+            ]
 
     def __getitem__(self, item: int | slice) -> Agent:
         """

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
@@ -184,7 +185,9 @@ class DataCollector:
 
         agent_records = map(
             get_reports,
-            model.schedule.agents if hasattr(model, "schedule") else model.agents,
+            model.schedule.agents
+            if hasattr(model, "schedule") and model.schedule is not None
+            else model.agents,
         )
         return agent_records
 

mesa/experimental/UserParam.py

@@ -0,0 +1,56 @@
+class UserParam:
+    _ERROR_MESSAGE = "Missing or malformed inputs for '{}' Option '{}'"
+
+    def maybe_raise_error(self, param_type, valid):
+        if valid:
+            return
+        msg = self._ERROR_MESSAGE.format(param_type, self.label)
+        raise ValueError(msg)
+
+
+class Slider(UserParam):
+    """
+    A number-based slider input with settable increment.
+
+    Example:
+
+    slider_option = Slider("My Slider", value=123, min=10, max=200, step=0.1)
+
+    Args:
+        label: The displayed label in the UI
+        value: The initial value of the slider
+        min: The minimum possible value of the slider
+        max: The maximum possible value of the slider
+        step: The step between min and max for a range of possible values
+        dtype: either int or float
+    """
+
+    def __init__(
+        self,
+        label="",
+        value=None,
+        min=None,
+        max=None,
+        step=1,
+        dtype=None,
+    ):
+        self.label = label
+        self.value = value
+        self.min = min
+        self.max = max
+        self.step = step
+
+        # Validate option type to make sure values are supplied properly
+        valid = not (self.value is None or self.min is None or self.max is None)
+        self.maybe_raise_error("slider", valid)
+
+        if dtype is None:
+            self.is_float_slider = self._check_values_are_float(value, min, max, step)
+        else:
+            self.is_float_slider = dtype == float
+
+    def _check_values_are_float(self, value, min, max, step):
+        return any(isinstance(n, float) for n in (value, min, max, step))
+
+    def get(self, attr):
+        return getattr(self, attr)

mesa/experimental/__init__.py

@@ -1 +1,5 @@
-from .jupyter_viz import JupyterViz, make_text  # noqa
+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))