Mesa 3.0.0__py3-none-any.whl → 3.0.0a1__py3-none-any.whl

mesa/batchrunner.py

@@ -1,32 +1,4 @@
-"""batchrunner for running a factorial experiment design over a model.
-
-To take advantage of parallel execution of experiments, `batch_run` uses
-multiprocessing if ``number_processes`` is larger than 1. It is strongly advised
-to only run in parallel using a normal python file (so don't try to do it in a
-jupyter notebook). Moreover, best practice when using multiprocessing is to
-put the code inside an ``if __name__ == '__main__':`` code black as shown below::
-
-    from mesa.batchrunner import batch_run
-
-    params = {"width": 10, "height": 10, "N": range(10, 500, 10)}
-
-    if __name__ == '__main__':
-        results = batch_run(
-            MoneyModel,
-            parameters=params,
-            iterations=5,
-            max_steps=100,
-            number_processes=None,
-            data_collection_period=1,
-            display_progress=True,
-        )
-
-
-
-"""
-
 import itertools
-import multiprocessing
 from collections.abc import Iterable, Mapping
 from functools import partial
 from multiprocessing import Pool
@@ -36,8 +8,6 @@ from tqdm.auto import tqdm
 
 from mesa.model import Model
 
-multiprocessing.set_start_method("spawn", force=True)
-
 
 def batch_run(
     model_cls: type[Model],
@@ -51,22 +21,29 @@ def batch_run(
 ) -> list[dict[str, Any]]:
     """Batch run a mesa model with a set of parameter values.
 
-    Args:
-        model_cls (Type[Model]): The model class to batch-run
-        parameters (Mapping[str, Union[Any, Iterable[Any]]]): Dictionary with model parameters over which to run the model. You can either pass single values or iterables.
-        number_processes (int, optional): Number of processes used, by default 1. Set this to None if you want to use all CPUs.
-        iterations (int, optional): Number of iterations for each parameter combination, by default 1
-        data_collection_period (int, optional): Number of steps after which data gets collected, by default -1 (end of episode)
-        max_steps (int, optional): Maximum number of model steps after which the model halts, by default 1000
-        display_progress (bool, optional): Display batch run process, by default True
-
-    Returns:
-        List[Dict[str, Any]]
-
-    Notes:
-        batch_run assumes the model has a `datacollector` attribute that has a DataCollector object initialized.
+    Parameters
+    ----------
+    model_cls : Type[Model]
+        The model class to batch-run
+    parameters : Mapping[str, Union[Any, Iterable[Any]]],
+        Dictionary with model parameters over which to run the model. You can either pass single values or iterables.
+    number_processes : int, optional
+        Number of processes used, by default 1. Set this to None if you want to use all CPUs.
+    iterations : int, optional
+        Number of iterations for each parameter combination, by default 1
+    data_collection_period : int, optional
+        Number of steps after which data gets collected, by default -1 (end of episode)
+    max_steps : int, optional
+        Maximum number of model steps after which the model halts, by default 1000
+    display_progress : bool, optional
+        Display batch run process, by default True
 
+    Returns
+    -------
+    List[Dict[str, Any]]
+        [description]
     """
+
     runs_list = []
     run_id = 0
     for iteration in range(iterations):
@@ -108,7 +85,7 @@ def _make_model_kwargs(
     parameters : Mapping[str, Union[Any, Iterable[Any]]]
         Single or multiple values for each model parameter name
 
-    Returns:
+    Returns
     -------
     List[Dict[str, Any]]
         A list of all kwargs combinations.
@@ -148,21 +125,21 @@ def _model_run_func(
     data_collection_period : int
         Number of steps after which data gets collected
 
-    Returns:
+    Returns
     -------
     List[Dict[str, Any]]
         Return model_data, agent_data from the reporters
     """
     run_id, iteration, kwargs = run
     model = model_cls(**kwargs)
-    while model.running and model.steps <= max_steps:
+    while model.running and model._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._steps, data_collection_period))
+    if not steps or steps[-1] != model._steps - 1:
+        steps.append(model._steps - 1)
 
     for step in steps:
         model_data, all_agents_data = _collect_data(model, step)
@@ -201,10 +178,6 @@ def _collect_data(
     step: int,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """Collect model and agent data from a model using mesas datacollector."""
-    if not hasattr(model, "datacollector"):
-        raise AttributeError(
-            "The model does not have a datacollector attribute. Please add a DataCollector to your model."
-        )
     dc = model.datacollector
 
     model_data = {param: values[step] for param, values in dc.model_vars.items()}

mesa/cookiecutter-mesa/cookiecutter.json

@@ -0,0 +1,8 @@
+{
+    "project": "Example Project",
+    "snake": "{{ cookiecutter.project.lower().replace(' ', '_') }}",
+    "camel": "{{ cookiecutter.project.title().replace(' ', '') }}",
+    "agent": "{{ cookiecutter.camel + 'Agent'}}",
+    "model": "{{ cookiecutter.camel + 'Model'}}",
+    "description": "Example short description of the project"
+}

mesa/cookiecutter-mesa/hooks/post_gen_project.py

@@ -0,0 +1,11 @@
+import glob
+import os
+
+file_list = glob.glob("**/*.pytemplate", recursive=True)
+
+for file_path in file_list:
+    # Check if the file is a regular file
+    if not os.path.isfile(file_path):
+        continue
+    # Rename the file
+    os.rename(file_path, file_path.replace(".pytemplate", ".py"))

mesa/cookiecutter-mesa/{{cookiecutter.snake}}/README.md

@@ -0,0 +1,4 @@
+{{cookiecutter.project}}
+========================
+
+{{cookiecutter.description}}

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

@@ -0,0 +1,27 @@
+"""
+Configure visualization elements and instantiate a server
+"""
+from mesa.visualization import SolaraViz
+
+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 = SolaraViz(
+    {{cookiecutter.model}},
+    model_params,
+    measures=["num_agents"],
+    agent_portrayal=circle_portrayal_example
+)
+page  # noqa

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env python
+from setuptools import find_packages, setup
+
+requires = ["mesa"]
+
+setup(
+    name="{{cookiecutter.snake}}",
+    version="0.0.1",
+    packages=find_packages(),
+    install_requires=requires,
+)

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

@@ -0,0 +1,60 @@
+import mesa
+
+
+class {{cookiecutter.agent}}(mesa.Agent):  # noqa
+    """
+    An agent
+    """
+
+    def __init__(self, unique_id, model):
+        """
+        Customize the agent
+        """
+        self.unique_id = unique_id
+        super().__init__(unique_id, model)
+
+    def step(self):
+        """
+        Modify this method to change what an individual agent will do during each step.
+        Can include logic based on neighbors states.
+        """
+        pass
+
+
+class {{cookiecutter.model}}(mesa.Model):
+    """
+    The model class holds the model-level attributes, manages the agents, and generally handles
+    the global level of our model.
+
+    There is only one model-level parameter: how many agents the model contains. When a new model
+    is started, we want it to populate itself with the given number of agents.
+
+    The scheduler is a special model component which controls the order in which agents are activated.
+    """
+
+    def __init__(self, num_agents, width, height):
+        super().__init__()
+        self.num_agents = num_agents
+        self.schedule = mesa.time.RandomActivation(self)
+        self.grid = mesa.space.MultiGrid(width=width, height=height, torus=True)
+
+        for i in range(self.num_agents):
+            agent = {{cookiecutter.agent}}(i, self)
+            self.schedule.add(agent)
+
+            x = self.random.randrange(self.grid.width)
+            y = self.random.randrange(self.grid.height)
+            self.grid.place_agent(agent, (x, y))
+
+        # example data collector
+        self.datacollector = mesa.datacollection.DataCollector({"num_agents": "num_agents"})
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        """
+        A model step. Used for collecting data and advancing the schedule
+        """
+        self.datacollector.collect(self)
+        self.schedule.step()

mesa/datacollection.py

@@ -1,19 +1,20 @@
-"""Mesa Data Collection Module.
+"""
+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.
@@ -22,18 +23,19 @@ 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.
+
+The default DataCollector here makes several assumptions:
+    * The model has an agent list called agents
+    * For collecting agent-level variables, agents must have a unique_id
 """
 
 import contextlib
 import itertools
 import types
-import warnings
 from copy import deepcopy
 from functools import partial
 
@@ -44,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:
@@ -86,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
@@ -99,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:
@@ -110,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:
@@ -125,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)
@@ -177,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.
 
@@ -224,7 +180,7 @@ class DataCollector:
         rep_funcs = self.agent_reporters.values()
 
         def get_reports(agent):
-            _prefix = (agent.model.steps, agent.unique_id)
+            _prefix = (agent.model._steps, agent.unique_id)
             reports = tuple(rep(agent) for rep in rep_funcs)
             return _prefix + reports
 
@@ -236,34 +192,6 @@ 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:
@@ -282,20 +210,13 @@ class DataCollector:
                 elif isinstance(reporter, list):
                     self.model_vars[var].append(deepcopy(reporter[0](*reporter[1])))
                 # Assume it's a callable otherwise (e.g., method)
+                # TODO: Check if method of a class explicitly
                 else:
                     self.model_vars[var].append(deepcopy(reporter()))
 
         if self.agent_reporters:
             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
-                )
+            self._agent_records[model._steps] = list(agent_records)
 
     def add_table_row(self, table_name, row, ignore_missing=False):
         """Add a row dictionary to a specific table.
@@ -353,38 +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,13 +1,3 @@
-"""Experimental init."""
-
 from mesa.experimental import cell_space
 
-try:
-    from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
-
-    __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"]
+__all__ = ["cell_space"]

mesa/experimental/cell_space/__init__.py

@@ -1,16 +1,5 @@
-"""Cell spaces.
-
-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`.
-
-"""
-
 from mesa.experimental.cell_space.cell import Cell
-from mesa.experimental.cell_space.cell_agent import (
-    CellAgent,
-    FixedAgent,
-    Grid2DMovingAgent,
-)
+from mesa.experimental.cell_space.cell_agent import CellAgent
 from mesa.experimental.cell_space.cell_collection import CellCollection
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 from mesa.experimental.cell_space.grid import (
@@ -20,19 +9,15 @@ from mesa.experimental.cell_space.grid import (
     OrthogonalVonNeumannGrid,
 )
 from mesa.experimental.cell_space.network import Network
-from mesa.experimental.cell_space.voronoi import VoronoiGrid
 
 __all__ = [
     "CellCollection",
     "Cell",
     "CellAgent",
-    "Grid2DMovingAgent",
-    "FixedAgent",
     "DiscreteSpace",
     "Grid",
     "HexGrid",
     "OrthogonalMooreGrid",
     "OrthogonalVonNeumannGrid",
     "Network",
-    "VoronoiGrid",
 ]