Proposal: Unified Time and Event Scheduling API

[EwoutH]

Summary

This proposal redesigns Mesa's time advancement and event scheduling into a simple, unified API. The goal: make simple models simple, while enabling advanced discrete-event simulation for those who need it.

And everything in between.

Key changes:

• Remove the separate Simulator classes (ABMSimulator, DEVSimulator)
• Integrate all functionality directly into Model
• Provide unified run() and schedule() methods
• Make step() optional sugar that's automatically scheduled

Motivation

The problem with two objects

The current experimental DEVS implementation requires users to manage two separate objects:

simulator = ABMSimulator()
model = MyModel()
simulator.setup(model)
simulator.run_until(100)

This raises immediate questions: Why do I need a simulator? What's the difference between ABMSimulator and DEVSimulator? What does setup() do? When would I call reset()?

For most users, these questions shouldn't exist. They have a model, they want to run it.

The simplest API imaginable

Let's try to make it as simple as possible. You get something like:

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

The simulator is an implementation detail. Users shouldn't need to think about it.

Proposed API

Running models

model.run(until=100)              # Run until time reaches 100
model.run(duration=50)            # Run for 50 time units from now
model.run(condition=lambda m: m.running)  # Run while condition is True

Scheduling events

model.schedule(callback, at=50.0)     # At absolute time
model.schedule(callback, after=10.0)  # Relative to now

# With priority for simultaneous events
model.schedule(callback, at=50.0, priority=Priority.HIGH)

# Cancel if needed
event = model.schedule(callback, at=5)
event.cancel()

Model initialization

class Model:
    def __init__(self, seed=None, recurring="step"):
        """
        Args:
            seed: Random seed for reproducibility
            recurring: Methods to schedule automatically
                - str: Method name called every 1.0 time units
                - dict[str, float]: Method names mapped to intervals
                - None: No automatic scheduling (pure event-driven)
        """

Usage progression

The API lets users start simple and incrementally adopt advanced features without rewriting their model. I think this is the coolest part of an unified API.

Level 1: Just define step()

This is how most Mesa models work today, and it continues to work unchanged:

class WolfSheep(Model):
    def __init__(self, n_wolves, n_sheep):
        super().__init__()
        Wolf.create_agents(self, n_wolves)
        Sheep.create_agents(self, n_sheep)
    
    def step(self):
        self.agents.shuffle_do("step")

model = WolfSheep(10, 20)
model.run(duration=100)  # step() called at t=1, 2, 3, ... 100

No simulators, no setup, no complexity. Define step(), call run().

Level 2: Add scheduled events

Now suppose you want a drought to occur at t=50. Just schedule it:

class WolfSheep(Model):
    def __init__(self, n_wolves, n_sheep):
        super().__init__()
        Wolf.create_agents(self, n_wolves)
        Sheep.create_agents(self, n_sheep)
        
        # One-off event alongside regular stepping
        self.schedule(self.drought, at=50)
    
    def step(self):
        self.agents.shuffle_do("step")
    
    def drought(self):
        self.grass_layer.modify_cells(lambda g: g * 0.5)

The model still steps normally at t=1, 2, 3..., and the drought fires at t=50. No changes to how you run the model.

Level 3: Agents scheduling events

Agents can schedule their own events. This is useful for agents that need to "wake up" after some time:

class Citizen(Agent):
    def __init__(self, model):
        super().__init__(model)
        self.in_jail = False
    
    def step(self):
        if self.in_jail:
            return  # Skip - release already scheduled
        self.move()
        if self.should_rebel():
            self.rebel()
    
    def get_arrested(self, sentence):
        self.in_jail = True
        self.model.schedule(self.release, after=sentence)
    
    def release(self):
        self.in_jail = False

This is the pattern from Epstein's civil violence model. Jailed citizens don't need to be activated every tick just to check if they're still in jail.

Level 4: Agents with event-driven behavior

Some agents don't need regular activation at all. Grass in Wolf-Sheep only needs to act when eaten:

class Grass(Agent):
    def __init__(self, model):
        super().__init__(model)
        self.alive = True
    
    def step(self):
        pass  # No regular action needed
    
    def eaten(self):
        self.alive = False
        self.model.schedule(self.regrow, after=self.model.regrow_time)
    
    def regrow(self):
        self.alive = True

