Mesa 2.2.3__py3-none-any.whl → 2.3.0__py3-none-any.whl

mesa/experimental/devs/simulator.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import numbers
+from typing import Any, Callable
+
+from mesa import Model
+
+from .eventlist import EventList, Priority, SimulationEvent
+
+
+class Simulator:
+    """The Simulator controls the time advancement of the model.
+
+    The simulator uses next event time progression to advance the simulation time, and execute the next event
+
+    Attributes:
+        event_list (EventList): The list of events to execute
+        time (float | int): The current simulation time
+        time_unit (type) : The unit of the simulation time
+        model (Model): The model to simulate
+
+
+    """
+
+    # TODO: add replication support
+    # TODO: add experimentation support
+
+    def __init__(self, time_unit: type, start_time: int | float):
+        # should model run in a separate thread,
+        # and we can then interact with start, stop, run_until, and step?
+        self.event_list = EventList()
+        self.start_time = start_time
+        self.time_unit = time_unit
+
+        self.time = self.start_time
+        self.model = None
+
+    def check_time_unit(self, time: int | float) -> bool: ...
+
+    def setup(self, model: Model) -> None:
+        """Set up the simulator with the model to simulate
+
+        Args:
+            model (Model): The model to simulate
+
+        """
+        self.event_list.clear()
+        self.model = model
+
+    def reset(self):
+        """Reset the simulator by clearing the event list and removing the model to simulate"""
+        self.event_list.clear()
+        self.model = None
+        self.time = self.start_time
+
+    def run_until(self, end_time: int | float) -> None:
+        while True:
+            try:
+                event = self.event_list.pop_event()
+            except IndexError:  # event list is empty
+                self.time = end_time
+                break
+
+            if event.time <= end_time:
+                self.time = event.time
+                event.execute()
+            else:
+                self.time = end_time
+                self._schedule_event(event)  # reschedule event
+                break
+
+    def run_for(self, time_delta: int | float):
+        """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
+        self.run_until(end_time)
+
+    def schedule_event_now(
+        self,
+        function: Callable,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> SimulationEvent:
+        """Schedule event for the current time instant
+
+        Args:
+            function (Callable): The callable to execute for this event
+            priority (Priority): the priority of the event, optional
+            function_args (List[Any]): list of arguments for function
+            function_kwargs (Dict[str, Any]):  dict of keyword arguments for function
+
+        Returns:
+            SimulationEvent: the simulation event that is scheduled
+
+        """
+        return self.schedule_event_relative(
+            function,
+            0.0,
+            priority=priority,
+            function_args=function_args,
+            function_kwargs=function_kwargs,
+        )
+
+    def schedule_event_absolute(
+        self,
+        function: Callable,
+        time: int | float,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> SimulationEvent:
+        """Schedule event for the specified time instant
+
+        Args:
+            function (Callable): The callable to execute for this event
+            time (int | float): the time for which to schedule the event
+            priority (Priority): the priority of the event, optional
+            function_args (List[Any]): list of arguments for function
+            function_kwargs (Dict[str, Any]):  dict of keyword arguments for function
+
+        Returns:
+            SimulationEvent: the simulation event that is scheduled
+
+        """
+        if self.time > time:
+            raise ValueError("trying to schedule an event in the past")
+
+        event = SimulationEvent(
+            time,
+            function,
+            priority=priority,
+            function_args=function_args,
+            function_kwargs=function_kwargs,
+        )
+        self._schedule_event(event)
+        return event
+
+    def schedule_event_relative(
+        self,
+        function: Callable,
+        time_delta: int | float,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> SimulationEvent:
+        """Schedule event for the current time plus the time delta
+
+        Args:
+            function (Callable): The callable to execute for this event
+            time_delta (int | float): the time delta
+            priority (Priority): the priority of the event, optional
+            function_args (List[Any]): list of arguments for function
+            function_kwargs (Dict[str, Any]):  dict of keyword arguments for function
+
+        Returns:
+            SimulationEvent: the simulation event that is scheduled
+
+        """
+        event = SimulationEvent(
+            self.time + time_delta,
+            function,
+            priority=priority,
+            function_args=function_args,
+            function_kwargs=function_kwargs,
+        )
+        self._schedule_event(event)
+        return event
+
+    def cancel_event(self, event: SimulationEvent) -> None:
+        """remove the event from the event list
+
+        Args:
+            event (SimulationEvent): The simulation event to remove
+
+        """
+
+        self.event_list.remove(event)
+
+    def _schedule_event(self, event: SimulationEvent):
+        if not self.check_time_unit(event.time):
+            raise ValueError(
+                f"time unit mismatch {event.time} is not of time unit {self.time_unit}"
+            )
+
+        # check timeunit of events
+        self.event_list.add_event(event)
+
+
+class ABMSimulator(Simulator):
+    """This simulator uses incremental time progression, while allowing for additional event scheduling.
+
+    The basic time unit of this simulator is an integer. It schedules `model.step` for each tick with the
+    highest priority. This implies that by default, `model.step` is the first event executed at a specific tick.
+    In addition, discrete event scheduling, using integer as the time unit is fully supported, paving the way
+    for hybrid ABM-DEVS simulations.
+
+    """
+
+    def __init__(self):
+        super().__init__(int, 0)
+
+    def setup(self, model):
+        super().setup(model)
+        self.schedule_event_now(self.model.step, priority=Priority.HIGH)
+
+    def check_time_unit(self, time) -> bool:
+        if isinstance(time, int):
+            return True
+        if isinstance(time, float):
+            return time.is_integer()
+        else:
+            return False
+
+    def schedule_event_next_tick(
+        self,
+        function: Callable,
+        priority: Priority = Priority.DEFAULT,
+        function_args: list[Any] | None = None,
+        function_kwargs: dict[str, Any] | None = None,
+    ) -> SimulationEvent:
+        """Schedule a SimulationEvent for the next tick
+
+        Args
+            function (Callable): the callable to execute
+            priority (Priority): the priority of the event
+            function_args (List[Any]): List of arguments to pass to the callable
+            function_kwargs (Dict[str, Any]): List of keyword arguments to pass to the callable
+
+        """
+        return self.schedule_event_relative(
+            function,
+            1,
+            priority=priority,
+            function_args=function_args,
+            function_kwargs=function_kwargs,
+        )
+
+    def run_until(self, end_time: int) -> None:
+        """run the simulator up to and included the specified end time
+
+        Args:
+            end_time (float| int): The end_time delta. The simulator is until the specified end time
+
+        """
+        while True:
+            try:
+                event = self.event_list.pop_event()
+            except IndexError:
+                self.time = end_time
+                break
+
+            if event.time <= end_time:
+                self.time = event.time
+                if event.fn() == self.model.step:
+                    self.schedule_event_next_tick(
+                        self.model.step, priority=Priority.HIGH
+                    )
+
+                event.execute()
+            else:
+                self.time = end_time
+                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. Can be used for full-blown discrete event simulating using
+    event scheduling.
+
+    """
+
+    def __init__(self):
+        super().__init__(float, 0.0)
+
+    def check_time_unit(self, time) -> bool:
+        return isinstance(time, numbers.Number)

