This is a pathfinding PR for #2921, under active development. The goal is to explore the structure, design and API, and gather feedback before finalizing. Breaking changes may occur as we iterate.

Summary

This PR introduces a unified API for time advancement and event scheduling, integrating these capabilities directly into the Model class. It represents the first implementation step toward the design outlined in #2921.

Motive

Currently, Mesa's experimental discrete event simulation requires users to manage two separate objects:

simulator = ABMSimulator()
model = MyModel()
simulator.setup(model)
simulator.schedule_event_absolute(callback, time=50)
simulator.run_until(100)

This raises unnecessary questions: Why do I need a simulator? What's the difference between ABMSimulator and DEVSimulator? What does setup() do? For most users building standard ABMs, these questions shouldn't exist.

The deeper motivation is enabling a smooth progression from simple step-based models to full discrete-event simulation without rewriting code. A user should be able to:

1. Start with just step() and run(steps=100)
2. Add scheduled events when needed (model.schedule(drought, at=50))
3. Have agents schedule their own events (self.model.schedule(self.release, after=sentence))
4. Eventually build pure event-driven models with no regular stepping

All using the same unified API, without switching between different simulator classes or paradigms.

Implementation

The implementation uses composition to keep concerns separated:

• Scheduler (new class in scheduler.py): Owns the EventList and implements all scheduling/execution logic
• Model: Adds thin delegation methods (schedule(), run(), cancel()) that forward to the internal Scheduler
• Simulator classes: Deprecated but still functional, now delegate to Model's API

This design keeps Model focused (~50 new lines) while the Scheduler contains the complexity (~150 lines). The Scheduler can be tested independently and potentially subclassed for custom behavior.

Usage Examples

API is non-final, we're currently exploring both keyword argument and separate method APIs. This implemenation uses keyword arguments.

Simple step-based model (unchanged):

class MyModel(Model):
    def step(self):
        self.agents.shuffle_do("step")

model = MyModel()
model.run(steps=100)

Adding scheduled events:

class DroughtModel(Model):
    def __init__(self):
        super().__init__()
        self.schedule(self.drought, at=50.0)  # One-off event
    
    def step(self):
        self.agents.shuffle_do("step")
    
    def drought(self):
        self.grass_level *= 0.5

model = DroughtModel()
model.run(until=100)

Migration from old API:

# Before
simulator = ABMSimulator()
model = WolfSheep()
simulator.setup(model)
simulator.schedule_event_absolute(callback, time=50)
simulator.run_until(100)

# After
model = WolfSheep()
model.schedule(callback, at=50)
model.run(until=100)

Additional Notes

What this PR does NOT include (yet):

• The recurring parameter for automatic method scheduling (needs more design discussion)
• Decorator-based scheduling (@scheduled)
• Changes to DataCollector or visualization integration

Open questions for reviewers:

1. Is the composition approach (Model → Scheduler) the right separation?
2. Should _scheduler be public (scheduler) for advanced users?
3. How far do we want to go in providing backwards compatibility?

Related:

• Proposal discussion: Proposal: Unified Time and Event Scheduling API #2921
• Original DEVS implementation: mesa/experimental/devs/