Instead of activating thousands of grass patches every tick to decrement a counter, each patch just schedules its own regrowth. This can dramatically improve performance.

Level 5: Multiple time scales

Some models have processes that operate at different speeds:

class ClimateEconomyModel(Model):
    def __init__(self):
        super().__init__(recurring={
            "hourly_weather": 1/24,
            "daily_markets": 1.0,
            "monthly_policy": 30.0,
        })
    
    def hourly_weather(self):
        self.weather.update()
    
    def daily_markets(self):
        self.agents_by_type[Firm].shuffle_do("trade")
    
    def monthly_policy(self):
        self.government.review_policy()

model = ClimateEconomyModel()
model.run(duration=365)

Weather updates 24 times per day, markets once per day, policy once per month. All coexist naturally.

Level 6: Pure event-driven

For true discrete-event simulation with no regular stepping:

class QueueingModel(Model):
    def __init__(self, arrival_rate):
        super().__init__(recurring=None)  # No step()
        self.arrival_rate = arrival_rate
        
        # Bootstrap with first arrival
        self.schedule(self.customer_arrival, at=self.random.expovariate(arrival_rate))
    
    def customer_arrival(self):
        Customer(self)
        # Schedule next arrival
        next_time = self.time + self.random.expovariate(self.arrival_rate)
        self.schedule(self.customer_arrival, at=next_time)

model = QueueingModel(arrival_rate=2.0)
model.run(until=1000.0)

Time jumps directly from event to event. No wasted computation on empty ticks.

Configuration reference

# Default: step() called every 1.0 time units
super().__init__()

# Different method name
super().__init__(recurring="update")

# Different interval
super().__init__(recurring={"step": 0.5})

# Multiple methods at different rates
super().__init__(recurring={
    "fast": 0.1,
    "slow": 1.0,
})

# Pure event-driven, no recurring methods
super().__init__(recurring=None)

Migration

From current step-based models

No changes required:

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

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

From experimental Simulator API

# Before
simulator = ABMSimulator()
model = WolfSheep()
simulator.setup(model)
simulator.run_until(100)

# After
model = WolfSheep()
model.run(until=100)

# Before
simulator.schedule_event_absolute(callback, time=50)
simulator.schedule_event_relative(callback, time_delta=10)

# After
model.schedule(callback, at=50)
model.schedule(callback, after=10)

Open questions

1. Naming: Is recurring clear? Alternatives: tick, auto_schedule
2. Steps counter: Should we keep model.steps alongside model.time? It's redundant for pure event-driven models, but familiar for step-based models.
3. Run forever: Should model.run() with no arguments run until model.running = False? Or can it be defined additionally, together with something else?
4. Manual stepping: Should model.step() still work for manual for loops?

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

Feedback welcome

I would love to hear your thoughts:

• Does the progression from simple to advanced feel natural?
• Can we come up with a more elegant API for recurring methods (step, etc.)
• Are there use cases this doesn't cover?

[EwoutH]

• Can we come up with a more elegant API for recurring methods (step, etc.)

An alternative API could be using a decorator:

class MyModel(Model):
    ...

    @recurring
    def step(self):
        self.agents.shuffle_do("step")
    
    @recurring(interval=7)
    def weekly_update(self):
        self.collect_stats()
    
    def helper_method(self):  # Not recurring, no decorator
        pass

Existing models only have to add @recurring to their step method (and we could gracefully handle that with a warning at the back-end). That makes it super explicit which methods are done every n-time. It might also be more robust than letting users pass a dict. @recurring could be extended with more arguments as seen fit.

[quaquel]

Thanks for this. I have been thinking about cleaning up the event scheduling and integrating it better into MESA as well, but you have already done most of the work. Broadly speaking, I endorse the ideas outlined. At long last, it adds proper control for running models to MESA (i.e., run for x steps, run until a given time, etc.).

Just a few quick reactions.