mesa/experimental/jupyter_viz.py

@@ -6,21 +6,59 @@ import reacton.ipywidgets as widgets
 import solara
 from solara.alias import rv
 
+import mesa.experimental.components.altair as components_altair
 import mesa.experimental.components.matplotlib as components_matplotlib
+from mesa.experimental.UserParam import Slider
 
 # Avoid interactive backend
 plt.switch_backend("agg")
 
 
+# TODO: Turn this function into a Solara component once the current_step.value
+# dependency is passed to measure()
+def Card(
+    model, measures, agent_portrayal, space_drawer, dependencies, color, layout_type
+):
+    with rv.Card(
+        style_=f"background-color: {color}; width: 100%; height: 100%"
+    ) as main:
+        if "Space" in layout_type:
+            rv.CardTitle(children=["Space"])
+            if space_drawer == "default":
+                # draw with the default implementation
+                components_matplotlib.SpaceMatplotlib(
+                    model, agent_portrayal, dependencies=dependencies
+                )
+            elif space_drawer == "altair":
+                components_altair.SpaceAltair(
+                    model, agent_portrayal, dependencies=dependencies
+                )
+            elif space_drawer:
+                # if specified, draw agent space with an alternate renderer
+                space_drawer(model, agent_portrayal)
+        elif "Measure" in layout_type:
+            rv.CardTitle(children=["Measure"])
+            measure = measures[layout_type["Measure"]]
+            if callable(measure):
+                # Is a custom object
+                measure(model)
+            else:
+                components_matplotlib.PlotMatplotlib(
+                    model, measure, dependencies=dependencies
+                )
+    return main
+
+
 @solara.component
 def JupyterViz(
     model_class,
     model_params,
     measures=None,
-    name="Mesa Model",
+    name=None,
     agent_portrayal=None,
     space_drawer="default",
     play_interval=150,
+    seed=None,
 ):
     """Initialize a component to visualize a model.
     Args:
@@ -34,64 +72,54 @@ def JupyterViz(
             simulations with no space to visualize should
             specify `space_drawer=False`
         play_interval: play interval (default: 150)
+        seed: the random seed used to initialize the model
     """
