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

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/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

@@ -13,7 +13,7 @@ from mesa.visualization.mpl_space_drawing import (
 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",

mesa/visualization/components/matplotlib_components.py

@@ -38,8 +38,7 @@ def make_mpl_space_component(
                                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", and "zorder". Other field are ignored and will result in a user warning.
-
+    "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

mesa/visualization/mpl_space_drawing.py

@@ -6,6 +6,7 @@ for a paper.
 
 """
 
+import contextlib
 import itertools
 import math
 import warnings
@@ -61,10 +62,19 @@ def collect_agent_data(
         zorder: default zorder
 
     agent_portrayal should return a dict, limited to size (size of marker), color (color of marker), zorder (z-order),
-    and marker (marker style)
+    marker (marker style), alpha, linewidths, and edgecolors
 
     """
-    arguments = {"s": [], "c": [], "marker": [], "zorder": [], "loc": []}
+    arguments = {
+        "s": [],
+        "c": [],
+        "marker": [],
+        "zorder": [],
+        "loc": [],
+        "alpha": [],
+        "edgecolors": [],
+        "linewidths": [],
+    }
 
     for agent in space.agents:
         portray = agent_portrayal(agent)
@@ -78,6 +88,10 @@ def collect_agent_data(
         arguments["marker"].append(portray.pop("marker", marker))
         arguments["zorder"].append(portray.pop("zorder", zorder))
 
+        for entry in ["alpha", "edgecolors", "linewidths"]:
+            with contextlib.suppress(KeyError):
+                arguments[entry].append(portray.pop(entry))
+
         if len(portray) > 0:
             ignored_fields = list(portray.keys())
             msg = ", ".join(ignored_fields)
@@ -110,7 +124,7 @@ def draw_space(
         Returns the Axes object with the plot drawn onto it.
 
     ``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.
+    "size", "marker", "zorder", alpha, linewidths, and edgecolors. Other field are ignored and will result in a user warning.
 
     """
     if ax is None:
@@ -118,16 +132,24 @@ def draw_space(
 
     # https://stackoverflow.com/questions/67524641/convert-multiple-isinstance-checks-to-structural-pattern-matching
     match space:
-        case mesa.space._Grid() | OrthogonalMooreGrid() | OrthogonalVonNeumannGrid():
-            draw_orthogonal_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
+        # order matters here given the class structure of old-style grid spaces
         case HexSingleGrid() | HexMultiGrid() | mesa.experimental.cell_space.HexGrid():
             draw_hex_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
+        case (
+            mesa.space.SingleGrid()
+            | OrthogonalMooreGrid()
+            | OrthogonalVonNeumannGrid()
+            | mesa.space.MultiGrid()
+        ):
+            draw_orthogonal_grid(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
         case mesa.space.NetworkGrid() | mesa.experimental.cell_space.Network():
             draw_network(space, agent_portrayal, ax=ax, **space_drawing_kwargs)
         case mesa.space.ContinuousSpace():
             draw_continuous_space(space, agent_portrayal, ax=ax)
         case VoronoiGrid():
-            draw_voroinoi_grid(space, agent_portrayal, ax=ax)
+            draw_voronoi_grid(space, agent_portrayal, ax=ax)
+        case _:
+            raise ValueError(f"Unknown space type: {type(space)}")
 
     if propertylayer_portrayal:
         draw_property_layers(space, propertylayer_portrayal, ax=ax)
@@ -473,7 +495,7 @@ def draw_continuous_space(
     return ax
 
 
-def draw_voroinoi_grid(
+def draw_voronoi_grid(
     space: VoronoiGrid, agent_portrayal: Callable, ax: Axes | None = None, **kwargs
 ):
     """Visualize a voronoi grid.
@@ -543,11 +565,24 @@ def _scatter(ax: Axes, arguments, **kwargs):
     marker = arguments.pop("marker")
     zorder = arguments.pop("zorder")
 
+    # we check if edgecolor, linewidth, and alpha are specified
+    # at the agent level, if not, we remove them from the arguments dict
+    # and fallback to the default value in ax.scatter / use what is passed via **kwargs
+    for entry in ["edgecolors", "linewidths", "alpha"]:
+        if len(arguments[entry]) == 0:
+            arguments.pop(entry)
+        else:
+            if entry in kwargs:
+                raise ValueError(
+                    f"{entry} is specified in agent portrayal and via plotting kwargs, you can only use one or the other"
+                )
+
     for mark in np.unique(marker):
         mark_mask = marker == mark
         for z_order in np.unique(zorder):
             zorder_mask = z_order == zorder
             logical = mark_mask & zorder_mask
+
             ax.scatter(
                 x[logical],
                 y[logical],

mesa/visualization/solara_viz.py

@@ -24,7 +24,6 @@ See the Visualization Tutorial and example models for more details.
 from __future__ import annotations
 
 import asyncio
-import copy
 import inspect
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Literal
@@ -33,7 +32,8 @@ import reacton.core
 import solara
 
 import mesa.visualization.components.altair_components as components_altair
-from mesa.visualization.UserParam import Slider
+from mesa.experimental.devs.simulator import Simulator
+from mesa.visualization.user_param import Slider
 from mesa.visualization.utils import force_update, update_counter
 
 if TYPE_CHECKING:
@@ -43,12 +43,13 @@ if TYPE_CHECKING:
 @solara.component
 def SolaraViz(
     model: Model | solara.Reactive[Model],
+    *,
     components: list[reacton.core.Component]
     | list[Callable[[Model], reacton.core.Component]]
     | Literal["default"] = "default",
     play_interval: int = 100,
+    simulator: Simulator | None = None,
     model_params=None,
-    seed: float = 0,
     name: str | None = None,
 ):
     """Solara visualization component.
@@ -67,10 +68,9 @@ def SolaraViz(
             Defaults to "default", which uses the default Altair space visualization.
         play_interval (int, optional): Interval for playing the model steps in milliseconds.
             This controls the speed of the model's automatic stepping. Defaults to 100 ms.
+        simulator: A simulator that controls the model (optional)
         model_params (dict, optional): Parameters for (re-)instantiating a model.
             Can include user-adjustable parameters and fixed parameters. Defaults to None.
-        seed (int, optional): Seed for the random number generator. This ensures reproducibility
-            of the model's behavior. Defaults to 0.
         name (str | None, optional): Name of the visualization. Defaults to the models class name.
 
     Returns:
@@ -88,41 +88,39 @@ def SolaraViz(
           value results in faster stepping, while a higher value results in slower stepping.
     """
     if components == "default":
-        components = [components_altair.make_space_altair()]
+        components = [components_altair.make_altair_space()]
+    if model_params is None:
+        model_params = {}
 
     # Convert model to reactive
     if not isinstance(model, solara.Reactive):
         model = solara.use_reactive(model)  # noqa: SH102, RUF100
 
-    def connect_to_model():
-        # Patch the step function to force updates
-        original_step = model.value.step
-
-        def step():
-            original_step()
-            force_update()
-
-        model.value.step = step
-        # Add a trigger to model itself
-        model.value.force_update = force_update
-        force_update()
-
-    solara.use_effect(connect_to_model, [model.value])
+    # set up reactive model_parameters shared by ModelCreator and ModelController
+    reactive_model_parameters = solara.use_reactive({})
 
     with solara.AppBar():
         solara.AppBarTitle(name if name else model.value.__class__.__name__)
 
     with solara.Sidebar(), solara.Column():
         with solara.Card("Controls"):
-            ModelController(model, play_interval)
-
-        if model_params is not None:
-            with solara.Card("Model Parameters"):
-                ModelCreator(
+            if not isinstance(simulator, Simulator):
+                ModelController(
                     model,
-                    model_params,
-                    seed=seed,
+                    model_parameters=reactive_model_parameters,
+                    play_interval=play_interval,
                 )
+            else:
+                SimulatorController(
+                    model,
+                    simulator,
+                    model_parameters=reactive_model_parameters,
+                    play_interval=play_interval,
+                )
+        with solara.Card("Model Parameters"):
+            ModelCreator(
+                model, model_params, model_parameters=reactive_model_parameters
+            )
         with solara.Card("Information"):
             ShowSteps(model.value)
 
@@ -173,24 +171,89 @@ JupyterViz = SolaraViz
 
 
 @solara.component
-def ModelController(model: solara.Reactive[Model], play_interval=100):
+def ModelController(
+    model: solara.Reactive[Model],
+    *,
+    model_parameters: dict | solara.Reactive[dict] = None,
+    play_interval: int = 100,
+):
     """Create controls for model execution (step, play, pause, reset).
 
     Args:
-        model (solara.Reactive[Model]): Reactive model instance
-        play_interval (int, optional): Interval for playing the model steps in milliseconds.
+        model: Reactive model instance
+        model_parameters: Reactive parameters for (re-)instantiating a model.
+        play_interval: Interval for playing the model steps in milliseconds.
+
     """
     playing = solara.use_reactive(False)
     running = solara.use_reactive(True)
-    original_model = solara.use_reactive(None)
+    if model_parameters is None:
+        model_parameters = {}
+    model_parameters = solara.use_reactive(model_parameters)
 
-    def save_initial_model():
-        """Save the initial model for comparison."""
-        original_model.set(copy.deepcopy(model.value))
-        playing.value = False
+    async def step():
+        while playing.value and running.value:
+            await asyncio.sleep(play_interval / 1000)
+            do_step()
+
+    solara.lab.use_task(
+        step, dependencies=[playing.value, running.value], prefer_threaded=False
+    )
+
+    def do_step():
+        """Advance the model by one step."""
+        model.value.step()
+        running.value = model.value.running
         force_update()
 
-    solara.use_effect(save_initial_model, [model.value])
+    def do_reset():
+        """Reset the model to its initial state."""
+        playing.value = False
+        running.value = True
+        model.value = model.value = model.value.__class__(**model_parameters.value)
+
+    def do_play_pause():
+        """Toggle play/pause."""
+        playing.value = not playing.value
+
+    with solara.Row(justify="space-between"):
+        solara.Button(label="Reset", color="primary", on_click=do_reset)
+        solara.Button(
+            label="▶" if not playing.value else "❚❚",
+            color="primary",
+            on_click=do_play_pause,
+            disabled=not running.value,
+        )
+        solara.Button(
+            label="Step",
+            color="primary",
+            on_click=do_step,
+            disabled=playing.value or not running.value,
+        )
+
+
+@solara.component
+def SimulatorController(
+    model: solara.Reactive[Model],
+    simulator,
+    *,
+    model_parameters: dict | solara.Reactive[dict] = None,
+    play_interval: int = 100,
+):
+    """Create controls for model execution (step, play, pause, reset).
+
+    Args:
+        model: Reactive model instance
+        simulator: Simulator instance
+        model_parameters: Reactive parameters for (re-)instantiating a model.
+        play_interval: Interval for playing the model steps in milliseconds.
+
+    """
+    playing = solara.use_reactive(False)
+    running = solara.use_reactive(True)
+    if model_parameters is None:
+        model_parameters = {}
+    model_parameters = solara.use_reactive(model_parameters)
 
     async def step():
         while playing.value and running.value:
@@ -203,14 +266,18 @@ def ModelController(model: solara.Reactive[Model], play_interval=100):
 
     def do_step():
         """Advance the model by one step."""
-        model.value.step()
+        simulator.run_for(1)
         running.value = model.value.running
+        force_update()
 
     def do_reset():
         """Reset the model to its initial state."""
         playing.value = False
         running.value = True
-        model.value = copy.deepcopy(original_model.value)
+        simulator.reset()
+        model.value = model.value = model.value.__class__(
+            simulator, **model_parameters.value
+        )
 
     def do_play_pause():
         """Toggle play/pause."""
@@ -269,7 +336,12 @@ def check_param_is_fixed(param):
 
 
 @solara.component
-def ModelCreator(model, model_params, seed=1):
+def ModelCreator(
+    model: solara.Reactive[Model],
+    user_params: dict,
+    *,
+    model_parameters: dict | solara.Reactive[dict] = None,
+):
     """Solara component for creating and managing a model instance with user-defined parameters.
 
     This component allows users to create a model instance with specified parameters and seed.
@@ -277,9 +349,9 @@ def ModelCreator(model, model_params, seed=1):
     number generator.
 
     Args:
-        model (solara.Reactive[Model]): A reactive model instance. This is the main model to be created and managed.
-        model_params (dict): Dictionary of model parameters. This includes both user-adjustable parameters and fixed parameters.
-        seed (int, optional): Initial seed for the random number generator. Defaults to 1.
+        model: A reactive model instance. This is the main model to be created and managed.
+        user_params: Parameters for (re-)instantiating a model. Can include user-adjustable parameters and fixed parameters. Defaults to None.
+        model_parameters: reactive parameters for reinitializing the model
 
     Returns:
         solara.component: A Solara component that renders the model creation and management interface.
@@ -300,24 +372,24 @@ def ModelCreator(model, model_params, seed=1):
         - The component provides an interface for adjusting user-defined parameters and reseeding the model.
 
     """
+    if model_parameters is None:
+        model_parameters = {}
+    model_parameters = solara.use_reactive(model_parameters)
+
     solara.use_effect(
         lambda: _check_model_params(model.value.__class__.__init__, fixed_params),
         [model.value],
     )
+    user_params, fixed_params = split_model_params(user_params)
 
-    user_params, fixed_params = split_model_params(model_params)
-
-    model_parameters, set_model_parameters = solara.use_state(
-        {
-            **fixed_params,
-            **{k: v.get("value") for k, v in user_params.items()},
-        }
-    )
+    # set model_parameters to the default values for all parameters
+    model_parameters.value = {
+        **fixed_params,
+        **{k: v.get("value") for k, v in user_params.items()},
+    }
 
     def on_change(name, value):
-        new_model_parameters = {**model_parameters, name: value}
-        model.value = model.value.__class__(**new_model_parameters)
-        set_model_parameters(new_model_parameters)
+        model_parameters.value = {**model_parameters.value, name: value}
 
     UserInputs(user_params, on_change=on_change)
 
@@ -338,10 +410,11 @@ def _check_model_params(init_func, model_params):
             model_parameters[name].default == inspect.Parameter.empty
             and name not in model_params
             and name != "self"
+            and name != "kwargs"
         ):
             raise ValueError(f"Missing required model parameter: {name}")
     for name in model_params:
-        if name not in model_parameters:
+        if name not in model_parameters and "kwargs" not in model_parameters:
             raise ValueError(f"Invalid model parameter: {name}")
 
 
@@ -409,6 +482,12 @@ def UserInputs(user_params, on_change=None):
                 on_value=change_handler,
                 value=options.get("value"),
             )
+        elif input_type == "InputText":
+            solara.InputText(
+                label=label,
+                on_value=change_handler,
+                value=options.get("value"),
+            )
         else:
             raise ValueError(f"{input_type} is not a supported input type")