Based on the discussions and accumulating insights in #3155 and #2921 (comment), a new implementation that implements the single schedule() method.

Builds on #3155. Can either be directly merged or after #3155 (I recommend former).

What's quite cool is that it schedules a model.step() event every 1 time. So like a ABMSimulator by default. Like a hearth beat. Can easily be turned off for full DEVS.

That also makes it super super backwards compatible.

Design decisions

I started from the following design decisions:

• We want a single, powerful schedule function. Utility functions come second and syntactic suger like decorators third.
• Same goes for run: Powerful run function, then utility functions.
• The RecurringEvent is a very useful concept. It should have methods to pause, resume and stop.
• The step is going to be the hearth beat of Mesa. This keeps backwards compatibility and a familiar way for basic models, with the only difference for them being to run a model with run() instead of repeated step calls. Internally, it's just a scheduled function with interval 1, and can be overwritten.
• The model.schedule() method returns the Event or RecurringEvent object directly, which in case of Recurring has methods like pause(), resume(), and cancel() for user control.
• Users who need to modify or cancel scheduled events simply keep a reference to the returned object (e.g., self.trading = model.schedule(self.trade, interval=1)), while one-off events that don't need later control can ignore the return value.
• The default step method is automatically scheduled as a RecurringEvent with interval=1 and stored in self.step_event, making it easy to introspect or modify the model's heartbeat.
• We're not implementing a central registry of central events for now, users manage their own event references as needed.

Methods

Some methods

# Schedule method
model.schedule(
    callback,
    start_at=None,      # Absolute time to start
    start_after=None,   # Delay before starting  
    interval=None,      # Time between recurrences (None = one-off, number or callable)
    count=None,         # Max executions (None = infinite for recurring, 1 for one-off)
    end_at=None,        # Absolute time to stop
    end_after=None,     # Duration to run (from first execution)
    priority=Priority.DEFAULT,
    args=None,
    kwargs=None,
) -> SimulationEvent | RecurringEvent

Return Values

• One-off events return SimulationEvent
• Recurring events return RecurringEvent with pause(), resume(), stop() methods

Default Step Behavior

• Model.__init__ automatically schedules self.step as a RecurringEvent with interval=1
• Stored in self.step_event for user access/modification
• Users override step() method, the scheduling is automatic

Convenience Methods

• model.schedule_at(callback, time, ...) → wraps schedule(start_at=time)
• model.schedule_after(callback, delay, ...) → wraps schedule(start_after=delay)

Run Methods

• model.run_for(duration) - run for N time units
• model.run_until(end_time) - run until absolute time
• model.run_while(condition) - run while condition is true
• model.run_next_event() - single event execution (debugging)

TODO

• Fix recurring event pausing
• Update PR description
• Update migration guide

Follow-up PRs:

• Deprecate simulators
• Update example models which use simulators
• Update tutorial

(please do not update, rebase or touch my branch in any way)