Mesa 2.4.0__py3-none-any.whl → 3.0.0a0__py3-none-any.whl

mesa/datacollection.py

@@ -3,30 +3,28 @@ Mesa Data Collection Module
 ===========================
 
 DataCollector is meant to provide a simple, standard way to collect data
-generated by a Mesa model. It collects four types of data: model-level data,
-agent-level data, agent-type-level data, and tables.
+generated by a Mesa model. It collects three types of data: model-level data,
+agent-level data, and tables.
 
-A DataCollector is instantiated with three dictionaries of reporter names and
-associated variable names or functions for each, one for model-level data,
-one for agent-level data, and one for agent-type-level data; a fourth dictionary
-provides table names and columns. Variable names are converted into functions
-which retrieve attributes of that name.
+A DataCollector is instantiated with two dictionaries of reporter names and
+associated variable names or functions for each, one for model-level data and
+one for agent-level data; a third dictionary provides table names and columns.
+Variable names are converted into functions which retrieve attributes of that
+name.
 
 When the collect() method is called, each model-level function is called, with
 the model as the argument, and the results associated with the relevant
-variable. Then the agent-level functions are called on each agent, and the
-agent-type-level functions are called on each agent of the specified type.
+variable. Then the agent-level functions are called on each agent.
 
 Additionally, other objects can write directly to tables by passing in an
 appropriate dictionary object for a table row.
 
+The DataCollector then stores the data it collects in dictionaries:
     * model_vars maps each reporter to a list of its values
     * tables maps each table to a dictionary, with each column as a key with a
       list as its value.
-    * _agent_records maps each model step to a list of each agent's id
+    * _agent_records maps each model step to a list of each agents id
       and its values.
-    * _agenttype_records maps each model step to a dictionary of agent types,
-      each containing a list of each agent's id and its values.
 
 Finally, DataCollector can create a pandas DataFrame from each collection.
 
@@ -38,7 +36,6 @@ The default DataCollector here makes several assumptions:
 import contextlib
 import itertools
 import types
-import warnings
 from copy import deepcopy
 from functools import partial
 
@@ -49,25 +46,24 @@ with contextlib.suppress(ImportError):
 class DataCollector:
     """Class for collecting data generated by a Mesa model.
 
-    A DataCollector is instantiated with dictionaries of names of model-,
-    agent-, and agent-type-level variables to collect, associated with
-    attribute names or functions which actually collect them. When the
-    collect(...) method is called, it collects these attributes and executes
-    these functions one by one and stores the results.
+    A DataCollector is instantiated with dictionaries of names of model- and
+    agent-level variables to collect, associated with attribute names or
+    functions which actually collect them. When the collect(...) method is
+    called, it collects these attributes and executes these functions one by
+    one and stores the results.
     """
 
     def __init__(
         self,
         model_reporters=None,
         agent_reporters=None,
-        agenttype_reporters=None,
         tables=None,
     ):
-        """Instantiate a DataCollector with lists of model, agent, and agent-type reporters.
-
-        Both model_reporters, agent_reporters, and agenttype_reporters accept a
-        dictionary mapping a variable name to either an attribute name, a function,
-        a method of a class/instance, or a function with parameters placed in a list.
+        """
+        Instantiate a DataCollector with lists of model and agent reporters.
+        Both model_reporters and agent_reporters accept a dictionary mapping a
+        variable name to either an attribute name, a function, a method of a class/instance,
+        or a function with parameters placed in a list.
 
         Model reporters can take four types of arguments:
         1. Lambda function:
@@ -91,10 +87,6 @@ class DataCollector:
         4. Functions with parameters placed in a list:
            {"Agent_Function": [function, [param_1, param_2]]}
 
-        Agenttype reporters take a dictionary mapping agent types to dictionaries
-        of reporter names and attributes/funcs/methods, similar to agent_reporters:
-           {Wolf: {"energy": lambda a: a.energy}}
-
         The tables arg accepts a dictionary mapping names of tables to lists of
         columns. For example, if we want to allow agents to write their age
         when they are destroyed (to keep track of lifespans), it might look
@@ -104,8 +96,6 @@ class DataCollector:
         Args:
             model_reporters: Dictionary of reporter names and attributes/funcs/methods.
             agent_reporters: Dictionary of reporter names and attributes/funcs/methods.
-            agenttype_reporters: Dictionary of agent types to dictionaries of
-                                 reporter names and attributes/funcs/methods.
             tables: Dictionary of table names to lists of column names.
 
         Notes:
@@ -115,11 +105,9 @@ class DataCollector:
         """
         self.model_reporters = {}
         self.agent_reporters = {}
-        self.agenttype_reporters = {}
 
         self.model_vars = {}
         self._agent_records = {}
-        self._agenttype_records = {}
         self.tables = {}
 
         if model_reporters is not None:
@@ -130,11 +118,6 @@ class DataCollector:
             for name, reporter in agent_reporters.items():
                 self._new_agent_reporter(name, reporter)
 
-        if agenttype_reporters is not None:
-            for agent_type, reporters in agenttype_reporters.items():
-                for name, reporter in reporters.items():
-                    self._new_agenttype_reporter(agent_type, name, reporter)
-
         if tables is not None:
             for name, columns in tables.items():
                 self._new_table(name, columns)
@@ -182,38 +165,6 @@ class DataCollector:
 
         self.agent_reporters[name] = reporter
 
-    def _new_agenttype_reporter(self, agent_type, name, reporter):
-        """Add a new agent-type-level reporter to collect.
-
-        Args:
-            agent_type: The type of agent to collect data for.
-            name: Name of the agent-type-level variable to collect.
-            reporter: Attribute string, function object, method of a class/instance, or
-                      function with parameters placed in a list that returns the
-                      variable when given an agent instance.
-        """
-        if agent_type not in self.agenttype_reporters:
-            self.agenttype_reporters[agent_type] = {}
-
-        # Use the same logic as _new_agent_reporter
-        if isinstance(reporter, str):
-            attribute_name = reporter
-
-            def attr_reporter(agent):
-                return getattr(agent, attribute_name, None)
-
-            reporter = attr_reporter
-
-        elif isinstance(reporter, list):
-            func, params = reporter[0], reporter[1]
-
-            def func_with_params(agent):
-                return func(agent, *params)
-
-            reporter = func_with_params
-
-        self.agenttype_reporters[agent_type][name] = reporter
-
     def _new_table(self, table_name, table_columns):
         """Add a new table that objects can write to.
 
@@ -241,40 +192,12 @@ class DataCollector:
         )
         return agent_records
 
-    def _record_agenttype(self, model, agent_type):
-        """Record agent-type data in a mapping of functions and agents."""
-        rep_funcs = self.agenttype_reporters[agent_type].values()
-
-        def get_reports(agent):
-            _prefix = (agent.model._steps, agent.unique_id)
-            reports = tuple(rep(agent) for rep in rep_funcs)
-            return _prefix + reports
-
-        agent_types = model.agent_types
-        if agent_type in agent_types:
-            agents = model.agents_by_type[agent_type]
-        else:
-            from mesa import Agent
-
-            if issubclass(agent_type, Agent):
-                agents = [
-                    agent for agent in model.agents if isinstance(agent, agent_type)
-                ]
-            else:
-                # Raise error if agent_type is not in model.agent_types
-                raise ValueError(
-                    f"Agent type {agent_type} is not recognized as an Agent type in the model or Agent subclass. Use an Agent (sub)class, like {agent_types}."
-                )
-
-        agenttype_records = map(get_reports, agents)
-        return agenttype_records
-
     def collect(self, model):
         """Collect all the data for the given model object."""
         if self.model_reporters:
             for var, reporter in self.model_reporters.items():
                 # Check if lambda or partial function
-                if isinstance(reporter, (types.LambdaType, partial)):
+                if isinstance(reporter, types.LambdaType | partial):
                     # Use deepcopy to store a copy of the data,
                     # preventing references from being updated across steps.
                     self.model_vars[var].append(deepcopy(reporter(model)))
@@ -295,14 +218,6 @@ class DataCollector:
             agent_records = self._record_agents(model)
             self._agent_records[model._steps] = list(agent_records)
 
