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

mesa/time.py

@@ -1,9 +1,6 @@
-"""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
+"""
+Mesa Time Module
+================
 
 Objects for handling the time component of a model. In particular, this module
 contains Schedulers, which handle agent activation. A Scheduler is an object
@@ -42,16 +39,23 @@ 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.
-
+        - 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.
     """
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
@@ -62,22 +66,16 @@ 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.random)
+        self._agents: AgentSet = AgentSet(agents, model)
 
         self._remove_warning_given = False
         self._agents_key_warning_given = False
@@ -86,8 +84,10 @@ class BaseScheduler:
         """Add an Agent object to the schedule.
 
         Args:
-            agent (Agent): An Agent to be added to the schedule.
+            agent: An Agent to be added to the schedule. NOTE: The agent must
+            have a step() method.
         """
+
         if agent not in self._agents:
             self._agents.add(agent)
         else:
@@ -96,13 +96,12 @@ 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)
 
@@ -114,18 +113,21 @@ 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.
 
@@ -143,21 +145,14 @@ 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.
@@ -167,17 +162,23 @@ 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.
@@ -188,6 +189,8 @@ 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:
@@ -202,9 +205,9 @@ class SimultaneousActivation(BaseScheduler):
 
 
 class StagedActivation(BaseScheduler):
-    """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.
+    """
+    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.
 
     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.
@@ -219,6 +222,8 @@ 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__(
@@ -263,7 +268,8 @@ 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
@@ -279,10 +285,14 @@ 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):  # noqa: D102
+    def agents_by_type(self):
         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",
@@ -297,13 +307,14 @@ class RandomActivationByType(BaseScheduler):
         return agentsbytype
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
-        """Initialize RandomActivationByType instance.
+        super().__init__(model, agents)
+        """
 
         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] = {}
 
@@ -312,12 +323,11 @@ class RandomActivationByType(BaseScheduler):
                 try:
                     self._agents_by_type[type(agent)].add(agent)
                 except KeyError:
-                    self._agents_by_type[type(agent)] = AgentSet(
-                        [agent], self.model.random
-                    )
+                    self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
 
     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.
@@ -327,24 +337,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.random)
+            self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
 
     def remove(self, agent: Agent) -> None:
-        """Remove all instances of a given agent from the schedule.
-
-        Args:
-            agent: An Agent to be removed from the schedule.
-
+        """
+        Remove all instances of a given agent 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.
@@ -357,11 +367,12 @@ 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.
+        """
+        Shuffle order and run all agents of a given type.
+        This method is equivalent to the NetLogo 'ask [breed]...'.
 
         Args:
             agenttype: Class object of the type to run.
-            shuffle_agents: If True, shuffle agents
         """
         agents = self._agents_by_type[agenttype]
 
@@ -370,15 +381,19 @@ 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/{experimental → visualization}/UserParam.py

@@ -1,10 +1,7 @@
-"""helper classes."""
-
-
-class UserParam:  # noqa: D101
+class UserParam:
     _ERROR_MESSAGE = "Missing or malformed inputs for '{}' Option '{}'"
 
-    def maybe_raise_error(self, param_type, valid):  # noqa: D102
+    def maybe_raise_error(self, param_type, valid):
         if valid:
             return
         msg = self._ERROR_MESSAGE.format(param_type, self.label)
@@ -12,9 +9,11 @@ class UserParam:  # noqa: D101
 
 
 class Slider(UserParam):
-    """A number-based slider input with settable increment.
+    """
+    A number-based slider input with settable increment.
 
     Example:
+
     slider_option = Slider("My Slider", value=123, min=10, max=200, step=0.1)
 
     Args:
@@ -35,16 +34,6 @@ class Slider(UserParam):
         step=1,
         dtype=None,
     ):
-        """Slider class.
-
-        Args:
-            label: The displayed label in the UI
-            value: The initial value of the slider
-            min: The minimum possible value of the slider
-            max: The maximum possible value of the slider
-            step: The step between min and max for a range of possible values
-            dtype: either int or float
-        """
         self.label = label
         self.value = value
         self.min = min
@@ -63,5 +52,5 @@ class Slider(UserParam):
     def _check_values_are_float(self, value, min, max, step):
         return any(isinstance(n, float) for n in (value, min, max, step))
 
-    def get(self, attr):  # noqa: D102
+    def get(self, attr):
         return getattr(self, attr)

mesa/visualization/__init__.py

@@ -1,26 +1,3 @@
-"""Solara based visualization for Mesa models.
+from .jupyter_viz import JupyterViz, Slider, make_text
 
-.. 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",
-]
+__all__ = ["JupyterViz", "make_text", "Slider"]

mesa/{experimental → visualization}/components/altair.py

@@ -1,5 +1,3 @@
-"""Altair components."""
-
 import contextlib
 
 import solara
