Mesa 3.0.3__py3-none-any.whl → 3.1.0__py3-none-any.whl

mesa/__init__.py

@@ -7,24 +7,22 @@ import datetime
 
 import mesa.experimental as experimental
 import mesa.space as space
-import mesa.time as time
 from mesa.agent import Agent
 from mesa.batchrunner import batch_run
 from mesa.datacollection import DataCollector
 from mesa.model import Model
 
 __all__ = [
-    "Model",
     "Agent",
-    "time",
-    "space",
     "DataCollector",
+    "Model",
     "batch_run",
     "experimental",
+    "space",
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.3"
+__version__ = "3.1.0"
 __license__ = "Apache 2.0"
-_this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
+_this_year = datetime.datetime.now(tz=datetime.UTC).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -85,6 +85,54 @@ class Agent:
     def advance(self) -> None:  # noqa: D102
         pass
 
+    @classmethod
+    def create_agents(cls, model: Model, n: int, *args, **kwargs) -> AgentSet[Agent]:
+        """Create N agents.
+
+        Args:
+            model: the model to which the agents belong
+            args: arguments to pass onto agent instances
+                  each arg is either a single object or a sequence of length n
+            n: the number of agents to create
+            kwargs: keyword arguments to pass onto agent instances
+                   each keyword arg is either a single object or a sequence of length n
+
+        Returns:
+            AgentSet containing the agents created.
+
+        """
+
+        class ListLike:
+            """Helper class to make default arguments act as if they are in a list of length N."""
+
+            def __init__(self, value):
+                self.value = value
+
+            def __getitem__(self, i):
+                return self.value
+
+        listlike_args = []
+        for arg in args:
+            if isinstance(arg, (list | np.ndarray | tuple)) and len(arg) == n:
+                listlike_args.append(arg)
+            else:
+                listlike_args.append(ListLike(arg))
+
+        listlike_kwargs = {}
+        for k, v in kwargs.items():
+            if isinstance(v, (list | np.ndarray | tuple)) and len(v) == n:
+                listlike_kwargs[k] = v
+            else:
+                listlike_kwargs[k] = ListLike(v)
+
+        agents = []
+        for i in range(n):
+            instance_args = [arg[i] for arg in listlike_args]
+            instance_kwargs = {k: v[i] for k, v in listlike_kwargs.items()}
+            agent = cls(model, *instance_args, **instance_kwargs)
+            agents.append(agent)
+        return AgentSet(agents, random=model.random)
+
     @property
     def random(self) -> Random:
         """Return a seeded stdlib rng."""
@@ -155,7 +203,6 @@ class AgentSet(MutableSet, Sequence):
         at_most: int | float = float("inf"),
         inplace: bool = False,
         agent_type: type[Agent] | None = None,
-        n: int | None = None,
     ) -> AgentSet:
         """Select a subset of agents from the AgentSet based on a filter function and/or quantity limit.
 
@@ -167,7 +214,6 @@ class AgentSet(MutableSet, Sequence):
               - If a float between 0 and 1, at most that fraction of original the agents are selected.
             inplace (bool, optional): If True, modifies the current AgentSet; otherwise, returns a new AgentSet. Defaults to False.
             agent_type (type[Agent], optional): The class type of the agents to select. Defaults to None, meaning no type filtering is applied.
-            n (int): deprecated, use at_most instead
 
         Returns:
             AgentSet: A new AgentSet containing the selected agents, unless inplace is True, in which case the current AgentSet is updated.
@@ -176,14 +222,6 @@ class AgentSet(MutableSet, Sequence):
             - at_most just return the first n or fraction of agents. To take a random sample, shuffle() beforehand.
             - at_most is an upper limit. When specifying other criteria, the number of agents returned can be smaller.
         """