1. I prefer separate methods over methods with many keyword arguments, which result in different behavior. We have had this conversation before, e.g., in the context of AgentSet. Therefore, I prefer to have separate methods for scheduling at a given timestep and for scheduling relative to the current timestep. Why? Autocomplete makes it easier to use and find. If you have many keyword arguments, you need to pull up the documentation to figure out which keywords to use. Also, implementation-wise, it often results in simpler code with fewer if-else or case match structures.
2. I am not sure about the recurring idea. I don't like the name itself, and I am also unsure what we are trying to achieve here. In principle, the current default use case is for the user to use a for loop. I think this pattern should still be possible in the future. At the same time, I like to be able to just do model.run_for(100), or model.run_until(100, condition=None). One idea might be to move the name of the step method into the run methods: model.run_for(100, method="step"), model.run_until(100, method="step", condition=None). This mimics the pattern already established with AgentSet, and is thus predictable behavior. To be clear, this is a preliminary sketch, not a fully developed idea.
3. steps has always been redundant in my view; I am in favour of deprecating this sooner rather than later.
4. I am not sure about dropping the distinction between ABMSimulator and DEVSSimulator.

At the moment, DEVSSimulator has the following methods

• run_until - so run until a given time
• run_next_event - only execute the next event, ideal for debugging
• run_for - run for a given amount of time
• schedule_event_now - schedule an event at the given time
• schedule_event_absolute - schedule an event at an absolute point in time
• schedule_event_relative - schedule an event relative to the current time
• cancel_event - remove an event
• reset - clean the event list and set the time back to start_time.
  The ABMSimulator adds to this
• schedule_event_next_tick - schedule an event for the next time step, so it builds on schedule_event_relative with a value of 1.

Next to the methods, there is also a check to ensure that valid time units are used. DEVS allows floats and integers; ABM only integers. Lastly, the ABMScheduler automagically schedules step. I am in favour of having a simple API for the user, but I do believe that the distinctions between these two schedulers are important and should be kept. One idea I had for stabilizing the schedulers was to turn them into a keyword argument to Model, which could default to ABMSimulator. However, if users want, they can use DEVSSimulator instead.

    def __init__(
        self,
        *args: Any,
        seed: float | None = None,
        rng: RNGLike | SeedLike | None = None,
        simulator:Simulator = ABMSimulator,
        **kwargs: Any,
    ) -> None:

This is compatible with the API sketched here, while giving users full control if they want to use full DEVS or just ABM style fixed time advancement.

[EwoutH]

Thanks for your quick and extensive reply!

I prefer separate methods over methods with many keyword arguments, which result in different behavior. We have had this conversation before

We have indeed. For me it's a question of guiding: the method says what I'm going to do (run), the keyword arguments how (at what time). This guides in multiple steps, and prevents the Model from getting large number of methods.

More importantly, model.schedule(drought, after=10) reads more like natural English. To address your concern about ambiguity, we can enforce keyword-only arguments using * in the signature.

You can also view the keyword arguments with a shortcut in most IDEs (Ctrl+Q in PyCharm).

I am not sure about the recurring idea.

I think we're actually trying to distinguish between two orthogonal concepts: Global Processes (intrinsic model properties like weather updates or data collection that run repeatedly) and Agent Events (autonomous actions that happen dynamically).

The recurring parameter (or better yet, a @scheduled decorator) handles the first category by abstracting away the self-scheduling boilerplate that users would otherwise have to write manually.

Without it, a user wanting a Poisson arrival process must remember to write self.schedule(self.arrival, after=random.expovariate(λ)) at the end of every arrival method, also common source of bugs. With @scheduled(every=lambda: random.expovariate(1/5)), the framework handles the renewal automatically.

I'm open to better naming, but I believe the concept is useful for bridging fixed time-step ABMs and true discrete-event simulation in one unified API.

@scheduled makes thing like Poisson-distributed agent-generators trivial.

[quaquel]

I am not convinced by your points regarding methods versus keywords. Autocomplete at the method/function level shows up before you dive into keywords and thus, at least for me, works better to find what I need. Moreover, model.schedule_at and model.schedule_after or something similar are very clear and also perfectly readable. I also fail to see the problem with having a larger number of methods in a class.

On the recurring point, you might be on to something. So yes, there is indeed a difference between what you call global processes and events.

1. model.step in my view is more like a global process rather than an event.
2. I have to think about the @scheduled decorator. From an API perspective, I like it. However, implementing it will be challenging. For example, you want all random draws to use the RNG of the model. So the outlined lambda expression won't work. So you need to do something where whatever is called is always called with the model as the argument: @schedule(every=lambda m: m.random.expovariate(1/5)).