Add model.time as universal source of truth for simulation time

This commit introduces `model.time` as the single, canonical source for simulation time in Mesa, addressing the long-standing issue of having multiple competing time sources (model.steps, simulator.time) that caused confusion and required workarounds in components like DataCollector, visualization, and the experimental ContinuousObservable.

Previously, time information was scattered: basic models only had `model.steps`, while models using simulators had to access `simulator.time`. This forced components to implement fallback chains like checking for simulator.time, then model.time, then model.steps. The new design establishes `model.time` as the ground truth that all components can rely on.

Key changes to mesa/model.py:
- Add `time: float = 0.0` attribute that tracks simulation time
- Add `step_duration: float = 1.0` parameter allowing customization of how much time passes per step (useful for staged activation where you might want 0.25 per stage)
- Add `_simulator: Simulator | None` to track whether a simulator controls time progression
- Modify `_wrapped_step()` to only auto-increment time when no simulator is attached

Key changes to mesa/experimental/devs/simulator.py:
- Remove `self.time` from Simulator, now writes directly to `model.time`
- Add deprecated `time` property that delegates to `model.time` with a DeprecationWarning for backward compatibility
- Register simulator with model via `model._simulator = self` in setup()
- Update all time reads/writes to use `model.time` instead of `self.time`
- Improve error messages to be more descriptive

The design intentionally keeps things minimal: no RunControl abstraction, no complex time management classes. Simulators simply write to `model.time` directly, and the default step wrapper increments time by `step_duration` when no simulator is attached. This provides a single way to do things while remaining backward compatible.

Author: EwoutH

mesa/experimental/devs/__init__.py

@@ -19,6 +19,6 @@
 """
 
 from .eventlist import Priority, SimulationEvent
-from .simulator import ABMSimulator, DEVSimulator
+from .simulator import ABMSimulator, DEVSimulator, Simulator
 
-__all__ = ["ABMSimulator", "DEVSimulator", "Priority", "SimulationEvent"]
+__all__ = ["ABMSimulator", "DEVSimulator", "Priority", "SimulationEvent", "Simulator"]

mesa/experimental/devs/simulator.py

@@ -23,6 +23,7 @@
 from __future__ import annotations
 
 import numbers
+import warnings
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
@@ -61,9 +62,17 @@ def __init__(self, time_unit: type, start_time: int | float):
         self.event_list = EventList()
         self.start_time = start_time
         self.time_unit = time_unit
-
-        self.time = self.start_time
-        self.model = None
+        self.model: Model | None = None
+
+    @property
+    def time(self) -> float:
+        """Simulator time (deprecated)."""
+        warnings.warn(
+            "simulator.time is deprecated, use model.time instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.model.time
 
     def check_time_unit(self, time: int | float) -> bool: ...  # noqa: D102
 
@@ -78,22 +87,24 @@ def setup(self, model: Model) -> None:
             Exception if event list is not empty
 
         """
-        if self.time != self.start_time:
+        if model.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?"
+                f"Model time ({model.time}) does not match simulator start_time ({self.start_time}). "
+                "Has the model already been run?"
             )
         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"
-            )
+            raise ValueError("Events already scheduled. Call setup before scheduling.")
 
         self.model = model
+        model._simulator = self  # Register simulator with model
 
     def reset(self):
-        """Reset the simulator by clearing the event list and removing the model to simulate."""
+        """Reset the simulator."""
         self.event_list.clear()
-        self.model = None
-        self.time = self.start_time
+        if self.model is not None:
+            self.model._simulator = None
+            self.model.time = self.start_time
+            self.model = None
 
     def run_until(self, end_time: int | float) -> None:
         """Run the simulator until the end time.
@@ -106,23 +117,23 @@ def run_until(self, end_time: int | float) -> None:
 
         """
         if self.model is None:
-            raise Exception(
-                "simulator has not been setup, call simulator.setup(model) first"
+            raise RuntimeError(
+                "Simulator not set up. Call simulator.setup(model) first."
             )
 
         while True:
             try:
                 event = self.event_list.pop_event()
-            except IndexError:  # event list is empty
-                self.time = end_time
+            except IndexError:
+                self.model.time = end_time
                 break
 
             if event.time <= end_time:
-                self.time = event.time
+                self.model.time = event.time
                 event.execute()
             else:
-                self.time = end_time
-                self._schedule_event(event)  # reschedule event
+                self.model.time = end_time
+                self._schedule_event(event)
                 break
 
     def run_next_event(self):
@@ -133,17 +144,17 @@ def run_next_event(self):
 
         """
         if self.model is None:
-            raise Exception(
-                "simulator has not been setup, call simulator.setup(model) first"
+            raise RuntimeError(
+                "Simulator not set up. Call simulator.setup(model) first."
             )
 
         try:
             event = self.event_list.pop_event()
-        except IndexError:  # event list is empty
+        except IndexError:
             return
-        else:
-            self.time = event.time
-            event.execute()
+
+        self.model.time = event.time
+        event.execute()
 
     def run_for(self, time_delta: int | float):
         """Run the simulator for the specified time delta.
@@ -154,7 +165,7 @@ def run_for(self, time_delta: int | float):
 
         """
         # fixme, raise initialization error or something like it if model.setup has not been called
-        end_time = self.time + time_delta
+        end_time = self.model.time + time_delta
         self.run_until(end_time)
 
     def schedule_event_now(
@@ -240,7 +251,7 @@ def schedule_event_relative(
 
         """
         event = SimulationEvent(
-            self.time + time_delta,
+            self.model.time + time_delta,
             function,
             priority=priority,
             function_args=function_args,
@@ -344,29 +355,29 @@ def run_until(self, end_time: int) -> None:
 
         """
         if self.model is None:
-            raise Exception(
-                "simulator has not been setup, call simulator.setup(model) first"
+            raise RuntimeError(
+                "Simulator not set up. Call simulator.setup(model) first."
             )
 
         while True:
             try:
                 event = self.event_list.pop_event()
             except IndexError:
-                self.time = end_time
+                self.model.time = float(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
+                self.model.time = float(event.time)
+
+                # Reschedule model.step for next tick if this is a step event
                 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.model.time = float(end_time)
                 self._schedule_event(event)
                 break
 

mesa/model.py

@@ -17,6 +17,7 @@
 import numpy as np
 
 from mesa.agent import Agent, AgentSet
+from mesa.experimental.devs import Simulator
 from mesa.mesa_logging import create_module_logger, method_logger
 
 SeedLike = int | np.integer | Sequence[int] | np.random.SeedSequence
@@ -52,6 +53,7 @@ def __init__(
         *args: Any,
         seed: float | None = None,
         rng: RNGLike | SeedLike | None = None,
+        step_duration: float = 1.0,
         **kwargs: Any,
     ) -> None:
         """Create a new model.
@@ -65,15 +67,21 @@ def __init__(
             rng : Pseudorandom number generator state. When `rng` is None, a new `numpy.random.Generator` is created
                   using entropy from the operating system. Types other than `numpy.random.Generator` are passed to
                   `numpy.random.default_rng` to instantiate a `Generator`.
+            step_duration: How much time advances each step (default 1.0)
             kwargs: keyword arguments to pass onto super
 
         Notes:
             you have to pass either seed or rng, but not both.
 
         """
         super().__init__(*args, **kwargs)
-        self.running = True
+        self.running: bool = True
         self.steps: int = 0
+        self.time: float = 0.0
+        self.step_duration: float = step_duration
+
+        # Track if a simulator is controlling time
+        self._simulator: Simulator | None = None
 
         if (seed is not None) and (rng is not None):
             raise ValueError("you have to pass either rng or seed, not both")
@@ -117,7 +125,13 @@ def _wrapped_step(self, *args: Any, **kwargs: Any) -> None:
         """Automatically increments time and steps after calling the user's step method."""
         # Automatically increment time and step counters
         self.steps += 1
-        _mesa_logger.info(f"calling model.step for timestep {self.steps} ")
+        # Only auto-increment time if no simulator is controlling it
+        if self._simulator is None:
+            self.time += self.step_duration
+
+        _mesa_logger.info(
+            f"calling model.step for step {self.steps} at time {self.time}"
+        )
         # Call the original user-defined step method
         self._user_step(*args, **kwargs)