@@ -10,14 +8,6 @@ with contextlib.suppress(ImportError):
 
 @solara.component
 def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
-    """A component that renders a Space using Altair.
-
-    Args:
-        model: a model instance
-        agent_portrayal: agent portray specification
-        dependencies: optional list of dependencies (currently not used)
-
-    """
     space = getattr(model, "grid", None)
     if space is None:
         # Sometimes the space is defined as model.space instead of model.grid

mesa/visualization/components/matplotlib.py

@@ -0,0 +1,134 @@
+import networkx as nx
+import solara
+from matplotlib.figure import Figure
+from matplotlib.ticker import MaxNLocator
+
+import mesa
+
+
+@solara.component
+def SpaceMatplotlib(model, agent_portrayal, dependencies: list[any] | None = None):
+    space_fig = Figure()
+    space_ax = space_fig.subplots()
+    space = getattr(model, "grid", None)
+    if space is None:
+        # Sometimes the space is defined as model.space instead of model.grid
+        space = model.space
+    if isinstance(space, mesa.space.NetworkGrid):
+        _draw_network_grid(space, space_ax, agent_portrayal)
+    elif isinstance(space, mesa.space.ContinuousSpace):
+        _draw_continuous_space(space, space_ax, agent_portrayal)
+    else:
+        _draw_grid(space, space_ax, agent_portrayal)
+    solara.FigureMatplotlib(space_fig, format="png", dependencies=dependencies)
+
+
+def _draw_grid(space, space_ax, agent_portrayal):
+    def portray(g):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+        for i in range(g.width):
+            for j in range(g.height):
+                content = g._grid[i][j]
+                if not content:
+                    continue
+                if not hasattr(content, "__iter__"):
+                    # Is a single grid
+                    content = [content]
+                for agent in content:
+                    data = agent_portrayal(agent)
+                    x.append(i)
+                    y.append(j)
+                    if "size" in data:
+                        s.append(data["size"])
+                    if "color" in data:
+                        c.append(data["color"])
+        out = {"x": x, "y": y}
+        # This is the default value for the marker size, which auto-scales
+        # according to the grid area.
+        out["s"] = (180 / min(g.width, g.height)) ** 2
+        if len(s) > 0:
+            out["s"] = s
+        if len(c) > 0:
+            out["c"] = c
+        return out
+
+    space_ax.set_xlim(-1, space.width)
+    space_ax.set_ylim(-1, space.height)
+    space_ax.scatter(**portray(space))
+
+
+def _draw_network_grid(space, space_ax, agent_portrayal):
+    graph = space.G
+    pos = nx.spring_layout(graph, seed=0)
+    nx.draw(
+        graph,
+        ax=space_ax,
+        pos=pos,
+        **agent_portrayal(graph),
+    )
+
+
+def _draw_continuous_space(space, space_ax, agent_portrayal):
+    def portray(space):
+        x = []
+        y = []
+        s = []  # size
+        c = []  # color
+        for agent in space._agent_to_index:
+            data = agent_portrayal(agent)
+            _x, _y = agent.pos
+            x.append(_x)
+            y.append(_y)
+            if "size" in data:
+                s.append(data["size"])
+            if "color" in data:
+                c.append(data["color"])
+        out = {"x": x, "y": y}
+        if len(s) > 0:
+            out["s"] = s
+        if len(c) > 0:
+            out["c"] = c
+        return out
+
+    # Determine border style based on space.torus
+    border_style = "solid" if not space.torus else (0, (5, 10))
+
+    # Set the border of the plot
+    for spine in space_ax.spines.values():
+        spine.set_linewidth(1.5)
+        spine.set_color("black")
+        spine.set_linestyle(border_style)
+
+    width = space.x_max - space.x_min
+    x_padding = width / 20
+    height = space.y_max - space.y_min
+    y_padding = height / 20
+    space_ax.set_xlim(space.x_min - x_padding, space.x_max + x_padding)
+    space_ax.set_ylim(space.y_min - y_padding, space.y_max + y_padding)
+
+    # Portray and scatter the agents in the space
+    space_ax.scatter(**portray(space))
+
+
+@solara.component
+def PlotMatplotlib(model, measure, dependencies: list[any] | None = None):
+    fig = Figure()
+    ax = fig.subplots()
+    df = model.datacollector.get_model_vars_dataframe()
+    if isinstance(measure, str):
+        ax.plot(df.loc[:, measure])
+        ax.set_ylabel(measure)
+    elif isinstance(measure, dict):
+        for m, color in measure.items():
+            ax.plot(df.loc[:, m], label=m, color=color)
+        fig.legend()
+    elif isinstance(measure, list | tuple):
+        for m in measure:
+            ax.plot(df.loc[:, m], label=m)
+        fig.legend()
+    # Set integer x axis
+    ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+    solara.FigureMatplotlib(fig, dependencies=dependencies)