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

mesa/time.py

@@ -1,6 +1,9 @@
-"""
-Mesa Time Module
-================
+"""Mesa Time Module.
+
+.. warning::
+    The time module and all its Schedulers are deprecated and will be removed in a future version.
+    They can be replaced with AgentSet functionality. See the migration guide for details:
+    https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers
 
 Objects for handling the time component of a model. In particular, this module
 contains Schedulers, which handle agent activation. A Scheduler is an object
@@ -30,34 +33,25 @@ 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:
-    """
-    A simple scheduler that activates agents one at a time, in the order they were added.
+    """A simple scheduler that activates agents one at a time, in the order they were added.
 
     This scheduler is designed to replicate the behavior of the scheduler in MASON, a multi-agent simulation toolkit.
     It assumes that each agent added has a `step` method which takes no arguments and executes the agent's actions.
 
     Attributes:
-        - model (Model): The model instance associated with the scheduler.
-        - steps (int): The number of steps the scheduler has taken.
-        - time (TimeT): The current time in the simulation. Can be an integer or a float.
-
-    Methods:
-        - add: Adds an agent to the scheduler.
-        - remove: Removes an agent from the scheduler.
-        - step: Executes a step, which involves activating each agent once.
-        - get_agent_count: Returns the number of agents in the scheduler.
-        - agents (property): Returns a list of all agent instances.
+        model (Model): The model instance associated with the scheduler.
+        steps (int): The number of steps the scheduler has taken.
+        time (TimeT): The current time in the simulation. Can be an integer or a float.
+
     """
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
@@ -68,16 +62,22 @@ class BaseScheduler:
             agents (Iterable[Agent], None, optional): An iterable of agents who are controlled by the schedule
 
         """
