Summary

Exposes event scheduling and time advancement methods directly on Model, giving users a public API for scheduling events and advancing simulation time without needing to interact with the Simulator class.

Basically, these methods allow us:

• to replace all existing behavior (in examples, tutorials, etc.)
• start deprecation all current scheduling and stepping APIs
• remove them in Mesa 4.

Motive

Currently, users advance their models by calling model.step(), which is tightly coupled to the concept of a single discrete step. With the event-based architecture taking shape (#3201, #3204), we need public methods that let users think in terms of time rather than steps.

The key method here is model.run_for(duration). For existing ABM users, model.run_for(1) is functionally equivalent to model.step(): it advances time by 1 unit, which triggers the scheduled step event. But unlike step(), it generalizes naturally: run_for(0.5) advances half a time unit, run_for(100) advances 100 units processing all scheduled events along the way. This makes run_for the foundation for both traditional ABMs and event-driven models.

This is also a stepping stone toward deprecating model.step() as the primary way to advance a model. Instead of calling a method that is a step, users call a method that advances time, and steps happen as scheduled events within that time. The mental model shifts from "execute step N" to "advance time, and whatever is scheduled will run."

Implementation

Four new public methods on Model:

• schedule_event(function, *, at, after, priority): schedule a one-off event at an absolute or relative time
• schedule_recurring(function, schedule, priority): schedule a recurring event using a Schedule object, returns an EventGenerator
• run_for(duration): advance time by the given duration, processing all events
• run_until(end_time): advance time to an absolute point, processing all events

All four are thin wrappers around existing internal machinery (_event_list, _advance_time, EventGenerator).

Model also stores strong references to active EventGenerators in _event_generators to prevent garbage collection — SimulationEvent wraps bound methods in WeakMethod, so without this a fire-and-forget schedule_recurring() call would silently stop working.

Testing

Tests cover run_for, run_until, schedule_event (at/after/cancel/validation), and schedule_recurring (fixed interval/stop/count). Includes an explicit gc.collect() regression test for the WeakMethod lifetime issue.

Usage Examples

Drop-in replacement for model.step():

# Old
for _ in range(100):
    model.step()

# New — functionally identical
for _ in range(100):
    model.run_for(1)

# Or simply
model.run_for(100)

Schedule custom events alongside steps:

class MyModel(mesa.Model):
    def __init__(self):
        super().__init__()
        # Schedule a one-off event
        self.schedule_event(self.market_crash, at=50.0)

        # Schedule recurring data export every 10 time units
        self.schedule_recurring(
            self.export_data,
            Schedule(interval=10.0, start=10.0),
        )

    def step(self):
        self.agents.shuffle_do("step")

Run to a specific time:

model = MyModel()
model.run_until(500.0)  # run until t=500, executing all scheduled events

Additional Notes

• No breaking changes, model.step() continues to work exactly as before
• run_for(1) and step() produce identical results for standard ABMs, since both advance time by 1 unit and trigger the same scheduled step event
• schedule_event and schedule_recurring return their event/generator objects, allowing cancellation via .cancel() / .stop()
• These methods work both with and without a Simulator attached

One we agree on the API I will add tests. In separate PRs we can update examples and tutorials and deprecate old API surfaces.