Mesa 3.0.0b2__py3-none-any.whl → 3.0.1__py3-none-any.whl

mesa/experimental/cell_space/cell_collection.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import itertools
+import warnings
 from collections.abc import Callable, Iterable, Mapping
 from functools import cached_property
 from random import Random
@@ -23,6 +24,12 @@ class CellCollection(Generic[T]):
         agents (List[CellAgent]) : List of agents occupying the cells in this collection
         random (Random) : The random number generator
 
+    Notes:
+        A `UserWarning` is issued if `random=None`. You can resolve this warning by explicitly
+        passing a random number generator. In most cases, this will be the seeded random number
+        generator in the model. So, you would do `random=self.random` in a `Model` or `Agent` instance.
+
+
     """
 
     def __init__(
@@ -45,7 +52,12 @@ class CellCollection(Generic[T]):
         self._capacity: int = next(iter(self._cells.keys())).capacity
 
         if random is None:
-            random = Random()  # FIXME
+            warnings.warn(
+                "Random number generator not specified, this can make models non-reproducible. Please pass a random number generator explicitly",
+                UserWarning,
+                stacklevel=2,
+            )
+            random = Random()
         self.random = random
 
     def __iter__(self):  # noqa
@@ -115,4 +127,4 @@ class CellCollection(Generic[T]):
                     yield cell
                     count += 1
 
-        return CellCollection(cell_generator(filter_func, at_most))
+        return CellCollection(cell_generator(filter_func, at_most), random=self.random)

mesa/experimental/cell_space/discrete_space.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable
 from functools import cached_property
 from random import Random
@@ -25,6 +26,12 @@ class DiscreteSpace(Generic[T]):
         cell_klass (Type) : the type of cell class
         empties (CellCollection) : collection of all cells that are empty
         property_layers (dict[str, PropertyLayer]): the property layers of the discrete space
+
+    Notes:
+        A `UserWarning` is issued if `random=None`. You can resolve this warning by explicitly
+        passing a random number generator. In most cases, this will be the seeded random number
+        generator in the model. So, you would do `random=self.random` in a `Model` or `Agent` instance.
+
     """
 
     def __init__(
@@ -44,7 +51,12 @@ class DiscreteSpace(Generic[T]):
         self.capacity = capacity
         self._cells: dict[tuple[int, ...], T] = {}
         if random is None:
-            random = Random()  # FIXME should default to default rng from model
+            warnings.warn(
+                "Random number generator not specified, this can make models non-reproducible. Please pass a random number generator explicitly",
+                UserWarning,
+                stacklevel=2,
+            )
+            random = Random()
         self.random = random
         self.cell_klass = cell_klass
 
@@ -67,7 +79,9 @@ class DiscreteSpace(Generic[T]):
     @cached_property
     def all_cells(self):
         """Return all cells in space."""
-        return CellCollection({cell: cell.agents for cell in self._cells.values()})
+        return CellCollection(
+            {cell: cell.agents for cell in self._cells.values()}, random=self.random
+        )
 
     def __iter__(self):  # noqa
         return iter(self._cells.values())

mesa/experimental/devs/simulator.py

@@ -57,8 +57,20 @@ class Simulator:
         Args:
             model (Model): The model to simulate
 
+        Raises:
+            Exception if simulator.time is not equal to simulator.starttime
+            Exception if event list is not empty
+
         """
-        self.event_list.clear()
+        if self.time != self.start_time:
+            raise ValueError(
+                "trying to setup model, but current time is not equal to start_time, Has the simulator been reset or freshly initialized?"
+            )
+        if not self.event_list.is_empty():
+            raise ValueError(
+                "trying to setup model, but events have already been scheduled. Call simulator.setup before any scheduling"
+            )
+
         self.model = model
 
     def reset(self):
@@ -68,7 +80,20 @@ class Simulator:
         self.time = self.start_time
 
     def run_until(self, end_time: int | float) -> None:
-        """Run the simulator until the end time."""
+        """Run the simulator until the end time.
+
+        Args:
+            end_time (int | float): The end time for stopping the simulator
+
+        Raises:
+            Exception if simulator.setup() has not yet been called
+
+        """
+        if self.model is None:
+            raise Exception(
+                "simulator has not been setup, call simulator.setup(model) first"
+            )
+
         while True:
             try:
                 event = self.event_list.pop_event()
@@ -84,6 +109,26 @@ class Simulator:
                 self._schedule_event(event)  # reschedule event
                 break
 
+    def run_next_event(self):
+        """Execute the next event.
+
+        Raises:
+            Exception if simulator.setup() has not yet been called
+
+        """
+        if self.model is None:
+            raise Exception(
+                "simulator has not been setup, call simulator.setup(model) first"
+            )
+
+        try:
+            event = self.event_list.pop_event()
+        except IndexError:  # event list is empty
+            return
+        else:
+            self.time = event.time
+            event.execute()
+
     def run_for(self, time_delta: int | float):
         """Run the simulator for the specified time delta.
 
@@ -92,6 +137,7 @@ class Simulator:
                                      plus the time delta
 
         """
+        # fixme, raise initialization error or something like it if model.setup has not been called
         end_time = self.time + time_delta
         self.run_until(end_time)
 
@@ -228,7 +274,7 @@ class ABMSimulator(Simulator):
 
         """
         super().setup(model)
-        self.schedule_event_now(self.model.step, priority=Priority.HIGH)
+        self.schedule_event_next_tick(self.model.step, priority=Priority.HIGH)
 
     def check_time_unit(self, time) -> bool:
         """Check whether the time is of the correct unit.
@@ -277,7 +323,15 @@ class ABMSimulator(Simulator):
         Args:
             end_time (float| int): The end_time delta. The simulator is until the specified end time
 
+        Raises:
+            Exception if simulator.setup() has not yet been called
+
         """
+        if self.model is None:
+            raise Exception(
+                "simulator has not been setup, call simulator.setup(model) first"
+            )
+
         while True:
             try:
                 event = self.event_list.pop_event()
@@ -285,6 +339,8 @@ class ABMSimulator(Simulator):
                 self.time = end_time
                 break
 
+            # fixme: the alternative would be to wrap model.step with an annotation which
+            #  handles this scheduling.
             if event.time <= end_time:
                 self.time = event.time
                 if event.fn() == self.model.step:
@@ -298,17 +354,6 @@ class ABMSimulator(Simulator):
                 self._schedule_event(event)
                 break
 
-    def run_for(self, time_delta: int):
-        """Run the simulator for the specified time delta.
-
-        Args:
-            time_delta (float| int): The time delta. The simulator is run from the current time to the current time
-                                     plus the time delta
-
-        """
-        end_time = self.time + time_delta - 1
-        self.run_until(end_time)
-
 
 class DEVSimulator(Simulator):
     """A simulator where the unit of time is a float.

mesa/model.py

@@ -114,7 +114,7 @@ class Model:
 
     def next_id(self) -> int:  # noqa: D102
         warnings.warn(
-            "using model.next_id() is deprecated. Agents track their unique ID automatically",
+            "using model.next_id() is deprecated and will be removed in Mesa 3.1. Agents track their unique ID automatically",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -146,8 +146,8 @@ class Model:
     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}].",
+            f"Model.get_agents_of_type() is deprecated and will be removed in Mesa 3.1."
+            f"Please replace get_agents_of_type({agenttype}) with the property agents_by_type[{agenttype}].",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -262,7 +262,7 @@ class Model:
 
         """
         warnings.warn(
-            "initialize_data_collector() is deprecated. Please use the DataCollector class directly. "
+            "initialize_data_collector() is deprecated and will be removed in Mesa 3.1. Please use the DataCollector class directly. "
             "by using `self.datacollector = DataCollector(...)`.",
             DeprecationWarning,
             stacklevel=2,

mesa/space.py

@@ -1287,36 +1287,6 @@ class HexMultiGrid(_HexGrid, MultiGrid):
     """
 
 
-class HexGrid(HexSingleGrid):
-    """Hexagonal Grid: a Grid where neighbors are computed according to a hexagonal tiling of the grid.
-
-    Functions according to odd-q rules.
-    See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
-
-    Properties:
-        width, height: The grid's width and height.
-        torus: Boolean which determines whether to treat the grid as a torus.
-    """
-
-    def __init__(self, width: int, height: int, torus: bool) -> None:
-        """Initializes a HexGrid, deprecated.
-
-        Args:
-            width: the width of the grid
-            height: the height of the grid
-            torus: whether the grid wraps
-        """
-        super().__init__(width, height, torus)
-        warn(
-            (
-                "HexGrid is being deprecated; use instead HexSingleGrid or HexMultiGrid "
-                "depending on your use case."
-            ),
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
 class ContinuousSpace:
     """Continuous space where each agent can have an arbitrary position.
 

mesa/time.py

@@ -1,7 +1,7 @@
 """Mesa Time Module.
 
 .. warning::
-    The time module and all its Schedulers are deprecated and will be removed in a future version.
+    The time module and all its Schedulers are deprecated and will be removed in Mesa 3.1.
     They can be replaced with AgentSet functionality. See the migration guide for details:
     https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers
 
@@ -63,7 +63,7 @@ class BaseScheduler:
 
         """
         warnings.warn(
-            "The time module and all its Schedulers are deprecated and will be removed in a future version. "
+            "The time module and all its Schedulers are deprecated and will be removed in Mesa 3.1. "
             "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,
@@ -375,7 +375,7 @@ class RandomActivationByType(BaseScheduler):
 
 
 class DiscreteEventScheduler(BaseScheduler):
-    """This class has been deprecated and replaced by the functionality provided by experimental.devs."""
+    """This class has been removed and replaced by the functionality provided by experimental.devs."""
 
     def __init__(self, model: Model, time_step: TimeT = 1) -> None:
         """Initialize DiscreteEventScheduler.
@@ -387,5 +387,5 @@ class DiscreteEventScheduler(BaseScheduler):
         """
         super().__init__(model)
         raise Exception(
-            "DiscreteEventScheduler is deprecated in favor of the functionality provided by experimental.devs"
+            "DiscreteEventScheduler is removed in favor of the functionality provided by experimental.devs"
         )

mesa/visualization/__init__.py

@@ -1,15 +1,26 @@
-"""Solara based visualization for Mesa models."""
+"""Solara based visualization for Mesa models.
 
-from .components.altair import make_space_altair
-from .components.matplotlib import make_plot_measure, make_space_matplotlib
+.. 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 .UserParam import Slider
+from .user_param import Slider
 
 __all__ = [
     "JupyterViz",
     "SolaraViz",
     "Slider",
     "make_space_altair",
-    "make_space_matplotlib",
-    "make_plot_measure",
+    "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.py → altair_components.py}

@@ -1,6 +1,7 @@
 """Altair based solara components for visualization mesa spaces."""
 
 import contextlib
+import warnings
 
 import solara
 
@@ -12,7 +13,33 @@ from mesa.space import ContinuousSpace, _Grid
 from mesa.visualization.utils import update_counter
 
 
-def make_space_altair(agent_portrayal=None):  # noqa: D103
+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):
@@ -25,7 +52,12 @@ def make_space_altair(agent_portrayal=None):  # noqa: D103
 
 
 @solara.component
-def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):  # noqa: D103
+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:

mesa/visualization/components/matplotlib_components.py

@@ -0,0 +1,175 @@
+"""Matplotlib based solara components for visualization MESA spaces and plots."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+
+import matplotlib.pyplot as plt
+import solara
+from matplotlib.figure import Figure
+
+from mesa.visualization.mpl_space_drawing import draw_space
+from mesa.visualization.utils import update_counter
+
+
+def make_space_matplotlib(*args, **kwargs):  # noqa: D103
+    warnings.warn(
+        "make_space_matplotlib has been renamed to make_mpl_space_component",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return make_mpl_space_component(*args, **kwargs)
+
+
+def make_mpl_space_component(
+    agent_portrayal: Callable | None = None,
+    propertylayer_portrayal: dict | None = None,
+    post_process: Callable | None = None,
+    **space_drawing_kwargs,
+) -> SpaceMatplotlib:
+    """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)
+        space_drawing_kwargs : additional keyword arguments to be passed on to the underlying space drawer function. See
+                               the functions for drawing the various spaces for further details.
+
+    ``agent_portrayal`` is called with an agent and should return a dict. Valid fields in this dict are "color",
+    "size", "marker", "zorder", alpha, linewidths, and edgecolors. 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 {}
+
+    def MakeSpaceMatplotlib(model):
+        return SpaceMatplotlib(
+            model,
+            agent_portrayal,
+            propertylayer_portrayal,
+            post_process=post_process,
+            **space_drawing_kwargs,
+        )
+
+    return MakeSpaceMatplotlib
+
+
+@solara.component
+def SpaceMatplotlib(
+    model,
+    agent_portrayal,
+    propertylayer_portrayal,
+    dependencies: list[any] | None = None,
+    post_process: Callable | None = None,
+    **space_drawing_kwargs,
+):
+    """Create a Matplotlib-based space visualization component."""
+    update_counter.get()
+
+    space = getattr(model, "grid", None)
+    if space is None:
+        space = getattr(model, "space", None)
+
+    fig = Figure()
+    ax = fig.add_subplot()
+
+    draw_space(
+        space,
+        agent_portrayal,
+        propertylayer_portrayal=propertylayer_portrayal,
+        ax=ax,
+        **space_drawing_kwargs,
+    )
+
+    if post_process is not None:
+        post_process(ax)
+
+    solara.FigureMatplotlib(
+        fig, format="png", bbox_inches="tight", dependencies=dependencies
+    )
+
+
+def make_plot_measure(*args, **kwargs):  # noqa: D103
+    warnings.warn(
+        "make_plot_measure has been renamed to make_plot_component",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return make_mpl_plot_component(*args, **kwargs)
+
+
+def make_mpl_plot_component(
+    measure: str | dict[str, str] | list[str] | tuple[str],
+    post_process: Callable | None = None,
+    save_format="png",
+):
+    """Create a plotting function for a specified measure.
+
+    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.
+        save_format: save format of figure in solara backend
+
+    Returns:
+        function: A function that creates a PlotMatplotlib component.
+    """
+
+    def MakePlotMatplotlib(model):
+        return PlotMatplotlib(
+            model, measure, post_process=post_process, save_format=save_format
+        )
+
+    return MakePlotMatplotlib
+
+
+@solara.component
+def PlotMatplotlib(
+    model,
+    measure,
+    dependencies: list[any] | None = None,
+    post_process: Callable | None = None,
+    save_format="png",
+):
+    """Create a Matplotlib-based plot for a measure or measures.
+
+    Args:
+        model (mesa.Model): The model instance.
+        measure (str | dict[str, str] | list[str] | tuple[str]): Measure(s) to plot.
+        dependencies (list[any] | None): Optional dependencies for the plot.
+        post_process: a user-specified callable to do post-processing called with the Axes instance.
+        save_format: format used for saving the figure.
+
+    Returns:
+        solara.FigureMatplotlib: A component for rendering the plot.
+    """
+    update_counter.get()
+    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)
+        ax.legend(loc="best")
+    elif isinstance(measure, list | tuple):
+        for m in measure:
+            ax.plot(df.loc[:, m], label=m)
+        ax.legend(loc="best")
+
+    if post_process is not None:
+        post_process(ax)
+
+    ax.set_xlabel("Step")
+    # Set integer x axis
+    ax.xaxis.set_major_locator(plt.MaxNLocator(integer=True))
+    solara.FigureMatplotlib(
+        fig, format=save_format, bbox_inches="tight", dependencies=dependencies
+    )