+    if name is None:
+        name = model_class.__name__
+
     current_step = solara.use_reactive(0)
 
     # 1. Set up model parameters
+    reactive_seed = solara.use_reactive(0)
     user_params, fixed_params = split_model_params(model_params)
     model_parameters, set_model_parameters = solara.use_state(
-        {**fixed_params, **{k: v["value"] for k, v in user_params.items()}}
+        {**fixed_params, **{k: v.get("value") for k, v in user_params.items()}}
     )
 
     # 2. Set up Model
     def make_model():
-        model = model_class(**model_parameters)
+        model = model_class.__new__(
+            model_class, **model_parameters, seed=reactive_seed.value
+        )
+        model.__init__(**model_parameters)
         current_step.value = 0
         return model
 
     reset_counter = solara.use_reactive(0)
     model = solara.use_memo(
-        make_model, dependencies=[*list(model_parameters.values()), reset_counter.value]
+        make_model,
+        dependencies=[
+            *list(model_parameters.values()),
+            reset_counter.value,
+            reactive_seed.value,
+        ],
     )
 
     def handle_change_model_params(name: str, value: any):
         set_model_parameters({**model_parameters, name: value})
 
-    def ColorCard(color, layout_type):
-        # TODO: turn this into a Solara component, but must pass in current
-        # step as a dependency for the plots, so that there is no flickering
-        # due to rerender.
-        with rv.Card(
-            style_=f"background-color: {color}; width: 100%; height: 100%"
-        ) as main:
-            if "Space" in layout_type:
-                rv.CardTitle(children=["Space"])
-                if space_drawer == "default":
-                    # draw with the default implementation
-                    components_matplotlib.SpaceMatplotlib(
-                        model, agent_portrayal, dependencies=[current_step.value]
-                    )
-                elif space_drawer:
-                    # if specified, draw agent space with an alternate renderer
-                    space_drawer(model, agent_portrayal)
-            elif "Measure" in layout_type:
-                rv.CardTitle(children=["Measure"])
-                measure = measures[layout_type["Measure"]]
-                if callable(measure):
-                    # Is a custom object
-                    measure(model)
-                else:
-                    components_matplotlib.make_plot(model, measure)
-        return main
-
     # 3. Set up UI
 
     with solara.AppBar():
         solara.AppBarTitle(name)
 
     # render layout and plot
+    def do_reseed():
+        reactive_seed.value = model.random.random()
 
     # jupyter
+    dependencies = [current_step.value, reactive_seed.value]
+
     def render_in_jupyter():
         with solara.GridFixed(columns=2):
             UserInputs(user_params, on_change=handle_change_model_params)
@@ -103,7 +131,11 @@ def JupyterViz(
             if space_drawer == "default":
                 # draw with the default implementation
                 components_matplotlib.SpaceMatplotlib(
-                    model, agent_portrayal, dependencies=[current_step.value]
+                    model, agent_portrayal, dependencies=dependencies
+                )
+            elif space_drawer == "altair":
+                components_altair.SpaceAltair(
+                    model, agent_portrayal, dependencies=dependencies
                 )
             elif space_drawer:
                 # if specified, draw agent space with an alternate renderer
@@ -111,13 +143,14 @@ def JupyterViz(
             # otherwise, do nothing (do not draw space)
 
             # 5. Plots
-
             for measure in measures:
                 if callable(measure):
                     # Is a custom object
                     measure(model)
                 else:
-                    components_matplotlib.make_plot(model, measure)
+                    components_matplotlib.PlotMatplotlib(
+                        model, measure, dependencies=dependencies
+                    )
 
     def render_in_browser():
         # if space drawer is disabled, do not include it
@@ -126,18 +159,32 @@ def JupyterViz(
         if measures:
             layout_types += [{"Measure": elem} for elem in range(len(measures))]
 
-        grid_layout_initial = get_initial_grid_layout(layout_types=layout_types)
+        grid_layout_initial = make_initial_grid_layout(layout_types=layout_types)
         grid_layout, set_grid_layout = solara.use_state(grid_layout_initial)
 
         with solara.Sidebar():
             with solara.Card("Controls", margin=1, elevation=2):
+                solara.InputText(
+                    label="Seed",
+                    value=reactive_seed,
+                    continuous_update=True,
+                )
                 UserInputs(user_params, on_change=handle_change_model_params)
                 ModelController(model, play_interval, current_step, reset_counter)
-            with solara.Card("Progress", margin=1, elevation=2):
-                solara.Markdown(md_text=f"####Step - {current_step}")
+                solara.Button(label="Reseed", color="primary", on_click=do_reseed)
+            with solara.Card("Information", margin=1, elevation=2):
+                solara.Markdown(md_text=f"Step - {current_step}")
 
         items = [
-            ColorCard(color="white", layout_type=layout_types[i])
+            Card(
+                model,
+                measures,
+                agent_portrayal,
+                space_drawer,
+                dependencies,
+                color="white",
+                layout_type=layout_types[i],
+            )
             for i in range(len(layout_types))
         ]
         solara.GridDraggable(
@@ -178,7 +225,7 @@ def ModelController(model, play_interval, current_step, reset_counter):
     def do_step():
         model.step()
         previous_step.value = current_step.value
-        current_step.value += 1
+        current_step.value = model._steps
 
     def do_play():
         model.running = True
@@ -215,7 +262,11 @@ def ModelController(model, play_interval, current_step, reset_counter):
         solara.Style(
             """
         .widget-play {
-            height: 30px;
+            height: 35px;
+        }
+        .widget-play button {
+            color: white;
+            background-color: #1976D2;  // Solara blue color
         }
         """
         )
@@ -251,6 +302,8 @@ def split_model_params(model_params):
 
 
 def check_param_is_fixed(param):
+    if isinstance(param, Slider):
+        return False
     if not isinstance(param, dict):
         return True
     if "type" not in param:
@@ -270,13 +323,27 @@ def UserInputs(user_params, on_change=None):
     """
 
     for name, options in user_params.items():
-        # label for the input is "label" from options or name
-        label = options.get("label", name)
-        input_type = options.get("type")
 
         def change_handler(value, name=name):
             on_change(name, value)
 
+        if isinstance(options, Slider):
+            slider_class = (
+                solara.SliderFloat if options.is_float_slider else solara.SliderInt
+            )
+            slider_class(
+                options.label,
+                value=options.value,
+                on_value=change_handler,
+                min=options.min,
+                max=options.max,
+                step=options.step,
+            )
+            continue
+
+        # label for the input is "label" from options or name
+        label = options.get("label", name)
+        input_type = options.get("type")
         if input_type == "SliderInt":
             solara.SliderInt(
                 label,
@@ -319,20 +386,15 @@ def make_text(renderer):
     return function
 
 
-def get_initial_grid_layout(layout_types):
-    grid_lay = []
-    y_coord = 0
-    for ii in range(len(layout_types)):
-        template_layout = {"h": 10, "i": 0, "moved": False, "w": 6, "y": 0, "x": 0}
-        if ii == 0:
-            grid_lay.append(template_layout)
-        else:
-            template_layout.update({"i": ii})
-            if ii % 2 == 0:
-                template_layout.update({"x": 0})
-                y_coord += 16
-            else:
-                template_layout.update({"x": 6})
-            template_layout.update({"y": y_coord})
-            grid_lay.append(template_layout)
-    return grid_lay
+def make_initial_grid_layout(layout_types):
+    return [
+        {
+            "i": i,
+            "w": 6,
+            "h": 10,
+            "moved": False,
+            "x": 6 * (i % 2),
+            "y": 16 * (i - i % 2),
+        }
+        for i in range(len(layout_types))
+    ]

mesa/main.py

@@ -30,11 +30,14 @@ def runserver(project):
     PROJECT is the path to the directory containing `run.py`, or the current
     directory if not specified.
     """
-    run_path = Path(project) / "run.py"
-    if not run_path.exists():
-        sys.exit(f"ERROR: file {run_path} does not exist")
-    args = [sys.executable, str(run_path)]
-    call(args)
+    run_files = ["run.py", "server.py"]
+    for run_file in run_files:
+        run_path = Path(project) / run_file
+        if not run_path.exists():
+            continue
+        args = [sys.executable, str(run_path)]
+        call(args)
+    sys.exit(f"ERROR: file run.py or server.py (in {Path(project)}) does not exist")
 
 
 @click.command()

mesa/model.py

@@ -3,6 +3,7 @@ The model class for Mesa framework.
 
 Core Objects: Model
 """
+
 # Mypy; for the `|` operator purpose
 # Remove this __future__ import once the oldest supported Python is 3.10
 from __future__ import annotations
@@ -13,11 +14,13 @@ import warnings
 from collections import defaultdict
 
 # mypy
-from typing import Any
+from typing import Any, Union
 
 from mesa.agent import Agent, AgentSet
 from mesa.datacollection import DataCollector
 
+TimeT = Union[float, int]
+
 
 class Model:
     """Base class for models in the Mesa ABM library.
@@ -53,8 +56,11 @@ class Model:
         if obj._seed is None:
             # We explicitly specify the seed here so that we know its value in
             # advance.
-            obj._seed = random.random()  # noqa: S311
+            obj._seed = random.random()
         obj.random = random.Random(obj._seed)
+        # TODO: Remove these 2 lines just before Mesa 3.0
+        obj._steps = 0
+        obj._time = 0
         return obj
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -68,8 +74,8 @@ class Model:
         self.current_id = 0
         self.agents_: defaultdict[type, dict] = defaultdict(dict)
 
-        # Warning flags for current experimental features. These make sure a warning is only printed once per model.
-        self.agentset_experimental_warning_given = False
+        self._steps: int = 0
+        self._time: TimeT = 0  # the model's clock
 
     @property
     def agents(self) -> AgentSet:
@@ -112,6 +118,11 @@ class Model:
     def step(self) -> None:
         """A single step. Fill in here."""
 
+    def _advance_time(self, deltat: TimeT = 1):
+        """Increment the model's steps counter and clock."""
+        self._steps += 1
+        self._time += deltat
+
     def next_id(self) -> int:
         """Return the next unique ID for agents, increment current_id"""
         self.current_id += 1