Mesa 3.1.5__py3-none-any.whl → 3.2.0__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"
 __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

@@ -53,13 +53,12 @@ class Agent:
 
         Args:
             model (Model): The model instance in which the agent exists.
-            args: passed on to super
-            kwargs: passed on to super
+            args: Passed on to super.
+            kwargs: Passed on to super.
 
         Notes:
             to make proper use of python's super, in each class remove the arguments and
             keyword arguments you need and pass on the rest to super
-
         """
         super().__init__(*args, **kwargs)
 
@@ -103,7 +102,10 @@ class Agent:
         """
 
         class ListLike:
-            """Helper class to make default arguments act as if they are in a list of length N."""
+            """Make default arguments act as if they are in a list of length N.
+
+            This is a helper class.
+            """
 
             def __init__(self, value):
                 self.value = value
@@ -381,18 +383,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/README.md

@@ -12,7 +12,7 @@ The examples are categorized into two groups:
 The basic examples are relatively simple and only use stable Mesa features. They are good starting points for learning how to use Mesa.
 
 ### [Boltzmann Wealth Model](examples/basic/boltzmann_wealth_model)
-Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
+Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/0_first_model.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
 
 ### [Boids Flockers Model](examples/basic/boid_flockers)
 [Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.

mesa/examples/__init__.py

@@ -1,3 +1,4 @@
+from mesa.examples.advanced.alliance_formation.model import MultiLevelAllianceModel
 from mesa.examples.advanced.epstein_civil_violence.model import EpsteinCivilViolence
 from mesa.examples.advanced.pd_grid.model import PdGrid
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
@@ -13,6 +14,7 @@ __all__ = [
     "BoltzmannWealth",
     "ConwaysGameOfLife",
     "EpsteinCivilViolence",
+    "MultiLevelAllianceModel",
     "PdGrid",
     "Schelling",
     "SugarscapeG1mt",

mesa/examples/advanced/alliance_formation/Readme.md

@@ -0,0 +1,50 @@
+# Alliance Formation Model (Meta-Agent Example)
+
+## Summary
+
+This model demonstrates Mesa's meta agent capability.
+
+**Overview of meta agent:** Complex systems often have multiple levels of components. A city is not a single entity, but it is made of districts,neighborhoods, buildings, and people. A forest comprises an ecosystem of trees, plants, animals, and microorganisms. An organization is not one entity, but is made of departments, sub-departments, and people. A person is not a single entity, but it is made of micro biomes, organs and cells.
+
+This reality is the motivation for meta-agents. It allows users to represent these multiple levels, where each level can have agents with sub-agents.
+
+This model demonstrates Mesa's ability to dynamically create new classes of agents that are composed of existing agents. These meta-agents inherits functions and attributes from their sub-agents and users can specify new functionality or attributes they want the meta agent to have. For example, if a user is doing a factory simulation with autonomous systems, each major component of that system can be a sub-agent of the overall robot agent. Or, if someone is doing a simulation of an organization, individuals can be part of different organizational units that are working for some purpose.
+
+To provide a simple demonstration of this capability is an alliance formation model.
+
+In this simulation n agents are created, who have two attributes (1) power and (2) preference. Each attribute is a number between 0 and 1 over a gaussian distribution. Agents then randomly select other agents and use the [bilateral shapley value](https://en.wikipedia.org/wiki/Shapley_value) to determine if they should form an alliance. If the expected utility support an alliances, the agent creates a meta-agent. Subsequent steps may add agents to the meta-agent, create new instances of similar hierarchy, or create a new hierarchy level where meta-agents form an alliance of meta-agents. In this visualization of this model a new meta-agent hierarchy will be a larger node and a new color.
+
+In MetaAgents current configuration, agents being part of multiple meta-agents is not supported.
+
+If you would like to see an example of explicit meta-agent formation see the [warehouse model in the Mesa example's repository](https://github.com/projectmesa/mesa-examples/tree/main/examples/warehouse)
+
+
+## Installation
+
+This model requires Mesa's recommended install and scipy
+
+```
+    $ pip install mesa[rec]
+```
+
+## How to Run
+
+To run the model interactively, in this directory, run the following command
+
+```
+    $ solara run app.py
+```
+
+## Files
+
+- `model.py`: Contains creation of agents, the network and management of agent execution.
+- `agents.py`: Contains logic for forming alliances and creation of new agents
+- `app.py`: Contains the code for the interactive Solara visualization.
+
+## Further Reading
+
+The full tutorial describing how the model is built can be found at:
+https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html
+
+An example of the bilateral shapley value in another model:
+[Techno-Social Energy Infrastructure Siting: Sustainable Energy Modeling Programming (SEMPro)](https://www.jasss.org/16/3/6.html)

mesa/examples/advanced/alliance_formation/agents.py

@@ -0,0 +1,20 @@
+import mesa
+
+
+class AllianceAgent(mesa.Agent):
+    """
+    Agent has three attributes power (float), position (float) and level (int)
+
+    """
+
+    def __init__(self, model, power, position, level=0):
+        super().__init__(model)
+        self.power = power
+        self.position = position
+        self.level = level
+
+    """
+    For this demo model agent only need attributes.
+
+    More complex models could have functions that define agent behavior.
+    """

mesa/examples/advanced/alliance_formation/app.py

@@ -0,0 +1,71 @@
+import matplotlib.pyplot as plt
+import networkx as nx
+import solara
+from matplotlib.figure import Figure
+
+from mesa.examples.advanced.alliance_formation.model import MultiLevelAllianceModel
+from mesa.visualization import SolaraViz
+from mesa.visualization.utils import update_counter
+
+model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
+    "n": {
+        "type": "SliderInt",
+        "value": 50,
+        "label": "Number of agents:",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+}
+
+# Create visualization elements. The visualization elements are solara components
+# that receive the model instance as a "prop" and display it in a certain way.
+# Under the hood these are just classes that receive the model instance.
+# You can also author your own visualization elements, which can also be functions
+# that receive the model instance and return a valid solara component.
+
+
+@solara.component
+def plot_network(model):
+    update_counter.get()
+    g = model.network
+    pos = nx.fruchterman_reingold_layout(g)
+    fig = Figure()
+    ax = fig.subplots()
+    labels = {agent.unique_id: agent.unique_id for agent in model.agents}
+    node_sizes = [g.nodes[node]["size"] for node in g.nodes]
+    node_colors = [g.nodes[node]["size"] for node in g.nodes()]
+
+    nx.draw(
+        g,
+        pos,
+        node_size=node_sizes,
+        node_color=node_colors,
+        cmap=plt.cm.coolwarm,
+        labels=labels,
+        ax=ax,
+    )
+
+    solara.FigureMatplotlib(fig)
+
+
+# Create initial model instance
+model = MultiLevelAllianceModel(50)
+
+# Create the SolaraViz page. This will automatically create a server and display the
+# visualization elements in a web browser.
+# Display it using the following command in the example directory:
+# solara run app.py
+# It will automatically update and display any changes made to this file
+page = SolaraViz(
+    model,
+    components=[plot_network],
+    model_params=model_params,
+    name="Alliance Formation Model",
+)
+page  # noqa