+        warnings.warn(
+            "The time module and all its Schedulers are deprecated and will be removed in a future version. "
+            "They can be replaced with AgentSet functionality. See the migration guide for details. "
+            "https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         self.model = model
         self.steps = 0
         self.time: TimeT = 0
-        self._original_step = self.step
-        self.step = self._wrapped_step
 
         if agents is None:
             agents = []
 
-        self._agents: AgentSet = AgentSet(agents, model)
+        self._agents: AgentSet = AgentSet(agents, model.random)
 
         self._remove_warning_given = False
         self._agents_key_warning_given = False
@@ -86,10 +86,8 @@ class BaseScheduler:
         """Add an Agent object to the schedule.
 
         Args:
-            agent: An Agent to be added to the schedule. NOTE: The agent must
-            have a step() method.
+            agent (Agent): An Agent to be added to the schedule.
         """
-
         if agent not in self._agents:
             self._agents.add(agent)
         else:
@@ -98,12 +96,13 @@ class BaseScheduler:
     def remove(self, agent: Agent) -> None:
         """Remove all instances of a given agent from the schedule.
 
+        Args:
+            agent: An `Agent` instance.
+
         Note:
             It is only necessary to explicitly remove agents from the schedule if
             the agent is not removed from the model.
 
-        Args:
-            agent: An agent object.
         """
         self._agents.remove(agent)
 
@@ -115,21 +114,18 @@ class BaseScheduler:
         self.steps += 1
         self.time += 1
 
-    def _wrapped_step(self):
-        """Wrapper for the step method to include time and step updating."""
-        self._original_step()
-        self.model._advance_time()
-
     def get_agent_count(self) -> int:
         """Returns the current number of agents in the queue."""
         return len(self._agents)
 
     @property
     def agents(self) -> AgentSet:
+        """Return agents in the scheduler."""
         # a bit dirty, but returns a copy of the internal agent set
         return self._agents.select()
 
     def get_agent_keys(self, shuffle: bool = False) -> list[int]:
+        """Deprecated."""
         # To be able to remove and/or add agents during stepping
         # it's necessary to cast the keys view to a list.
 
@@ -147,14 +143,21 @@ class BaseScheduler:
         return agent_keys
 
     def do_each(self, method, shuffle=False):
+        """Perform `method` on each agent.
+
+        Args:
+            method: method to call
+            shuffle: shuffle the agents or not prior to calling method
+
+
+        """
         if shuffle:
             self._agents.shuffle(inplace=True)
         self._agents.do(method)
 
 
 class RandomActivation(BaseScheduler):
-    """
-    A scheduler that activates each agent once per step, in a random order, with the order reshuffled each step.
+    """A scheduler that activates each agent once per step, in a random order, with the order reshuffled each step.
 
     This scheduler is equivalent to the NetLogo 'ask agents...' behavior and is a common default for ABMs.
     It assumes that all agents have a `step` method.
@@ -164,23 +167,17 @@ class RandomActivation(BaseScheduler):
 
     Inherits all attributes and methods from BaseScheduler.
 
-    Methods:
-        - step: Executes a step, activating each agent in a random order.
     """
 
     def step(self) -> None:
-        """Executes the step of all agents, one at a time, in
-        random order.
-
-        """
+        """Executes the step of all agents, one at a time, in random order."""
         self.do_each("step", shuffle=True)
         self.steps += 1
         self.time += 1
 
 
 class SimultaneousActivation(BaseScheduler):
-    """
-    A scheduler that simulates the simultaneous activation of all agents.
+    """A scheduler that simulates the simultaneous activation of all agents.
 
     This scheduler is unique in that it requires agents to have both `step` and `advance` methods.
     - The `step` method is for activating the agent and staging any changes without applying them immediately.
@@ -191,8 +188,6 @@ class SimultaneousActivation(BaseScheduler):
 
     Inherits all attributes and methods from BaseScheduler.
 
-    Methods:
-        - step: Executes a step for all agents, first calling `step` then `advance` on each.
     """
 
     def step(self) -> None:
@@ -207,9 +202,9 @@ class SimultaneousActivation(BaseScheduler):
 
 
 class StagedActivation(BaseScheduler):
-    """
-    A scheduler allowing agent activation to be divided into several stages, with all agents executing one stage
-    before moving on to the next. This class is a generalization of SimultaneousActivation.
+    """A scheduler allowing agent activation to be divided into several stages.
+
+    All agents executing one stage before moving on to the next. This class is a generalization of SimultaneousActivation.
 
     This scheduler is useful for complex models where actions need to be broken down into distinct phases
     for each agent in each time step. Agents must implement methods for each defined stage.
@@ -224,8 +219,6 @@ class StagedActivation(BaseScheduler):
         - shuffle (bool): Determines whether to shuffle the order of agents each step.
         - shuffle_between_stages (bool): Determines whether to shuffle agents between each stage.
 
-    Methods:
-        - step: Executes all the stages for all agents in the defined order.
     """
 
     def __init__(
@@ -270,8 +263,7 @@ class StagedActivation(BaseScheduler):
 
 
 class RandomActivationByType(BaseScheduler):
-    """
-    A scheduler that activates each type of agent once per step, in random order, with the order reshuffled every step.
+    """A scheduler that activates each type of agent once per step, in random order, with the order reshuffled every step.
 
     This scheduler is useful for models with multiple types of agents, ensuring that each type is treated
     equitably in terms of activation order. The randomness in activation order helps in reducing biases
@@ -287,14 +279,10 @@ class RandomActivationByType(BaseScheduler):
     Attributes:
         - agents_by_type (defaultdict): A dictionary mapping agent types to dictionaries of agents.
 
-    Methods:
-        - step: Executes the step of each agent type in a random order.
-        - step_type: Activates all agents of a given type.
-        - get_type_count: Returns the count of agents of a specific type.
     """
 
     @property
-    def agents_by_type(self):
+    def agents_by_type(self):  # noqa: D102
         warnings.warn(
             "Because of the shift to using AgentSet, in the future this attribute will return a dict with"
             "type as key as AgentSet as value. Future behavior is available via RandomActivationByType._agents_by_type",
@@ -309,14 +297,13 @@ class RandomActivationByType(BaseScheduler):
         return agentsbytype
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
-        super().__init__(model, agents)
-        """
+        """Initialize RandomActivationByType instance.
 
         Args:
             model (Model): The model to which the schedule belongs
             agents (Iterable[Agent], None, optional): An iterable of agents who are controlled by the schedule
         """
-
+        super().__init__(model, agents)
         # can't be a defaultdict because we need to pass model to AgentSet
         self._agents_by_type: [type, AgentSet] = {}
 
@@ -325,11 +312,12 @@ class RandomActivationByType(BaseScheduler):
                 try:
                     self._agents_by_type[type(agent)].add(agent)
                 except KeyError:
-                    self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
+                    self._agents_by_type[type(agent)] = AgentSet(
+                        [agent], self.model.random
+                    )
 
     def add(self, agent: Agent) -> None:
-        """
-        Add an Agent object to the schedule
+        """Add an Agent object to the schedule.
 
         Args:
             agent: An Agent to be added to the schedule.
@@ -339,24 +327,24 @@ class RandomActivationByType(BaseScheduler):
         try:
             self._agents_by_type[type(agent)].add(agent)
         except KeyError:
-            self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
+            self._agents_by_type[type(agent)] = AgentSet([agent], self.model.random)
 
     def remove(self, agent: Agent) -> None:
-        """
-        Remove all instances of a given agent from the schedule.
+        """Remove all instances of a given agent from the schedule.
+
+        Args:
+            agent: An Agent to be removed from the schedule.
+
         """
         super().remove(agent)
         self._agents_by_type[type(agent)].remove(agent)
 
     def step(self, shuffle_types: bool = True, shuffle_agents: bool = True) -> None:
-        """
-        Executes the step of each agent type, one at a time, in random order.
+        """Executes the step of each agent type, one at a time, in random order.
 
         Args:
-            shuffle_types: If True, the order of execution of each types is
-                           shuffled.
-            shuffle_agents: If True, the order of execution of each agents in a
-                            type group is shuffled.
+            shuffle_types: If True, the order of execution of each types is shuffled.
+            shuffle_agents: If True, the order of execution of each agents in a type group is shuffled.
         """
         # To be able to remove and/or add agents during stepping
         # it's necessary to cast the keys view to a list.
@@ -369,12 +357,11 @@ class RandomActivationByType(BaseScheduler):
         self.time += 1
 
     def step_type(self, agenttype: type[Agent], shuffle_agents: bool = True) -> None:
-        """
-        Shuffle order and run all agents of a given type.
-        This method is equivalent to the NetLogo 'ask [breed]...'.
+        """Shuffle order and run all agents of a given type.
 
         Args:
             agenttype: Class object of the type to run.
+            shuffle_agents: If True, shuffle agents
         """
         agents = self._agents_by_type[agenttype]
 
@@ -383,19 +370,15 @@ class RandomActivationByType(BaseScheduler):
         agents.do("step")
 
     def get_type_count(self, agenttype: type[Agent]) -> int:
-        """
-        Returns the current number of agents of certain type in the queue.
-        """
+        """Returns the current number of agents of certain type in the queue."""
         return len(self._agents_by_type[agenttype])
 
 
 class DiscreteEventScheduler(BaseScheduler):
-    """
-    This class has been deprecated and replaced by the functionality provided by experimental.devs
-    """
+    """This class has been deprecated and replaced by the functionality provided by experimental.devs."""
 
     def __init__(self, model: Model, time_step: TimeT = 1) -> None:
-        """
+        """Initialize DiscreteEventScheduler.
 
         Args:
             model (Model): The model to which the schedule belongs

mesa/visualization/__init__.py

@@ -1,7 +1,26 @@
-import contextlib
+"""Solara based visualization for Mesa models.
 
-with contextlib.suppress(ImportError):
-    from mesa_viz_tornado.ModularVisualization import *  # noqa
-    from mesa_viz_tornado.modules import *  # noqa
-    from mesa_viz_tornado.UserParam import *  # noqa
-    from mesa_viz_tornado.TextVisualization import *  # noqa
+.. note::
+    SolaraViz is experimental and still in active development for Mesa 3.0. While we attempt to minimize them, there might be API breaking changes between Mesa 3.0 and 3.1.
+
+    There won't be breaking changes between Mesa 3.0.x patch releases.
+"""
+
+from mesa.visualization.mpl_space_drawing import (
+    draw_space,
+)
+
+from .components import make_plot_component, make_space_component
+from .components.altair_components import make_space_altair
+from .solara_viz import JupyterViz, SolaraViz
+from .user_param import Slider
+
+__all__ = [
+    "JupyterViz",
+    "SolaraViz",
+    "Slider",
+    "make_space_altair",
+    "draw_space",
+    "make_plot_component",
+    "make_space_component",
+]

mesa/visualization/components/__init__.py

@@ -0,0 +1,83 @@
+"""custom solara components."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .altair_components import SpaceAltair, make_altair_space
+from .matplotlib_components import (
+    SpaceMatplotlib,
+    make_mpl_plot_component,
+    make_mpl_space_component,
+)
+
+
+def make_space_component(
+    agent_portrayal: Callable | None = None,
+    propertylayer_portrayal: dict | None = None,
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **space_drawing_kwargs,
+) -> SpaceMatplotlib | SpaceAltair:
+    """Create a Matplotlib-based space visualization component.
+
+    Args:
+        agent_portrayal: Function to portray agents.
+        propertylayer_portrayal: Dictionary of PropertyLayer portrayal specifications
+        post_process : a callable that will be called with the Axes instance. Allows for fine-tuning plots (e.g., control ticks)
+        backend: the backend to use {"matplotlib", "altair"}
+        space_drawing_kwargs : additional keyword arguments to be passed on to the underlying backend specific space drawer function. See
+                               the functions for drawing the various spaces for the appropriate backend further details.
+
+
+    Returns:
+        function: A function that creates a space component
+    """
+    if backend == "matplotlib":
+        return make_mpl_space_component(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    elif backend == "altair":
+        return make_altair_space(
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process,
+            **space_drawing_kwargs,
+        )
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )
+
+
+def make_plot_component(
+    measure: str | dict[str, str] | list[str] | tuple[str],
+    post_process: Callable | None = None,
+    backend: str = "matplotlib",
+    **plot_drawing_kwargs,
+):
+    """Create a plotting function for a specified measure using the specified backend.
+
+    Args:
+        measure (str | dict[str, str] | list[str] | tuple[str]): Measure(s) to plot.
+        post_process: a user-specified callable to do post-processing called with the Axes instance.
+        backend: the backend to use {"matplotlib", "altair"}
+        plot_drawing_kwargs: additional keyword arguments to pass onto the backend specific function for making a plotting component
+
+    Notes:
+        altair plotting backend is not yet implemented and planned for mesa 3.1.
+
+    Returns:
+        function: A function that creates a plot component
+    """
+    if backend == "matplotlib":
+        return make_mpl_plot_component(measure, post_process, **plot_drawing_kwargs)
+    elif backend == "altair":
+        raise NotImplementedError("altair line plots are not yet implemented")
+    else:
+        raise ValueError(
+            f"unknown backend {backend}, must be one of matplotlib, altair"
+        )

mesa/visualization/components/altair_components.py

@@ -0,0 +1,188 @@
+"""Altair based solara components for visualization mesa spaces."""
+
+import contextlib
+import warnings
+
+import solara
+
+with contextlib.suppress(ImportError):
+    import altair as alt
+
+from mesa.experimental.cell_space import DiscreteSpace, Grid
+from mesa.space import ContinuousSpace, _Grid
+from mesa.visualization.utils import update_counter
+
+
+def make_space_altair(*args, **kwargs):  # noqa: D103
+    warnings.warn(
+        "make_space_altair has been renamed to make_altair_space",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return make_altair_space(*args, **kwargs)
+
+
+def make_altair_space(
+    agent_portrayal, propertylayer_portrayal, post_process, **space_drawing_kwargs
+):
+    """Create an Altair-based space visualization component.
+
+    Args:
+        agent_portrayal: Function to portray agents.
+        propertylayer_portrayal: not yet implemented
+        post_process :not yet implemented
+        space_drawing_kwargs : not yet implemented
+
+    ``agent_portrayal`` is called with an agent and should return a dict. Valid fields in this dict are "color",
+    "size", "marker", and "zorder". Other field are ignored and will result in a user warning.
+
+
+    Returns:
+        function: A function that creates a SpaceMatplotlib component
+    """
+    if agent_portrayal is None:
+
+        def agent_portrayal(a):
+            return {"id": a.unique_id}
+
+    def MakeSpaceAltair(model):
+        return SpaceAltair(model, agent_portrayal)
+
+    return MakeSpaceAltair
+
+
+@solara.component
+def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+    """Create an Altair-based space visualization component.
+
+    Returns:
+        a solara FigureAltair instance
+    """
+    update_counter.get()
+    space = getattr(model, "grid", None)
+    if space is None:
+        # Sometimes the space is defined as model.space instead of model.grid
+        space = model.space
+
+    chart = _draw_grid(space, agent_portrayal)
+    solara.FigureAltair(chart)
+
+
+def _get_agent_data_old__discrete_space(space, agent_portrayal):
+    """Format agent portrayal data for old-style discrete spaces.
+
+    Args:
+        space: the mesa.space._Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+    for content, (x, y) in space.coord_iter():
+        if not content:
+            continue
+        if not hasattr(content, "__iter__"):
+            # Is a single grid
+            content = [content]  # noqa: PLW2901
+        for agent in content:
+            # use all data from agent portrayal, and add x,y coordinates
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = x
+            agent_data["y"] = y
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_new_discrete_space(space: DiscreteSpace, agent_portrayal):
+    """Format agent portrayal data for new-style discrete spaces.
+
+    Args:
+        space: the mesa.experiment.cell_space.Grid instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+
+    """
+    all_agent_data = []
+
+    for cell in space.all_cells:
+        for agent in cell.agents:
+            agent_data = agent_portrayal(agent)
+            agent_data["x"] = cell.coordinate[0]
+            agent_data["y"] = cell.coordinate[1]
+            all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _get_agent_data_continuous_space(space: ContinuousSpace, agent_portrayal):
+    """Format agent portrayal data for continuous space.
+
+    Args:
+        space: the ContinuousSpace instance
+        agent_portrayal: the agent portrayal callable
+
+    Returns:
+        list of dicts
+    """
+    all_agent_data = []
+    for agent in space._agent_to_index:
+        agent_data = agent_portrayal(agent)
+        agent_data["x"] = agent.pos[0]
+        agent_data["y"] = agent.pos[1]
+        all_agent_data.append(agent_data)
+    return all_agent_data
+
+
+def _draw_grid(space, agent_portrayal):
+    match space:
+        case Grid():
+            all_agent_data = _get_agent_data_new_discrete_space(space, agent_portrayal)
+        case _Grid():
+            all_agent_data = _get_agent_data_old__discrete_space(space, agent_portrayal)
+        case ContinuousSpace():
+            all_agent_data = _get_agent_data_continuous_space(space, agent_portrayal)
+        case _:
+            raise NotImplementedError(
+                f"visualizing {type(space)} is currently not supported through altair"
+            )
+
+    invalid_tooltips = ["color", "size", "x", "y"]
+
+    x_y_type = "ordinal" if not isinstance(space, ContinuousSpace) else "nominal"
+
+    encoding_dict = {
+        # no x-axis label
+        "x": alt.X("x", axis=None, type=x_y_type),
+        # no y-axis label
+        "y": alt.Y("y", axis=None, type=x_y_type),
+        "tooltip": [
+            alt.Tooltip(key, type=alt.utils.infer_vegalite_type([value]))
+            for key, value in all_agent_data[0].items()
+            if key not in invalid_tooltips
+        ],
+    }
+    has_color = "color" in all_agent_data[0]
+    if has_color:
+        encoding_dict["color"] = alt.Color("color", type="nominal")
+    has_size = "size" in all_agent_data[0]
+    if has_size:
+        encoding_dict["size"] = alt.Size("size", type="quantitative")
+
+    chart = (
+        alt.Chart(
+            alt.Data(values=all_agent_data), encoding=alt.Encoding(**encoding_dict)
+        )
+        .mark_point(filled=True)
+        .properties(width=280, height=280)
+        # .configure_view(strokeOpacity=0)  # hide grid/chart lines
+    )
+    # This is the default value for the marker size, which auto-scales
+    # according to the grid area.
+    if not has_size:
+        length = min(space.width, space.height)
+        chart = chart.mark_point(size=30000 / length**2, filled=True)
+
+    return chart