Summary

Introduces model.time as the single, canonical source of simulation time in Mesa. All components (DataCollector, visualization, user code, simulators) can now rely on model.time to get the current simulation time, regardless of whether the model uses simple stepping or discrete event simulation.

Motive

Previously, time in Mesa was fragmented across different locations depending on the simulation mode:

• Simple models used model.steps as a proxy for time
• Discrete event simulations stored time in simulator.time
• Components needing time had to implement fallback chains like:

  def _get_time(self):
      if hasattr(model, "simulator") and hasattr(model.simulator, "time"):
          return model.simulator.time
      if hasattr(model, "time"):
          return model.time
      return float(model.steps)

This caused problems for features that need consistent time access, such as the ContinuousObservable in #2851 and the conceptual model of space discussed in #2585. The discussion in #2228 (which originated in #2223) established consensus that Mesa needs a universal truth for time.

Implementation

Model class changes:

• Add time: float attribute initialized to 0.0
• Add step_duration: float parameter (default 1.0) controlling time advancement per step
• Add _simulator: Simulator | None to track if a simulator controls time
• Modify _wrapped_step() to only auto-increment time when no simulator is attached

Simulator class changes:

• Remove internal self.time attribute
• Write directly to model.time during event execution
• Add deprecated time property delegating to model.time for backward compatibility
• Register with model via model._simulator = self in setup()
• Reset model.time to start_time in reset()

Design kept minimal: a simple attribute rather than a property or RunControl class, following YAGNI principles while solving the immediate problem.

Usage Examples

Basic usage (time auto-increments with steps):

model = Model()
model.step()
print(model.time)  # 1.0
model.step()
print(model.time)  # 2.0

Custom step duration (useful for staged activation):

model = Model(step_duration=0.25)
model.step()
print(model.time)  # 0.25
model.step()
print(model.time)  # 0.5

With discrete event simulator (simulator controls time):

model = Model()
simulator = DEVSimulator()
simulator.setup(model)

simulator.schedule_event_absolute(some_function, 2.5)
simulator.run_until(3.0)
print(model.time)  # 3.0

Components can now simply use model.time:

class MyDataCollector:
    def collect(self, model):
        timestamp = model.time  # Always works, no fallbacks needed

Compatibility

• simulator.time still works but emits a DeprecationWarning directing users to model.time (considering DEVS is still experimental, this is quite gentle)
• Code directly accessing simulator.time without triggering the property (unlikely) would break (again, experimental, and all test pass)

Additional Notes

• Closes the implementation side of The time variable in mesa.Model #2228
• Enables cleaner implementation of Add ContinuousStates and -Observables #2851 (ContinuousObservable)
• In the future we might want to allow datetime values for time.