Mesa 3.1.5__py3-none-any.whl → 3.2.0.dev0__py3-none-any.whl

mesa/__init__.py

@@ -5,6 +5,7 @@ Core Objects: Model, and Agent.
 
 import datetime
 
+import mesa.discrete_space as discrete_space
 import mesa.experimental as experimental
 import mesa.space as space
 from mesa.agent import Agent
@@ -17,12 +18,13 @@ __all__ = [
     "DataCollector",
     "Model",
     "batch_run",
+    "discrete_space",
     "experimental",
     "space",
 ]
 
 __title__ = "mesa"
-__version__ = "3.1.5"
+__version__ = "3.2.0.dev"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -381,18 +381,33 @@ class AgentSet(MutableSet, Sequence):
 
         return res
 
-    def agg(self, attribute: str, func: Callable) -> Any:
-        """Aggregate an attribute of all agents in the AgentSet using a specified function.
+    def agg(
+        self, attribute: str, func: Callable | Iterable[Callable]
+    ) -> Any | list[Any]:
+        """Aggregate an attribute of all agents in the AgentSet using one or more functions.
 
         Args:
             attribute (str): The name of the attribute to aggregate.
-            func (Callable): The function to apply to the attribute values (e.g., min, max, sum, np.mean).
+            func (Callable | Iterable[Callable]):
+                - If Callable: A single function to apply to the attribute values (e.g., min, max, sum, np.mean)
+                - If Iterable: Multiple functions to apply to the attribute values
 
         Returns:
-            Any: The result of applying the function to the attribute values. Often a single value.
+            Any | [Any, ...]: Result of applying the function(s) to the attribute values.
+
+        Examples:
+            # Single function
+            avg_energy = model.agents.agg("energy", np.mean)
+
+            # Multiple functions
+            min_wealth, max_wealth, total_wealth = model.agents.agg("wealth", [min, max, sum])
         """
         values = self.get(attribute)
-        return func(values)
+
+        if isinstance(func, Callable):
+            return func(values)
+        else:
+            return [f(values) for f in func]
 
     @overload
     def get(

mesa/discrete_space/__init__.py

@@ -0,0 +1,50 @@
+"""Cell spaces for active, property-rich spatial modeling in Mesa.
+
+Cell spaces extend Mesa's spatial modeling capabilities by making the space itself active -
+each position (cell) can have properties and behaviors rather than just containing agents.
+This enables more sophisticated environmental modeling and agent-environment interactions.
+
+Key components:
+- Cells: Active positions that can have properties and contain agents
+- CellAgents: Agents that understand how to interact with cells
+- Spaces: Different cell organization patterns (grids, networks, etc.)
+- PropertyLayers: Efficient property storage and manipulation
+
+This is particularly useful for models where the environment plays an active role,
+like resource growth, pollution diffusion, or infrastructure networks. The cell
+space system is experimental and under active development.
+"""
+
+from mesa.discrete_space.cell import Cell
+from mesa.discrete_space.cell_agent import (
+    CellAgent,
+    FixedAgent,
+    Grid2DMovingAgent,
+)
+from mesa.discrete_space.cell_collection import CellCollection
+from mesa.discrete_space.discrete_space import DiscreteSpace
+from mesa.discrete_space.grid import (
+    Grid,
+    HexGrid,
+    OrthogonalMooreGrid,
+    OrthogonalVonNeumannGrid,
+)
+from mesa.discrete_space.network import Network
+from mesa.discrete_space.property_layer import PropertyLayer
+from mesa.discrete_space.voronoi import VoronoiGrid
+
+__all__ = [
+    "Cell",
+    "CellAgent",
+    "CellCollection",
+    "DiscreteSpace",
+    "FixedAgent",
+    "Grid",
+    "Grid2DMovingAgent",
+    "HexGrid",
+    "Network",
+    "OrthogonalMooreGrid",
+    "OrthogonalVonNeumannGrid",
+    "PropertyLayer",
+    "VoronoiGrid",
+]

mesa/{experimental/cell_space → discrete_space}/cell.py

@@ -18,8 +18,8 @@ from functools import cache, cached_property
 from random import Random
 from typing import TYPE_CHECKING
 
-from mesa.experimental.cell_space.cell_agent import CellAgent
-from mesa.experimental.cell_space.cell_collection import CellCollection
+from mesa.discrete_space.cell_agent import CellAgent
+from mesa.discrete_space.cell_collection import CellCollection
 
 if TYPE_CHECKING:
     from mesa.agent import Agent
@@ -40,7 +40,7 @@ class Cell:
 
     __slots__ = [
         "__dict__",
-        "agents",
+        "_agents",
         "capacity",
         "connections",
         "coordinate",
@@ -65,8 +65,8 @@ class Cell:
         super().__init__()
         self.coordinate = coordinate
         self.connections: dict[Coordinate, Cell] = {}
-        self.agents: list[
-            Agent
+        self._agents: list[
+            CellAgent
         ] = []  # TODO:: change to AgentSet or weakrefs? (neither is very performant, )
         self.capacity: int | None = capacity
         self.properties: dict[
@@ -84,6 +84,7 @@ class Cell:
         """
         if key is None:
             key = other.coordinate