-        if n is not None:
-            warnings.warn(
-                "The parameter 'n' is deprecated and will be removed in Mesa 3.1. Use 'at_most' instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            at_most = n
-
         inf = float("inf")
         if filter_func is None and agent_type is None and at_most == inf:
             return self if inplace else copy.copy(self)
@@ -281,21 +319,6 @@ class AgentSet(MutableSet, Sequence):
         Returns:
             AgentSet | list[Any]: The results of the callable calls if return_results is True, otherwise the AgentSet itself.
         """
-        try:
-            return_results = kwargs.pop("return_results")
-        except KeyError:
-            return_results = False
-        else:
-            warnings.warn(
-                "Using return_results is deprecated and will be removed in Mesa 3.1."
-                "Use AgenSet.do in case of return_results=False, and AgentSet.map in case of return_results=True",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-        if return_results:
-            return self.map(method, *args, **kwargs)
-
         # we iterate over the actual weakref keys and check if weakref is alive before calling the method
         if isinstance(method, str):
             for agentref in self._agents.keyrefs():

mesa/batchrunner.py

@@ -106,7 +106,14 @@ def _make_model_kwargs(
     Parameters
     ----------
     parameters : Mapping[str, Union[Any, Iterable[Any]]]
-        Single or multiple values for each model parameter name
+        Single or multiple values for each model parameter name.
+
+        Allowed values for each parameter:
+        - A single value (e.g., `32`, `"relu"`).
+        - A non-empty iterable (e.g., `[0.01, 0.1]`, `["relu", "sigmoid"]`).
+
+        Not allowed:
+        - Empty lists or empty iterables (e.g., `[]`, `()`, etc.). These should be removed manually.
 
     Returns:
     -------
@@ -118,6 +125,12 @@ def _make_model_kwargs(
         if isinstance(values, str):
             # The values is a single string, so we shouldn't iterate over it.
             all_values = [(param, values)]
+        elif isinstance(values, list | tuple | set) and len(values) == 0:
+            # If it's an empty iterable, raise an error
+            raise ValueError(
+                f"Parameter '{param}' contains an empty iterable, which is not allowed."
+            )
+
         else:
             try:
                 all_values = [(param, value) for value in values]

mesa/datacollection.py

@@ -228,12 +228,7 @@ class DataCollector:
             reports = tuple(rep(agent) for rep in rep_funcs)
             return _prefix + reports
 
-        agent_records = map(
-            get_reports,
-            model.schedule.agents
-            if hasattr(model, "schedule") and model.schedule is not None
-            else model.agents,
-        )
+        agent_records = map(get_reports, model.agents)
         return agent_records
 
     def _record_agenttype(self, model, agent_type):

mesa/examples/__init__.py

@@ -12,10 +12,10 @@ __all__ = [
     "BoidFlockers",
     "BoltzmannWealth",
     "ConwaysGameOfLife",
-    "Schelling",
-    "VirusOnNetwork",
     "EpsteinCivilViolence",
     "PdGrid",
+    "Schelling",
     "SugarscapeG1mt",
+    "VirusOnNetwork",
     "WolfSheep",
 ]

mesa/examples/advanced/epstein_civil_violence/app.py

@@ -44,6 +44,11 @@ def post_process(ax):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "height": 40,
     "width": 40,
     "citizen_density": Slider("Initial Agent Density", 0.7, 0.0, 0.9, 0.1),

mesa/examples/advanced/pd_grid/app.py

@@ -24,6 +24,11 @@ def pd_agent_portrayal(agent):
 
 # Model parameters
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": Slider("Grid Width", value=50, min=10, max=100, step=1),
     "height": Slider("Grid Height", value=50, min=10, max=100, step=1),
     "activation_order": {

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -47,6 +47,11 @@ def SpaceDrawer(model):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": 50,
     "height": 50,
     # Population parameters
@@ -66,10 +71,10 @@ model_params = {
     "enable_trade": {"type": "Checkbox", "value": True, "label": "Enable Trading"},
 }
 
-model1 = SugarscapeG1mt()
+model = SugarscapeG1mt()
 
 page = SolaraViz(
-    model1,
+    model,
     components=[SpaceDrawer, make_plot_component(["Trader", "Price"])],
     model_params=model_params,
     name="Sugarscape {G1, M, T}",

mesa/examples/basic/boid_flockers/app.py

@@ -12,6 +12,11 @@ def boid_draw(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "population": Slider(
         label="Number of boids",
         value=100,

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -1,10 +1,13 @@
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
+from mesa.mesa_logging import DEBUG, log_to_stderr
 from mesa.visualization import (
     SolaraViz,
     make_plot_component,
     make_space_component,
 )
 
+log_to_stderr(DEBUG)
+
 
 def agent_portrayal(agent):
     color = agent.wealth  # we are using a colormap to translate wealth to color
@@ -12,6 +15,11 @@ def agent_portrayal(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "n": {
         "type": "SliderInt",
         "value": 50,
@@ -20,11 +28,6 @@ model_params = {
         "max": 100,
         "step": 1,
     },
-    "seed": {
-        "type": "InputText",
-        "value": 42,
-        "label": "Random Seed",
-    },
     "width": 10,
     "height": 10,
 }

mesa/examples/basic/boltzmann_wealth_model/st_app.py

@@ -68,7 +68,7 @@ if run:
     for i in range(num_ticks):
         model.step()
         my_bar.progress((i / num_ticks), text="Simulation progress")
-        placeholder.text("Step = %d" % i)
+        placeholder.text(f"Step = {i}")
         for cell in model.grid.coord_iter():
             cell_content, (x, y) = cell
             agent_count = len(cell_content)

mesa/examples/basic/conways_game_of_life/app.py

@@ -20,6 +20,11 @@ def post_process(ax):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "width": {
         "type": "SliderInt",
         "value": 50,

mesa/examples/basic/conways_game_of_life/st_app.py

@@ -49,9 +49,9 @@ if run:
     for i in range(num_ticks):
         model.step()
         my_bar.progress((i / num_ticks), text="Simulation progress")
-        placeholder.text("Step = %d" % i)
+        placeholder.text(f"Step = {i}")
         for contents, (x, y) in model.grid.coord_iter():
-            # print('x:',x,'y:',y, 'state:',contents)
+            # print(f"x: {x}, y: {y}, state: {contents}")
             selected_row = df_grid[(df_grid["x"] == x) & (df_grid["y"] == y)]
             df_grid.loc[selected_row.index, "state"] = (
                 contents.state

mesa/examples/basic/schelling/app.py

@@ -19,6 +19,11 @@ def agent_portrayal(agent):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "density": Slider("Agent density", 0.8, 0.1, 1.0, 0.1),
     "minority_pc": Slider("Fraction minority", 0.2, 0.0, 1.0, 0.05),
     "homophily": Slider("Homophily", 3, 0, 8, 1),

mesa/examples/basic/virus_on_network/app.py

@@ -35,6 +35,11 @@ def get_resistant_susceptible_ratio(model):
 
 
 model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
     "num_nodes": Slider(
         label="Number of agents",
         value=10,

mesa/experimental/__init__.py

@@ -1,13 +1,20 @@
-"""Experimental init."""
+"""Experimental features package for Mesa.
 
-from mesa.experimental import cell_space
+This package contains modules that are under active development and testing. These
+features are provided to allow early access and feedback from the Mesa community, but
+their APIs may change between releases without following semantic versioning.
 
-try:
-    from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
+Current experimental modules:
+    cell_space: Alternative API for discrete spaces with cell-centric functionality
+    devs: Discrete event simulation system for scheduling events at arbitrary times
+    mesa_signals: Reactive programming capabilities for tracking state changes
 
-    __all__ = ["cell_space", "JupyterViz", "Slider", "SolaraViz", "make_text"]
-except ImportError:
-    print(
-        "Could not import SolaraViz. If you need it, install with 'pip install --pre mesa[viz]'"
-    )
-    __all__ = ["cell_space"]
+Notes:
+    - Features in this package may be changed or removed without notice
+    - APIs are not guaranteed to be stable between releases
+    - Features graduate from experimental status once their APIs are stabilized
+"""
+
+from mesa.experimental import cell_space, devs, mesa_signals
+
+__all__ = ["cell_space", "devs", "mesa_signals"]

mesa/experimental/cell_space/__init__.py

@@ -1,8 +1,18 @@
-"""Cell spaces.
+"""Cell spaces for active, property-rich spatial modeling in Mesa.
 
-Cell spaces offer an alternative API for discrete spaces. It is experimental and under development. The API is more
-expressive that the default grids available in `mesa.space`.
+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.experimental.cell_space.cell import Cell
@@ -20,19 +30,21 @@ from mesa.experimental.cell_space.grid import (
     OrthogonalVonNeumannGrid,
 )
 from mesa.experimental.cell_space.network import Network
+from mesa.experimental.cell_space.property_layer import PropertyLayer
 from mesa.experimental.cell_space.voronoi import VoronoiGrid
 
 __all__ = [
-    "CellCollection",
     "Cell",
     "CellAgent",
-    "Grid2DMovingAgent",
-    "FixedAgent",
+    "CellCollection",
     "DiscreteSpace",
+    "FixedAgent",
     "Grid",
+    "Grid2DMovingAgent",
     "HexGrid",
+    "Network",
     "OrthogonalMooreGrid",
     "OrthogonalVonNeumannGrid",
-    "Network",
+    "PropertyLayer",
     "VoronoiGrid",
 ]

mesa/experimental/cell_space/cell.py

@@ -1,15 +1,25 @@
-"""The Cell in a cell space."""
+"""Cells are positions in space that can have properties and contain agents.
+
+A cell represents a location that can:
+- Have properties (like temperature or resources)
+- Track and limit the agents it contains
+- Connect to neighboring cells
+- Provide neighborhood information
+
+Cells form the foundation of the cell space system, enabling rich spatial
+environments where both location properties and agent behaviors matter. They're
+useful for modeling things like varying terrain, infrastructure capacity, or
+environmental conditions.
+"""
 
 from __future__ import annotations
 
-from collections.abc import Callable
 from functools import cache, cached_property
 from random import Random
-from typing import TYPE_CHECKING, Any
+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.space import PropertyLayer
 
 if TYPE_CHECKING:
     from mesa.agent import Agent
@@ -24,31 +34,20 @@ class Cell:
         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",
+        "__dict__",
         "agents",
         "capacity",
+        "connections",
+        "coordinate",
         "properties",
         "random",
-        "_mesa_property_layers",
-        "__dict__",
     ]
 
-    # 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: Coordinate,
@@ -70,9 +69,10 @@ class Cell:
             Agent
         ] = []  # TODO:: change to AgentSet or weakrefs? (neither is very performant, )
         self.capacity: int | None = capacity
-        self.properties: dict[Coordinate, object] = {}
+        self.properties: dict[
+            Coordinate, object
+        ] = {}  # fixme still used by voronoi mesh
         self.random = random
-        self._mesa_property_layers: dict[str, PropertyLayer] = {}
 
     def connect(self, other: Cell, key: Coordinate | None = None) -> None:
         """Connects this cell to another cell.
@@ -105,6 +105,7 @@ class Cell:
 
         """
         n = len(self.agents)
+        self.empty = False
 
         if self.capacity and n >= self.capacity:
             raise Exception(
@@ -121,6 +122,7 @@ class Cell:
 
         """
         self.agents.remove(agent)
+        self.empty = self.is_empty
 
     @property
     def is_empty(self) -> bool:
@@ -195,23 +197,6 @@ class Cell:
                 neighborhood.pop(self, None)
             return neighborhood
 
-    # PropertyLayer methods
-    def get_property(self, property_name: str) -> Any:
-        """Get the value of a property."""
-        return self._mesa_property_layers[property_name].data[self.coordinate]
-
-    def set_property(self, property_name: str, value: Any):
-        """Set the value of a property."""
-        self._mesa_property_layers[property_name].set_cell(self.coordinate, value)
-
-    def modify_property(
-        self, property_name: str, operation: Callable, value: Any = None
-    ):
-        """Modify the value of a property."""
-        self._mesa_property_layers[property_name].modify_cell(
-            self.coordinate, operation, value
-        )
-
     def __getstate__(self):
         """Return state of the Cell with connections set to empty."""
         # fixme, once we shift to 3.11, replace this with super. __getstate__

mesa/experimental/cell_space/cell_agent.py

@@ -1,4 +1,15 @@
-"""An agent with movement methods for cell spaces."""
+"""Agents that understand how to exist in and move through cell spaces.
+
+Provides specialized agent classes that handle cell occupation, movement, and
+proper registration:
+- CellAgent: Mobile agents that can move between cells
+- FixedAgent: Immobile agents permanently fixed to cells
+- Grid2DMovingAgent: Agents with grid-specific movement capabilities
+
+These classes ensure consistent agent-cell relationships and proper state management
+as agents move through the space. They can be used directly or as examples for
+creating custom cell-aware agents.
+"""
 
 from __future__ import annotations
 

mesa/experimental/cell_space/cell_collection.py

@@ -1,4 +1,17 @@
-"""CellCollection class."""
+"""Collection class for managing and querying groups of cells.
+
+The CellCollection class provides a consistent interface for operating on multiple
+cells, supporting:
+- Filtering and selecting cells based on conditions
+- Random cell and agent selection
+- Access to contained agents
+- Group operations
+
+This is useful for implementing area effects, zones, or any operation that needs
+to work with multiple cells as a unit. The collection handles efficient iteration
+and agent access across cells. The class is used throughout the cell space
+implementation to represent neighborhoods, selections, and other cell groupings.
+"""
 
 from __future__ import annotations