-        if self.agenttype_reporters:
-            self._agenttype_records[model._steps] = {}
-            for agent_type in self.agenttype_reporters:
-                agenttype_records = self._record_agenttype(model, agent_type)
-                self._agenttype_records[model._steps][agent_type] = list(
-                    agenttype_records
-                )
-
     def add_table_row(self, table_name, row, ignore_missing=False):
         """Add a row dictionary to a specific table.
 
@@ -359,36 +274,6 @@ class DataCollector:
         )
         return df
 
-    def get_agenttype_vars_dataframe(self, agent_type):
-        """Create a pandas DataFrame from the agent-type variables for a specific agent type.
-        The DataFrame has one column for each variable, with two additional
-        columns for tick and agent_id.
-        Args:
-            agent_type: The type of agent to get the data for.
-        """
-        # Check if self.agenttype_reporters dictionary is empty for this agent type, if so return empty DataFrame
-        if agent_type not in self.agenttype_reporters:
-            warnings.warn(
-                f"No agent-type reporters have been defined for {agent_type} in the DataCollector, returning empty DataFrame.",
-                UserWarning,
-                stacklevel=2,
-            )
-            return pd.DataFrame()
-
-        all_records = itertools.chain.from_iterable(
-            records[agent_type]
-            for records in self._agenttype_records.values()
-            if agent_type in records
-        )
-        rep_names = list(self.agenttype_reporters[agent_type])
-
-        df = pd.DataFrame.from_records(
-            data=all_records,
-            columns=["Step", "AgentID", *rep_names],
-            index=["Step", "AgentID"],
-        )
-        return df
-
     def get_table_dataframe(self, table_name):
         """Create a pandas DataFrame from a particular table.
 

mesa/experimental/__init__.py

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

mesa/experimental/cell_space/cell_collection.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 import itertools
-from collections.abc import Iterable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from functools import cached_property
 from random import Random
-from typing import TYPE_CHECKING, Callable, Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar
 
 if TYPE_CHECKING:
     from mesa.experimental.cell_space.cell import Cell

mesa/experimental/cell_space/grid.py

@@ -60,7 +60,7 @@ class Grid(DiscreteSpace, Generic[T]):
             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)):
+        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:

mesa/experimental/cell_space/network.py

@@ -1,5 +1,5 @@
 from random import Random
-from typing import Any, Optional
+from typing import Any
 
 from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
@@ -11,8 +11,8 @@ class Network(DiscreteSpace):
     def __init__(
         self,
         G: Any,  # noqa: N803
-        capacity: Optional[int] = None,
-        random: Optional[Random] = None,
+        capacity: int | None = None,
+        random: Random | None = None,
         cell_klass: type[Cell] = Cell,
     ) -> None:
         """A Networked grid

mesa/experimental/devs/eventlist.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import itertools
+from collections.abc import Callable
 from enum import IntEnum
 from heapq import heapify, heappop, heappush
 from types import MethodType
-from typing import Any, Callable
+from typing import Any
 from weakref import WeakMethod, ref
 
 

mesa/experimental/devs/examples/epstein_civil_violence.py

@@ -261,8 +261,7 @@ class EpsteinCivilViolence(Model):
         self.active_agents = self.agents
 
     def step(self):
-        """Run one step of the model."""
-        self.active_agents.shuffle_do("step")
+        self.active_agents.shuffle(inplace=True).do("step")
 
 
 if __name__ == "__main__":

mesa/experimental/devs/examples/wolf_sheep.py

@@ -231,9 +231,8 @@ class WolfSheep(mesa.Model):
             self.grid.place_agent(patch, pos)
 
     def step(self):
-        """Perform one step of the model."""
-        self.agents_by_type[Sheep].shuffle_do("step")
-        self.agents_by_type[Wolf].shuffle_do("step")
+        self.get_agents_of_type(Sheep).shuffle(inplace=True).do("step")
+        self.get_agents_of_type(Wolf).shuffle(inplace=True).do("step")
 
 
 if __name__ == "__main__":

mesa/experimental/devs/simulator.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 import numbers
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from mesa import Model
 

mesa/model.py

@@ -8,16 +8,18 @@ Core Objects: Model
 # Remove this __future__ import once the oldest supported Python is 3.10
 from __future__ import annotations
 
+import itertools
 import random
 import warnings
+from collections import defaultdict
 
 # mypy
-from typing import Any, Union
+from typing import Any
 
 from mesa.agent import Agent, AgentSet
 from mesa.datacollection import DataCollector
 
-TimeT = Union[float, int]
+TimeT = float | int
 
 
 class Model:
@@ -31,28 +33,20 @@ class Model:
         running: A boolean indicating if the model should continue running.
         schedule: An object to manage the order and execution of agent steps.
         current_id: A counter for assigning unique IDs to agents.
+        agents_: A defaultdict mapping each agent type to a dict of its instances.
+                 This private attribute is used internally to manage agents.
 
     Properties:
-        agents: An AgentSet containing all agents in the model
+        agents: An AgentSet containing all agents in the model, generated from the _agents attribute.
         agent_types: A list of different agent types present in the model.
-        agents_by_type: A dictionary where the keys are agent types and the values are the corresponding AgentSets.
 
     Methods:
         get_agents_of_type: Returns an AgentSet of agents of the specified type.
-            Deprecated: Use agents_by_type[agenttype] instead.
         run_model: Runs the model's simulation until a defined end condition is reached.
         step: Executes a single step of the model's simulation process.
         next_id: Generates and returns the next unique identifier for an agent.
         reset_randomizer: Resets the model's random number generator with a new or existing seed.
         initialize_data_collector: Sets up the data collector for the model, requiring an initialized scheduler and agents.
-        register_agent : register an agent with the model
-        deregister_agent : remove an agent from the model
-
-    Notes:
-        Model.agents returns the AgentSet containing all agents registered with the model. Changing
-        the content of the AgentSet directly can result in strange behavior. If you want change the
-        composition of this AgentSet, ensure you operate on a copy.
-
     """
 
     def __new__(cls, *args: Any, **kwargs: Any) -> Any:
@@ -64,7 +58,6 @@ class Model:
             # advance.
             obj._seed = random.random()
         obj.random = random.Random(obj._seed)
-
         # TODO: Remove these 2 lines just before Mesa 3.0
         obj._steps = 0
         obj._time = 0
@@ -79,8 +72,7 @@ class Model:
         self.running = True
         self.schedule = None
         self.current_id = 0
-
-        self._setup_agent_registration()
+        self.agents_: defaultdict[type, dict] = defaultdict(dict)
 
         self._steps: int = 0
         self._time: TimeT = 0  # the model's clock
@@ -88,93 +80,33 @@ class Model:
     @property
     def agents(self) -> AgentSet:
         """Provides an AgentSet of all agents in the model, combining agents from all types."""
-        return self._all_agents
+
+        if hasattr(self, "_agents"):
+            return self._agents
+        else:
+            all_agents = itertools.chain.from_iterable(self.agents_.values())
+            return AgentSet(all_agents, self)
 
     @agents.setter
     def agents(self, agents: Any) -> None:
         warnings.warn(
-            "You are trying to set model.agents. In Mesa 3.0 and higher, this attribute is "
-            "used by Mesa itself, so you cannot use it directly anymore."
-            "Please adjust your code to use a different attribute name for custom agent storage.",
+            "You are trying to set model.agents. In a next release, this attribute is used "
+            "by MESA itself so you cannot use it directly anymore."
+            "Please adjust your code to use a different attribute name for custom agent storage",
             UserWarning,
             stacklevel=2,
         )
 
-    @property
-    def agent_types(self) -> list[type]:
-        """Return a list of all unique agent types registered with the model."""
-        return list(self._agents_by_type.keys())
+        self._agents = agents
 
     @property
-    def agents_by_type(self) -> dict[type[Agent], AgentSet]:
-        """A dictionary where the keys are agent types and the values are the corresponding AgentSets."""
-        return self._agents_by_type
+    def agent_types(self) -> list[type]:
+        """Return a list of different agent types."""
+        return list(self.agents_.keys())
 
     def get_agents_of_type(self, agenttype: type[Agent]) -> AgentSet:
-        """Deprecated: Retrieves an AgentSet containing all agents of the specified type."""
-        warnings.warn(
-            f"Model.get_agents_of_type() is deprecated, please replace get_agents_of_type({agenttype})"
-            f"with the property agents_by_type[{agenttype}].",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.agents_by_type[agenttype]
-
-    def _setup_agent_registration(self):
-        """helper method to initialize the agent registration datastructures"""
-        self._agents = {}  # the hard references to all agents in the model
-        self._agents_by_type: dict[
-            type[Agent], AgentSet
-        ] = {}  # a dict with an agentset for each class of agents
-        self._all_agents = AgentSet([], self)  # an agenset with all agents
-
-    def register_agent(self, agent):
-        """Register the agent with the model
-
-        Args:
-            agent: The agent to register.
-
-        Notes:
-            This method is called automatically by ``Agent.__init__``, so there is no need to use this
-            if you are subclassing Agent and calling its super in the ``__init__`` method.
-
-        """
-        if not hasattr(self, "_agents"):
-            self._setup_agent_registration()
-
-            warnings.warn(
-                "The Mesa Model class was not initialized. In the future, you need to explicitly initialize "
-                "the Model by calling super().__init__() on initialization.",
-                FutureWarning,
-                stacklevel=2,
-            )
-
-        self._agents[agent] = None
-
-        # because AgentSet requires model, we cannot use defaultdict
-        # tricks with a function won't work because model then cannot be pickled
-        try:
-            self._agents_by_type[type(agent)].add(agent)
-        except KeyError:
-            self._agents_by_type[type(agent)] = AgentSet(
-                [
-                    agent,
-                ],
-                self,
-            )
-
-        self._all_agents.add(agent)
-
-    def deregister_agent(self, agent):
-        """Deregister the agent with the model
-
-        Notes::
-        This method is called automatically by ``Agent.remove``
-
-        """
-        del self._agents[agent]
-        self._agents_by_type[type(agent)].remove(agent)
-        self._all_agents.remove(agent)
+        """Retrieves an AgentSet containing all agents of the specified type."""
+        return AgentSet(self.agents_[agenttype].keys(), self)
 
     def run_model(self) -> None:
         """Run the model until the end condition is reached. Overload as
@@ -212,7 +144,6 @@ class Model:
         self,
         model_reporters=None,
         agent_reporters=None,
-        agenttype_reporters=None,
         tables=None,
     ) -> None:
         if not hasattr(self, "schedule") or self.schedule is None:
@@ -226,7 +157,6 @@ class Model:
         self.datacollector = DataCollector(
             model_reporters=model_reporters,
             agent_reporters=agent_reporters,
-            agenttype_reporters=agenttype_reporters,
             tables=tables,
         )
         # Collect data for the first time during initialization.

mesa/space.py

@@ -23,9 +23,9 @@ import inspect
 import itertools
 import math
 import warnings
-from collections.abc import Iterable, Iterator, Sequence
+from collections.abc import Callable, Iterable, Iterator, Sequence
 from numbers import Real
-from typing import Any, Callable, TypeVar, Union, cast, overload
+from typing import Any, TypeVar, cast, overload
 from warnings import warn
 
 with contextlib.suppress(ImportError):
@@ -42,12 +42,12 @@ _types_integer = (int, np.integer)
 
 Coordinate = tuple[int, int]
 # used in ContinuousSpace
-FloatCoordinate = Union[tuple[float, float], npt.NDArray[float]]
+FloatCoordinate = tuple[float, float] | npt.NDArray[float]
 NetworkCoordinate = int
 
-Position = Union[Coordinate, FloatCoordinate, NetworkCoordinate]
+Position = Coordinate | FloatCoordinate | NetworkCoordinate
 
-GridContent = Union[Agent, None]
+GridContent = Agent | None
 MultiGridContent = list[Agent]
 
 F = TypeVar("F", bound=Callable[..., Any])
@@ -459,21 +459,15 @@ class _Grid:
             elif selection == "closest":
                 current_pos = agent.pos
                 # Find the closest position without sorting all positions
-                # TODO: See if this method can be optimized further
-                closest_pos = []
+                closest_pos = None
                 min_distance = float("inf")
                 agent.random.shuffle(pos)
                 for p in pos:
                     distance = self._distance_squared(p, current_pos)
                     if distance < min_distance:
                         min_distance = distance
-                        closest_pos.clear()
-                        closest_pos.append(p)
-                    elif distance == min_distance:
-                        closest_pos.append(p)
-
-                chosen_pos = agent.random.choice(closest_pos)
-
+                        closest_pos = p
+                chosen_pos = closest_pos
             else:
                 raise ValueError(
                     f"Invalid selection method {selection}. Choose 'random' or 'closest'."
@@ -592,7 +586,7 @@ class PropertyLayer:
         aggregate_property(operation): Performs an aggregate operation over all cells.
     """
 
-    propertylayer_experimental_warning_given = False
+    agentset_experimental_warning_given = False
 
     def __init__(
         self, name: str, width: int, height: int, default_value, dtype=np.float64
@@ -639,14 +633,14 @@ class PropertyLayer:
 
         self.data = np.full((width, height), default_value, dtype=dtype)
 
-        if not self.__class__.propertylayer_experimental_warning_given:
+        if not self.__class__.agentset_experimental_warning_given:
             warnings.warn(
                 "The new PropertyLayer and _PropertyGrid classes 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
+            self.__class__.agentset_experimental_warning_given = True
 
     def set_cell(self, position: Coordinate, value):
         """

mesa/time.py

@@ -30,14 +30,12 @@ from collections import defaultdict
 from collections.abc import Iterable
 
 # mypy
-from typing import Union
-
 from mesa.agent import Agent, AgentSet
 from mesa.model import Model
 
 # BaseScheduler has a self.time of int, while
 # StagedActivation has a self.time of float
-TimeT = Union[float, int]
+TimeT = float | int
 
 
 class BaseScheduler: