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

mesa/__init__.py

@@ -8,7 +8,6 @@ import datetime
 
 import mesa.space as space
 import mesa.time as time
-import mesa.visualization as visualization
 from mesa.agent import Agent
 from mesa.batchrunner import batch_run
 from mesa.datacollection import DataCollector
@@ -19,14 +18,13 @@ __all__ = [
     "Agent",
     "time",
     "space",
-    "visualization",
     "DataCollector",
     "batch_run",
     "experimental",
 ]
 
 __title__ = "mesa"
-__version__ = "2.4.0"
+__version__ = "3.0.0a0"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/agent.py

@@ -14,11 +14,11 @@ import operator
 import warnings
 import weakref
 from collections import defaultdict
-from collections.abc import Hashable, Iterable, Iterator, MutableSet, Sequence
+from collections.abc import Callable, Iterable, Iterator, MutableSet, Sequence
 from random import Random
 
 # mypy
-from typing import TYPE_CHECKING, Any, Callable, Literal, overload
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     # We ensure that these are not imported during runtime to prevent cyclic
@@ -49,12 +49,25 @@ class Agent:
         self.model = model
         self.pos: Position | None = None
 
-        self.model.register_agent(self)
+        # register agent
+        try:
+            self.model.agents_[type(self)][self] = None
+        except AttributeError:
+            # model super has not been called
+            self.model.agents_ = defaultdict(dict)
+            self.model.agents_[type(self)][self] = None
+            self.model.agentset_experimental_warning_given = False
+
+            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,
+            )
 
     def remove(self) -> None:
         """Remove and delete the agent from the model."""
         with contextlib.suppress(KeyError):
-            self.model.deregister_agent(self)
+            self.model.agents_[type(self)].pop(self)
 
     def step(self) -> None:
         """A single step of the agent."""
@@ -116,10 +129,9 @@ class AgentSet(MutableSet, Sequence):
     def select(
         self,
         filter_func: Callable[[Agent], bool] | None = None,
-        at_most: int | float = float("inf"),
+        n: int = 0,
         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.
@@ -127,47 +139,29 @@ class AgentSet(MutableSet, Sequence):
         Args:
             filter_func (Callable[[Agent], bool], optional): A function that takes an Agent and returns True if the
                 agent should be included in the result. Defaults to None, meaning no filtering is applied.
-            at_most (int | float, optional): The maximum amount of agents to select. Defaults to infinity.
-              - If an integer, at most the first number of matching agents are selected.
-              - If a float between 0 and 1, at most that fraction of original the agents are selected.
+            n (int, optional): The number of agents to select. If 0, all matching agents are selected. Defaults to 0.
             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.
 
         Returns:
             AgentSet: A new AgentSet containing the selected agents, unless inplace is True, in which case the current AgentSet is updated.
-
-        Notes:
-            - 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. 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:
+        if filter_func is None and agent_type is None and n == 0:
             return self if inplace else copy.copy(self)
 
-        # Check if at_most is of type float
-        if at_most <= 1.0 and isinstance(at_most, float):
-            at_most = int(len(self) * at_most)  # Note that it rounds down (floor)
-
-        def agent_generator(filter_func, agent_type, at_most):
+        def agent_generator(filter_func=None, agent_type=None, n=0):
             count = 0
             for agent in self:
-                if count >= at_most:
-                    break
                 if (not filter_func or filter_func(agent)) and (
                     not agent_type or isinstance(agent, agent_type)
                 ):
                     yield agent
                     count += 1
+                    if 0 < n <= count:
+                        break
 
-        agents = agent_generator(filter_func, agent_type, at_most)
+        agents = agent_generator(filter_func, agent_type, n)
 
         return AgentSet(agents, self.model) if not inplace else self._update(agents)
 
@@ -232,194 +226,53 @@ class AgentSet(MutableSet, Sequence):
         self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
         return self
 
-    def do(self, method: str | Callable, *args, **kwargs) -> AgentSet:
+    def do(
+        self, method_name: str, *args, return_results: bool = False, **kwargs
+    ) -> AgentSet | list[Any]:
         """
-        Invoke a method or function on each agent in the AgentSet.
+        Invoke a method on each agent in the AgentSet.
 
         Args:
-            method (str, callable): the callable to do on each agent
-
-                                        * in case of str, the name of the method to call on each agent.
-                                        * in case of callable, the function to be called with each agent as first argument
-
-            *args: Variable length argument list passed to the callable being called.
-            **kwargs: Arbitrary keyword arguments passed to the callable being called.
+            method_name (str): The name of the method to call on each agent.
+            return_results (bool, optional): If True, returns the results of the method calls; otherwise, returns the AgentSet itself. Defaults to False, so you can chain method calls.
+            *args: Variable length argument list passed to the method being called.
+            **kwargs: Arbitrary keyword arguments passed to the method being called.
 
         Returns:
-            AgentSet | list[Any]: The results of the callable calls if return_results is True, otherwise the AgentSet itself.
+            AgentSet | list[Any]: The results of the method 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. Use AgenSet.do in case of return_results=False, and "
-                "AgentSet.map in case of return_results=True",
-                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():
-                if (agent := agentref()) is not None:
-                    getattr(agent, method)(*args, **kwargs)
-        else:
-            for agentref in self._agents.keyrefs():
-                if (agent := agentref()) is not None:
-                    method(agent, *args, **kwargs)
-
-        return self
-
-    def shuffle_do(self, method: str | Callable, *args, **kwargs) -> AgentSet:
-        """Shuffle the agents in the AgentSet and then invoke a method or function on each agent.
-
-        It's a fast, optimized version of calling shuffle() followed by do().
-        """
-        agents = list(self._agents.keys())
-        self.random.shuffle(agents)
-
-        if isinstance(method, str):
-            for agent in agents:
-                getattr(agent, method)(*args, **kwargs)
-        else:
-            for agent in agents:
-                method(agent, *args, **kwargs)
+        res = [
+            getattr(agent, method_name)(*args, **kwargs)
+            for agentref in self._agents.keyrefs()
+            if (agent := agentref()) is not None
+        ]
 
-        return self
+        return res if return_results else self
 
-    def map(self, method: str | Callable, *args, **kwargs) -> list[Any]:
-        """
-        Invoke a method or function on each agent in the AgentSet and return the results.
-
-        Args:
-            method (str, callable): the callable to apply on each agent
-
-                                        * in case of str, the name of the method to call on each agent.
-                                        * in case of callable, the function to be called with each agent as first argument
-
-            *args: Variable length argument list passed to the callable being called.
-            **kwargs: Arbitrary keyword arguments passed to the callable being called.
-
-        Returns:
-           list[Any]: The results of the callable calls
-        """
-        # we iterate over the actual weakref keys and check if weakref is alive before calling the method
-        if isinstance(method, str):
-            res = [
-                getattr(agent, method)(*args, **kwargs)
-                for agentref in self._agents.keyrefs()
-                if (agent := agentref()) is not None
-            ]
-        else:
-            res = [
-                method(agent, *args, **kwargs)
-                for agentref in self._agents.keyrefs()
-                if (agent := agentref()) is not None
-            ]
-
-        return res
-
-    def agg(self, attribute: str, func: Callable) -> Any:
-        """
-        Aggregate an attribute of all agents in the AgentSet using a specified function.
-
-        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).
-
-        Returns:
-            Any: The result of applying the function to the attribute values. Often a single value.
-        """
-        values = self.get(attribute)
-        return func(values)
-
-    @overload
-    def get(
-        self,
-        attr_names: str,
-        handle_missing: Literal["error", "default"] = "error",
-        default_value: Any = None,
-    ) -> list[Any]: ...
-
-    @overload
-    def get(
-        self,
-        attr_names: list[str],
-        handle_missing: Literal["error", "default"] = "error",
-        default_value: Any = None,
-    ) -> list[list[Any]]: ...
-
-    def get(
-        self,
-        attr_names,
-        handle_missing="error",
-        default_value=None,
-    ):
+    def get(self, attr_names: str | list[str]) -> list[Any]:
         """
         Retrieve the specified attribute(s) from each agent in the AgentSet.
 
         Args:
             attr_names (str | list[str]): The name(s) of the attribute(s) to retrieve from each agent.
-            handle_missing (str, optional): How to handle missing attributes. Can be:
-                                            - 'error' (default): raises an AttributeError if attribute is missing.
-                                            - 'default': returns the specified default_value.
-            default_value (Any, optional): The default value to return if 'handle_missing' is set to 'default'
-                                           and the agent does not have the attribute.
 
         Returns:
-            list[Any]: A list with the attribute value for each agent if attr_names is a str.
-            list[list[Any]]: A list with a lists of attribute values for each agent if attr_names is a list of str.
+            list[Any]: A list with the attribute value for each agent in the set if attr_names is a str
+            list[list[Any]]: A list with a list of attribute values for each agent in the set if attr_names is a list of str
 
         Raises:
-            AttributeError: If 'handle_missing' is 'error' and the agent does not have the specified attribute(s).
-            ValueError: If an unknown 'handle_missing' option is provided.
-        """
-        is_single_attr = isinstance(attr_names, str)
-
-        if handle_missing == "error":
-            if is_single_attr:
-                return [getattr(agent, attr_names) for agent in self._agents]
-            else:
-                return [
-                    [getattr(agent, attr) for attr in attr_names]
-                    for agent in self._agents
-                ]
-
-        elif handle_missing == "default":
-            if is_single_attr:
-                return [
-                    getattr(agent, attr_names, default_value) for agent in self._agents
-                ]
-            else:
-                return [
-                    [getattr(agent, attr, default_value) for attr in attr_names]
-                    for agent in self._agents
-                ]
+            AttributeError if an agent does not have the specified attribute(s)
 
-        else:
-            raise ValueError(
-                f"Unknown handle_missing option: {handle_missing}, "
-                "should be one of 'error' or 'default'"
-            )
-
-    def set(self, attr_name: str, value: Any) -> AgentSet:
         """
-        Set a specified attribute to a given value for all agents in the AgentSet.
-
-        Args:
-            attr_name (str): The name of the attribute to set.
-            value (Any): The value to set the attribute to.
 
-        Returns:
-            AgentSet: The AgentSet instance itself, after setting the attribute.
-        """
-        for agent in self:
-            setattr(agent, attr_name, value)
-        return self
+        if isinstance(attr_names, str):
+            return [getattr(agent, attr_names) for agent in self._agents]
+        else:
+            return [
+                [getattr(agent, attr_name) for attr_name in attr_names]
+                for agent in self._agents
+            ]
 
     def __getitem__(self, item: int | slice) -> Agent:
         """
@@ -503,139 +356,7 @@ class AgentSet(MutableSet, Sequence):
         """
         return self.model.random
 
-    def groupby(self, by: Callable | str, result_type: str = "agentset") -> GroupBy:
-        """
-        Group agents by the specified attribute or return from the callable
-
-        Args:
-            by (Callable, str): used to determine what to group agents by
-
-                                * if ``by`` is a callable, it will be called for each agent and the return is used
-                                  for grouping
-                                * if ``by`` is a str, it should refer to an attribute on the agent and the value
-                                  of this attribute will be used for grouping
-            result_type (str, optional): The datatype for the resulting groups {"agentset", "list"}
-        Returns:
-            GroupBy
-
-
-        Notes:
-        There might be performance benefits to using `result_type='list'` if you don't need the advanced functionality
-        of an AgentSet.
-
-        """
-        groups = defaultdict(list)
-
-        if isinstance(by, Callable):
-            for agent in self:
-                groups[by(agent)].append(agent)
-        else:
-            for agent in self:
-                groups[getattr(agent, by)].append(agent)
-
-        if result_type == "agentset":
-            return GroupBy(
-                {k: AgentSet(v, model=self.model) for k, v in groups.items()}
-            )
-        else:
-            return GroupBy(groups)
-
-    # consider adding for performance reasons
-    # for Sequence: __reversed__, index, and count
-    # for MutableSet clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
-
-
-class GroupBy:
-    """Helper class for AgentSet.groupby
-
-
-    Attributes:
-        groups (dict): A dictionary with the group_name as key and group as values
-
-    """
-
-    def __init__(self, groups: dict[Any, list | AgentSet]):
-        self.groups: dict[Any, list | AgentSet] = groups
-
-    def map(self, method: Callable | str, *args, **kwargs) -> dict[Any, Any]:
-        """Apply the specified callable to each group and return the results.
-
-        Args:
-            method (Callable, str): The callable to apply to each group,
-
-                                    * if ``method`` is a callable, it will be called it will be called with the group as first argument
-                                    * if ``method`` is a str, it should refer to a method on the group
-
-                                    Additional arguments and keyword arguments will be passed on to the callable.
-
-        Returns:
-            dict with group_name as key and the return of the method as value
-
-        Notes:
-            this method is useful for methods or functions that do return something. It
-            will break method chaining. For that, use ``do`` instead.
-
-        """
-        if isinstance(method, str):
-            return {
-                k: getattr(v, method)(*args, **kwargs) for k, v in self.groups.items()
-            }
-        else:
-            return {k: method(v, *args, **kwargs) for k, v in self.groups.items()}
-
-    def do(self, method: Callable | str, *args, **kwargs) -> GroupBy:
-        """Apply the specified callable to each group
-
-        Args:
-            method (Callable, str): The callable to apply to each group,
-
-                                    * if ``method`` is a callable, it will be called it will be called with the group as first argument
-                                    * if ``method`` is a str, it should refer to a method on the group
-
-                                    Additional arguments and keyword arguments will be passed on to the callable.
-
-        Returns:
-            the original GroupBy instance
-
-        Notes:
-            this method is useful for methods or functions that don't return anything and/or
-            if you want to chain multiple do calls
-
-        """
-        if isinstance(method, str):
-            for v in self.groups.values():
-                getattr(v, method)(*args, **kwargs)
-        else:
-            for v in self.groups.values():
-                method(v, *args, **kwargs)
-
-        return self
-
-    def count(self) -> dict[Any, int]:
-        """Return the count of agents in each group.
-
-        Returns:
-            dict: A dictionary mapping group names to the number of agents in each group.
-        """
-        return {k: len(v) for k, v in self.groups.items()}
-
-    def agg(self, attr_name: str, func: Callable) -> dict[Hashable, Any]:
-        """Aggregate the values of a specific attribute across each group using the provided function.
-
-        Args:
-            attr_name (str): The name of the attribute to aggregate.
-            func (Callable): The function to apply (e.g., sum, min, max, mean).
-
-        Returns:
-            dict[Hashable, Any]: A dictionary mapping group names to the result of applying the aggregation function.
-        """
-        return {
-            group_name: func([getattr(agent, attr_name) for agent in group])
-            for group_name, group in self.groups.items()
-        }
-
-    def __iter__(self):
-        return iter(self.groups.items())
 
-    def __len__(self):
-        return len(self.groups)
+# consider adding for performance reasons
+# for Sequence: __reversed__, index, and count
+# for MutableSet clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__

mesa/batchrunner.py

@@ -1,22 +1,19 @@
 import itertools
-import multiprocessing
 from collections.abc import Iterable, Mapping
 from functools import partial
 from multiprocessing import Pool
-from typing import Any, Optional, Union
+from typing import Any
 
 from tqdm.auto import tqdm
 
 from mesa.model import Model
 
-multiprocessing.set_start_method("spawn", force=True)
-
 
 def batch_run(
     model_cls: type[Model],
-    parameters: Mapping[str, Union[Any, Iterable[Any]]],
+    parameters: Mapping[str, Any | Iterable[Any]],
     # We still retain the Optional[int] because users may set it to None (i.e. use all CPUs)
-    number_processes: Optional[int] = 1,
+    number_processes: int | None = 1,
     iterations: int = 1,
     data_collection_period: int = -1,
     max_steps: int = 1000,
@@ -79,7 +76,7 @@ def batch_run(
 
 
 def _make_model_kwargs(
-    parameters: Mapping[str, Union[Any, Iterable[Any]]],
+    parameters: Mapping[str, Any | Iterable[Any]],
 ) -> list[dict[str, Any]]:
     """Create model kwargs from parameters dictionary.
 
@@ -135,14 +132,14 @@ def _model_run_func(
     """
     run_id, iteration, kwargs = run
     model = model_cls(**kwargs)
-    while model.running and model._steps <= max_steps:
+    while model.running and model.schedule.steps <= max_steps:
         model.step()
 
     data = []
 
-    steps = list(range(0, model._steps, data_collection_period))
-    if not steps or steps[-1] != model._steps - 1:
-        steps.append(model._steps - 1)
+    steps = list(range(0, model.schedule.steps, data_collection_period))
+    if not steps or steps[-1] != model.schedule.steps - 1:
+        steps.append(model.schedule.steps - 1)
 
     for step in steps:
         model_data, all_agents_data = _collect_data(model, step)

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/app.pytemplate

@@ -0,0 +1,27 @@
+"""
+Configure visualization elements and instantiate a server
+"""
+from mesa.visualization import JupyterViz
+
+from {{ cookiecutter.snake }}.model import {{ cookiecutter.model }}, {{ cookiecutter.agent }}  # noqa
+
+import mesa
+
+
+def circle_portrayal_example(agent):
+    return {
+        "size": 40,
+        # This is Matplotlib's color
+        "color": "tab:pink",
+    }
+
+
+model_params = {"num_agents": 10, "width": 10, "height": 10}
+
+page = JupyterViz(
+    {{cookiecutter.model}},
+    model_params,
+    measures=["num_agents"],
+    agent_portrayal=circle_portrayal_example
+)
+page  # noqa

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/{{cookiecutter.snake}}/model.pytemplate

@@ -47,7 +47,7 @@ class {{cookiecutter.model}}(mesa.Model):
             self.grid.place_agent(agent, (x, y))
 
         # example data collector
-        self.datacollector = mesa.datacollection.DataCollector()
+        self.datacollector = mesa.datacollection.DataCollector({"num_agents": "num_agents"})
 
         self.running = True
         self.datacollector.collect(self)