+        self._clear_cache()
         self.connections[key] = other
 
     def disconnect(self, other: Cell) -> None:
@@ -96,6 +97,7 @@ class Cell:
         keys_to_remove = [k for k, v in self.connections.items() if v == other]
         for key in keys_to_remove:
             del self.connections[key]
+        self._clear_cache()
 
     def add_agent(self, agent: CellAgent) -> None:
         """Adds an agent to the cell.
@@ -104,7 +106,7 @@ class Cell:
             agent (CellAgent): agent to add to this Cell
 
         """
-        n = len(self.agents)
+        n = len(self._agents)
         self.empty = False
 
         if self.capacity and n >= self.capacity:
@@ -112,7 +114,7 @@ class Cell:
                 "ERROR: Cell is full"
             )  # FIXME we need MESA errors or a proper error
 
-        self.agents.append(agent)
+        self._agents.append(agent)
 
     def remove_agent(self, agent: CellAgent) -> None:
         """Removes an agent from the cell.
@@ -121,7 +123,7 @@ class Cell:
             agent (CellAgent): agent to remove from this cell
 
         """
-        self.agents.remove(agent)
+        self._agents.remove(agent)
         self.empty = self.is_empty
 
     @property
@@ -134,6 +136,11 @@ class Cell:
         """Returns a bool of the contents of a cell."""
         return len(self.agents) == self.capacity
 
+    @property
+    def agents(self) -> list[CellAgent]:
+        """Returns a list of the agents occupying the cell."""
+        return self._agents.copy()
+
     def __repr__(self):  # noqa
         return f"Cell({self.coordinate}, {self.agents})"
 
@@ -180,12 +187,12 @@ class Cell:
             raise ValueError("radius must be larger than one")
         if radius == 1:
             neighborhood = {
-                neighbor: neighbor.agents for neighbor in self.connections.values()
+                neighbor: neighbor._agents for neighbor in self.connections.values()
             }
             if not include_center:
                 return neighborhood
             else:
-                neighborhood[self] = self.agents
+                neighborhood[self] = self._agents
                 return neighborhood
         else:
             neighborhood: dict[Cell, list[Agent]] = {}
@@ -205,3 +212,15 @@ class Cell:
             "connections"
         ] = {}  # replace this with empty connections to avoid infinite recursion error in pickle/deepcopy
         return state
+
+    def _clear_cache(self):
+        """Helper function to clear local cache."""
+        try:
+            self.__dict__.pop(
+                "neighborhood"
+            )  # cached properties are stored in __dict__, see functools.cached_property docs
+        except KeyError:
+            pass  # cache is not set
+        else:
+            self.get_neighborhood.cache_clear()
+            self._neighborhood.cache_clear()

mesa/{experimental/cell_space → discrete_space}/cell_agent.py

@@ -18,7 +18,7 @@ from typing import TYPE_CHECKING, Protocol
 from mesa.agent import Agent
 
 if TYPE_CHECKING:
-    from mesa.experimental.cell_space import Cell
+    from mesa.discrete_space import Cell
 
 
 class HasCellProtocol(Protocol):

mesa/{experimental/cell_space → discrete_space}/cell_collection.py

@@ -23,8 +23,8 @@ from random import Random
 from typing import TYPE_CHECKING, Generic, TypeVar
 
 if TYPE_CHECKING:
-    from mesa.experimental.cell_space.cell import Cell
-    from mesa.experimental.cell_space.cell_agent import CellAgent
+    from mesa.discrete_space.cell import Cell
+    from mesa.discrete_space.cell_agent import CellAgent
 
 T = TypeVar("T", bound="Cell")
 
@@ -59,7 +59,7 @@ class CellCollection(Generic[T]):
         if isinstance(cells, dict):
             self._cells = cells
         else:
-            self._cells = {cell: cell.agents for cell in cells}
+            self._cells = {cell: cell._agents for cell in cells}
 
         # Get capacity from first cell if collection is not empty
         self._capacity: int | None = (

mesa/{experimental/cell_space → discrete_space}/discrete_space.py

@@ -21,8 +21,8 @@ from random import Random
 from typing import Generic, TypeVar
 
 from mesa.agent import AgentSet
-from mesa.experimental.cell_space.cell import Cell
-from mesa.experimental.cell_space.cell_collection import CellCollection
+from mesa.discrete_space.cell import Cell
+from mesa.discrete_space.cell_collection import CellCollection
 
 T = TypeVar("T", bound=Cell)
 
@@ -85,11 +85,73 @@ class DiscreteSpace(Generic[T]):
     def _connect_cells(self): ...
     def _connect_single_cell(self, cell: T): ...
 
+    def add_cell(self, cell: T):
+        """Add a cell to the space.
+
+        Args:
+            cell: cell to add
+
+        Note:
+            Discrete spaces rely on caching neighborhood relations for speedups. Adding or removing cells and
+            connections at runtime is possible. However, only the caches of cells directly affected will be cleared. So
+            if you rely on getting neighborhoods of cells with a radius higher than 1, these might not be cleared
+            correctly if you are adding or removing cells and connections at runtime.
+
+        """
+        self.__dict__.pop("all_cells", None)
+        self._cells[cell.coordinate] = cell
+
+    def remove_cell(self, cell: T):
+        """Remove a cell from the space.
+
+        Note:
+            Discrete spaces rely on caching neighborhood relations for speedups. Adding or removing cells and
+            connections at runtime is possible. However, only the caches of cells directly affected will be cleared. So
+            if you rely on getting neighborhoods of cells with a radius higher than 1, these might not be cleared
+            correctly if you are adding or removing cells and connections at runtime.
+
+
+        """
+        neighbors = cell.neighborhood
+        self._cells.pop(cell.coordinate)
+        self.__dict__.pop("all_cells", None)
+
+        # iterate over all neighbors
+        for neighbor in neighbors.cells:
+            neighbor.disconnect(cell)
+            cell.disconnect(neighbor)
+
+    def add_connection(self, cell1: T, cell2: T):
+        """Add a connection between the two cells.
+
+        Note:
+            Discrete spaces rely on caching neighborhood relations for speedups. Adding or removing cells and
+            connections at runtime is possible. However, only the caches of cells directly affected will be cleared. So
+            if you rely on getting neighborhoods of cells with a radius higher than 1, these might not be cleared
+            correctly if you are adding or removing cells and connections at runtime.
+
+        """
+        cell1.connect(cell2)
+        cell2.connect(cell1)
+
+    def remove_connection(self, cell1: T, cell2: T):
+        """Remove a connection between the two cells.
+
+        Note:
+            Discrete spaces rely on caching neighborhood relations for speedups. Adding or removing cells and
+            connections at runtime is possible. However, only the caches of cells directly affected will be cleared. So
+            if you rely on getting neighborhoods of cells with a radius higher than 1, these might not be cleared
+            correctly if you are adding or removing cells and connections at runtime.
+
+        """
+        cell1.disconnect(cell2)
+        cell2.disconnect(cell1)
+
     @cached_property
     def all_cells(self):
         """Return all cells in space."""
         return CellCollection(
-            {cell: cell.agents for cell in self._cells.values()}, random=self.random
+            {cell: cell._agents for cell in self._cells.values()}, random=self.random
         )
 
     def __iter__(self):  # noqa

mesa/{experimental/cell_space → discrete_space}/grid.py

@@ -19,8 +19,8 @@ from itertools import product
 from random import Random
 from typing import Any, Generic, TypeVar
 
-from mesa.experimental.cell_space import Cell, DiscreteSpace
-from mesa.experimental.cell_space.property_layer import (
+from mesa.discrete_space import Cell, DiscreteSpace
+from mesa.discrete_space.property_layer import (
     HasPropertyLayers,
     PropertyDescriptor,
 )

mesa/{experimental/cell_space → discrete_space}/network.py

@@ -15,8 +15,8 @@ or any environment where connectivity matters more than physical location.
 from random import Random
 from typing import Any
 
-from mesa.experimental.cell_space.cell import Cell
-from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+from mesa.discrete_space.cell import Cell
+from mesa.discrete_space.discrete_space import DiscreteSpace
 
 
 class Network(DiscreteSpace[Cell]):
@@ -55,3 +55,23 @@ class Network(DiscreteSpace[Cell]):
     def _connect_single_cell(self, cell: Cell):
         for node_id in self.G.neighbors(cell.coordinate):
             cell.connect(self._cells[node_id], node_id)
+
+    def add_cell(self, cell: Cell):
+        """Add a cell to the space."""
+        super().add_cell(cell)
+        self.G.add_node(cell.coordinate)
+
+    def remove_cell(self, cell: Cell):
+        """Remove a cell from the space."""
+        super().remove_cell(cell)
+        self.G.remove_node(cell.coordinate)
+
+    def add_connection(self, cell1: Cell, cell2: Cell):
+        """Add a connection between the two cells."""
+        super().add_connection(cell1, cell2)
+        self.G.add_edge(cell1.coordinate, cell2.coordinate)
+
+    def remove_connection(self, cell1: Cell, cell2: Cell):
+        """Remove a connection between the two cells."""
+        super().remove_connection(cell1, cell2)
+        self.G.remove_edge(cell1.coordinate, cell2.coordinate)

mesa/{experimental/cell_space → discrete_space}/property_layer.py

@@ -21,7 +21,7 @@ from typing import Any, TypeVar
 
 import numpy as np
 
-from mesa.experimental.cell_space import Cell
+from mesa.discrete_space import Cell
 
 Coordinate = Sequence[int]
 T = TypeVar("T", bound=Cell)
@@ -85,15 +85,6 @@ class PropertyLayer:
         # fixme why not initialize with empty?
         self._mesa_data = np.full(self.dimensions, default_value, dtype=dtype)
 
-        if not self.__class__.propertylayer_experimental_warning_given:
-            warnings.warn(
-                "The property layer functionality and associated classes are 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/1932",
-                FutureWarning,
-                stacklevel=2,
-            )
-            self.__class__.propertylayer_experimental_warning_given = True
-
     @classmethod
     def from_data(cls, name: str, data: np.ndarray):
         """Create a property layer from a NumPy array.

mesa/{experimental/cell_space → discrete_space}/voronoi.py

@@ -18,8 +18,8 @@ from random import Random
 
 import numpy as np
 
-from mesa.experimental.cell_space.cell import Cell
-from mesa.experimental.cell_space.discrete_space import DiscreteSpace
+from mesa.discrete_space.cell import Cell
+from mesa.discrete_space.discrete_space import DiscreteSpace
 
 
 class Delaunay:

mesa/examples/advanced/epstein_civil_violence/agents.py

@@ -10,7 +10,7 @@ class CitizenState(Enum):
     ARRESTED = 3
 
 
-class EpsteinAgent(mesa.experimental.cell_space.CellAgent):
+class EpsteinAgent(mesa.discrete_space.CellAgent):
     def update_neighbors(self):
         """
         Look around and see who my neighbors are

mesa/examples/advanced/epstein_civil_violence/model.py

@@ -53,7 +53,7 @@ class EpsteinCivilViolence(mesa.Model):
         self.movement = movement
         self.max_iters = max_iters
 
-        self.grid = mesa.experimental.cell_space.OrthogonalVonNeumannGrid(
+        self.grid = mesa.discrete_space.OrthogonalVonNeumannGrid(
             (width, height), capacity=1, torus=True, random=self.random
         )
 

mesa/examples/advanced/pd_grid/agents.py

@@ -1,4 +1,4 @@
-from mesa.experimental.cell_space import CellAgent
+from mesa.discrete_space import CellAgent
 
 
 class PDAgent(CellAgent):

mesa/examples/advanced/pd_grid/model.py

@@ -1,6 +1,6 @@
 import mesa
+from mesa.discrete_space import OrthogonalMooreGrid
 from mesa.examples.advanced.pd_grid.agents import PDAgent
-from mesa.experimental.cell_space import OrthogonalMooreGrid
 
 
 class PdGrid(mesa.Model):

mesa/examples/advanced/sugarscape_g1mt/agents.py

@@ -1,6 +1,6 @@
 import math
 
-from mesa.experimental.cell_space import CellAgent
+from mesa.discrete_space import CellAgent
 
 
 # Helper function

mesa/examples/advanced/sugarscape_g1mt/model.py

@@ -3,9 +3,9 @@ from pathlib import Path
 import numpy as np
 
 import mesa
+from mesa.discrete_space import OrthogonalVonNeumannGrid
+from mesa.discrete_space.property_layer import PropertyLayer
 from mesa.examples.advanced.sugarscape_g1mt.agents import Trader
-from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
-from mesa.experimental.cell_space.property_layer import PropertyLayer
 
 
 # Helper Functions

mesa/examples/advanced/wolf_sheep/agents.py

@@ -1,4 +1,4 @@
-from mesa.experimental.cell_space import CellAgent, FixedAgent
+from mesa.discrete_space import CellAgent, FixedAgent
 
 
 class Animal(CellAgent):

mesa/examples/advanced/wolf_sheep/app.py

@@ -2,6 +2,7 @@ from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
 from mesa.examples.advanced.wolf_sheep.model import WolfSheep
 from mesa.experimental.devs import ABMSimulator
 from mesa.visualization import (
+    CommandConsole,
     Slider,
     SolaraViz,
     make_plot_component,
@@ -87,7 +88,7 @@ model = WolfSheep(simulator=simulator, grass=True)
 
 page = SolaraViz(
     model,
-    components=[space_component, lineplot_component],
+    components=[space_component, lineplot_component, CommandConsole],
     model_params=model_params,
     name="Wolf Sheep",
     simulator=simulator,

mesa/examples/advanced/wolf_sheep/model.py

@@ -13,8 +13,8 @@ import math
 
 from mesa import Model
 from mesa.datacollection import DataCollector
+from mesa.discrete_space import OrthogonalVonNeumannGrid
 from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
-from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
 from mesa.experimental.devs import ABMSimulator
 
 

mesa/examples/basic/boid_flockers/agents.py

@@ -58,6 +58,7 @@ class Boid(ContinuousSpaceAgent):
         self.separate_factor = separate
         self.match_factor = match
         self.neighbors = []
+        self.angle = 0.0  # represents the angle at which the boid is moving
 
     def step(self):
         """Get the Boid's neighbors, compute the new vector, and move accordingly."""

mesa/examples/basic/boid_flockers/app.py

@@ -1,19 +1,34 @@
 import os
 import sys
 
+from matplotlib.markers import MarkerStyle
+
 sys.path.insert(0, os.path.abspath("../../../.."))
 
 from mesa.examples.basic.boid_flockers.model import BoidFlockers
 from mesa.visualization import Slider, SolaraViz, make_space_component
 
+# Pre-compute markers for different angles (e.g., every 10 degrees)
+MARKER_CACHE = {}
+for angle in range(0, 360, 10):
+    marker = MarkerStyle(10)
+    marker._transform = marker.get_transform().rotate_deg(angle)
+    MARKER_CACHE[angle] = marker
+
 
 def boid_draw(agent):
     neighbors = len(agent.neighbors)
 
+    # Calculate the angle
+    deg = agent.angle
+    # Round to nearest 10 degrees
+    rounded_deg = round(deg / 10) * 10 % 360
+
+    # using cached markers to speed things up
     if neighbors <= 1:
-        return {"color": "red", "size": 20}
+        return {"color": "red", "size": 20, "marker": MARKER_CACHE[rounded_deg]}
     elif neighbors >= 2:
-        return {"color": "green", "size": 20}
+        return {"color": "green", "size": 20, "marker": MARKER_CACHE[rounded_deg]}
 
 
 model_params = {

mesa/examples/basic/boid_flockers/model.py

@@ -49,6 +49,9 @@ class BoidFlockers(Model):
             seed: Random seed for reproducibility (default: None)
         """
         super().__init__(seed=seed)
+        self.agent_angles = np.zeros(
+            population_size
+        )  # holds the angle representing the direction of all agents at a given step
 
         # Set up the space
         self.space = ContinuousSpace(
@@ -79,6 +82,14 @@ class BoidFlockers(Model):
         self.average_heading = None
         self.update_average_heading()
 
+    # vectorizing the calculation of angles for all agents
+    def calculate_angles(self):
+        d1 = np.array([agent.direction[0] for agent in self.agents])
+        d2 = np.array([agent.direction[1] for agent in self.agents])
+        self.agent_angles = np.degrees(np.arctan2(d1, d2))
+        for agent, angle in zip(self.agents, self.agent_angles):
+            agent.angle = angle
+
     def update_average_heading(self):
         """Calculate the average heading (direction) of all Boids."""
         if not self.agents:
@@ -96,3 +107,4 @@ class BoidFlockers(Model):
         """
         self.agents.shuffle_do("step")
         self.update_average_heading()
+        self.calculate_angles()

mesa/examples/basic/boltzmann_wealth_model/agents.py

@@ -1,7 +1,7 @@
-from mesa import Agent
+from mesa.discrete_space import CellAgent
 
 
-class MoneyAgent(Agent):
+class MoneyAgent(CellAgent):
     """An agent with fixed initial wealth.
 
     Each agent starts with 1 unit of wealth and can give 1 unit to other agents
@@ -11,28 +11,23 @@ class MoneyAgent(Agent):
         wealth (int): The agent's current wealth (starts at 1)
     """
 
-    def __init__(self, model):
+    def __init__(self, model, cell):
         """Create a new agent.
 
         Args:
             model (Model): The model instance that contains the agent
         """
         super().__init__(model)
+        self.cell = cell
         self.wealth = 1
 
     def move(self):
         """Move the agent to a random neighboring cell."""
-        possible_steps = self.model.grid.get_neighborhood(
-            self.pos, moore=True, include_center=False
-        )
-        new_position = self.random.choice(possible_steps)
-        self.model.grid.move_agent(self, new_position)
+        self.cell = self.cell.neighborhood.select_random_cell()
 
     def give_money(self):
         """Give 1 unit of wealth to a random agent in the same cell."""
-        cellmates = self.model.grid.get_cell_list_contents([self.pos])
-        # Remove self from potential recipients
-        cellmates.pop(cellmates.index(self))
+        cellmates = [a for a in self.cell.agents if a is not self]
 
         if cellmates:  # Only give money if there are other agents present
             other = self.random.choice(cellmates)

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -1,12 +1,12 @@
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
-from mesa.mesa_logging import DEBUG, log_to_stderr
+from mesa.mesa_logging import INFO, log_to_stderr
 from mesa.visualization import (
     SolaraViz,
     make_plot_component,
     make_space_component,
 )
 
-log_to_stderr(DEBUG)
+log_to_stderr(INFO)
 
 
 def agent_portrayal(agent):