Proposal: Unified Time and Event Scheduling API #2921

EwoutH · 2025-12-03T20:43:30Z

EwoutH
Dec 3, 2025
Maintainer

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

Naming: Is recurring clear? Alternatives: tick, auto_schedule
Steps counter: Should we keep model.steps alongside model.time? It's redundant for pure event-driven models, but familiar for step-based models.
Run forever: Should model.run() with no arguments run until model.running = False? Or can it be defined additionally, together with something else?
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 · 2025-12-03T20:50:18Z

EwoutH
Dec 3, 2025
Maintainer Author

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.

0 replies

quaquel · 2025-12-03T22:00:59Z

quaquel
Dec 3, 2025
Maintainer

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.

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.
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.
steps has always been redundant in my view; I am in favour of deprecating this sooner rather than later.
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.

1 reply

EwoutH Dec 4, 2025
Maintainer Author

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 · 2025-12-05T09:55:01Z

quaquel
Dec 5, 2025
Maintainer

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.

model.step in my view is more like a global process rather than an event.
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)).

0 replies

EwoutH · 2025-12-05T18:25:14Z

EwoutH
Dec 5, 2025
Maintainer Author

Doing some pathfinding in:

9 replies

quaquel Dec 6, 2025
Maintainer

I am not sure I follow your comment.

I would start with having a bunch of different methods for scheduling before worrying about decorators. In essence, decorators are syntactic sugar. So, having a clear method/function first often makes writing the decorator easier.
I am inclined to have separate approaches for events and generic processes. So, having decorators for events, while handing structural processes via a keyword argument on various run methods (e.g., run_for, run_until, run_while) seems fine to me.

EwoutH Dec 6, 2025
Maintainer Author

Basically this:

class MyModel(Model):
    def __init__(self):
        ...
        self.schedule_every(self.step, interval=7)

    ...  ### lots of other stuff

    def some_recurring_event(self):  # Can you remember how often this happens?
        self.agents.do("step")

class MyModel(Model):
    ...

    @scheduled(every=7)  # Frequency directly defined at the method
    def some_recurring_event(self):
        self.agents.do("step")

It's syntactic sugar indeed. But that might be a good approach.

Can you give an example of your second point?

quaquel Dec 8, 2025
Maintainer

My current rough idea is to have both scheduling and running methods on the model. From my perspective, however, these should not be conflated. Scheduling involves some kind of event list (schedule at a given point in time, schedule relative to the current time, schedule repeatedly), while running involves some kind of run control (so, do one step, run for a given amount of time, run until a given point in time, run until some condition is met).

There is potentially some overlap here. Scheduling repeatedly can be handled both via the eventlist or via the run control. For example, if you have model.step, this can be handled via scheduling it repeatedly or by passing this method to the run method. So we either do

model.schedule_repeated(model.step, time__between=1)

model.run_for(10, method=model.step)

Scheduling repeatedly is clearly the more powerful concept. However, it is also something that we currently don't have in the experimental Event Scheduling API. So. I am inclined to separate working out how to do this from integrating the existing scheduling into the model, and adding run control methods to the model.

So my proposal moving forward is

Just integrate and stabilize the existing scheduling API into the model class
Create a run control class and add this to the model. We need to develop an API for this and agree on the desired functionality.
Work out how to do scheduling things repeatedly (either with fixed or variable time between events).

EwoutH Dec 8, 2025
Maintainer Author

My current rough idea is to have both scheduling and running methods on the model.

Agreed.

There is potentially some overlap here. Scheduling repeatedly can be handled both via the eventlist or via the run control.

model.run_for(10, method=model.step)

If I understand this correctly, would find this extremely confusing and counterintuitive. I see how there might be some conceptual overlap, but let's keep everything that schedules events (now or (repeatedly) in the future) in schedule and everything that progresses time as run.

Scheduling repeatedly is clearly the more powerful concept. However, it is also something that we currently don't have in the experimental Event Scheduling API. So. I am inclined to separate working out how to do this from integrating the existing scheduling into the model, and adding run control methods to the model.

I think that would be worth trying.

Just integrate and stabilize the existing scheduling API into the model class

As PoC yes, but I would like to have it all in place before committing to an API. Easiest way is if we split off a 3.x branch and decide main goes towards 4.0.

Create a run control class and add this to the model. We need to develop an API for this and agree on the desired functionality.

Agreed, good step, especially the second part. We an do that right in this discussion, right?

Work out how to do scheduling things repeatedly (either with fixed or variable time between events).

Also agreed. I would like doing one more attempt shooting directly to PoC with it included, but without the syntactic sugar (like @scheduled).

I think we can do three things in parallel:

Discuss API and class structure
Work out scheduler and run control classes
PoC integrated API (with backwards comp)

I don't have much time this week to develop, but I can discuss API or review. Hopefully next week some more dev time.

quaquel Dec 8, 2025
Maintainer

Agreed, good step, especially the second part. We an do that right in this discussion, right?

Probably yes, but it also seems we have figured out that the scheduling API and the run control API are separate concerns.

Conceptually, for scheduling, we have

scheduling relative to current time; currently called schedule_relative
scheduling at an absolute point in time; currently called schedule_absolute
scheduling repeatedly with a (random) time interval between them; tentatively called schedule_repeatedly

A key question is whether we want to make the event list a core part of Model. If so, the run control would manage the advancement of time as dictated by the event list.

Conceptually, for running, we have

run for a given amount of time; tentatively called run_for
run up to a given point in time; tentatively called run_until
run the next event; tentatively called run_next_event. In classic event scheduling tools, this is confusingly often called step, or stepping through the model.

The run control API also needs to consider, at least in its design, support for time units (e.g., datetime, calendars, meaning of a single step in case of fixed time advancement).

EwoutH · 2026-01-17T09:46:03Z

EwoutH
Jan 17, 2026
Maintainer Author

With #3155 providing the basics, this new architecture allows us to really flexibly schedule events.

We already have the schedule_at()and schedule_after() methods and the @scheduled decorator, but those are actually specialized solutions for common scheduling patterns in ABM.

Underlying, there should be a really powerful schedule() method that can both be used internally and by users.

I propose the following API for schedule():

Core 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 = no limit, defaults to 1 for one-off)
    end_at=None,        # Absolute time to stop
    end_after=None,     # Duration to run (from first execution)
    end_when=None,      # Condition to stop when true
    priority=Priority.DEFAULT,
    args=None,
    kwargs=None,
) -> SimulationEvent

Constraints:

Only one of: start_at, start_after, start_when
Only one of: end_at, end_after, end_when (count can combine with one of these; whichever comes first)
interval implies recurring (count defaults to None = infinite)
No interval means one-off (count defaults to 1)
only_if is checked every occurrence; if False, skips execution but continues scheduling

Convenience Functions

model.schedule_at(callback, time, priority=DEFAULT, args=None, kwargs=None)
# Equivalent to: model.schedule(callback, start_at=time)

model.schedule_after(callback, delay, priority=DEFAULT, args=None, kwargs=None)  
# Equivalent to: model.schedule(callback, start_after=delay)

model.cancel_event(event)

Decorator

@scheduled  # interval=1, count=None (infinite)
@scheduled(interval=7)
@scheduled(interval=7, start_at=10, count=5)
@scheduled(interval=1, end_when=lambda m: not m.running)
@scheduled(interval=1, only_if=lambda m: m.market_open)

Examples

One-off Events

# Immediate
model.schedule(self.initialize_agents)

# Scheduled disaster
model.schedule(self.earthquake, start_at=50)

# Delayed policy change
model.schedule(self.introduce_carbon_tax, start_after=100)

Simple Recurring

# Daily step
@scheduled
def step(self):
    self.agents.do("step")

# Weekly reports
@scheduled(interval=7)
def weekly_report(self):
    self.collect_statistics()

# Quarterly earnings (4 times)
model.schedule(self.publish_earnings, interval=90, start_at=90, count=4)

Conditional Execution (Pausing)

# Work week (Mon-Fri, 9am-5pm in simulation time)
@scheduled(
    interval=1,
    only_if=lambda m: m.time % 168 < 120 and 9 <= m.time % 24 < 17
)
def market_trading(self):
    self.process_trades()

# Seasonal breeding (spring/summer only)
@scheduled(
    interval=1,
    only_if=lambda m: 90 <= m.time % 365 < 270
)
def breeding_season(self):
    self.agents.select(lambda a: a.can_breed).do("reproduce")

# Crisis response (only during crisis)
@scheduled(interval=1, only_if=lambda m: m.in_crisis)
def crisis_response(self):
    self.handle_crisis()

Time-Bounded Recurring

# Limited intervention
model.schedule(self.stimulus_payment, interval=30, count=3)  # 3 payments

# Campaign that runs for 90 days
model.schedule(
    self.run_campaign,
    interval=1,
    start_at=100,
    end_after=90
)

Variable & Stochastic Intervals

# Activity rate changes over time
model.schedule(
    self.dynamic_event,
    interval=lambda m: m.current_activity_rate
)

# Poisson arrivals (customers, infections, etc.)
model.schedule(
    self.customer_arrival,
    interval=lambda m: m.random.expovariate(2.0),  # rate = 2.0/time unit
    end_at=1000
)

# Grass regrowth with variation
model.schedule(
    self.grass_regrow,
    interval=lambda m: m.random.uniform(20, 40),
    start_after=self.eaten_at
)

Combining only_if with other constraints

# Trading system: only during market hours, for first 100 days
@scheduled(
    interval=1,
    only_if=lambda m: 9 <= m.time % 24 < 17 and m.time % 7 < 5,
    end_at=100
)
def trading_step(self):
    self.process_orders()

# Seasonal migration: only in fall, for 10 years
model.schedule(
    self.migration_event,
    interval=7,
    only_if=lambda m: 270 <= m.time % 365 < 330,  # Fall months
    count=520  # ~10 years of weekly migrations
)

Agent Self-Scheduling

class Prisoner(Agent):
    def get_arrested(self, sentence):
        self.in_jail = True
        self.model.schedule(self.release, start_after=sentence)
    
    def release(self):
        self.in_jail = False

class GrassPatch(Agent):
    def get_eaten(self):
        self.fully_grown = False
        self.model.schedule(
            self.regrow,
            start_after=self.regrowth_time
        )
    
    def regrow(self):
        self.fully_grown = True

Event Chaining (User Pattern)

# Poisson process implemented by user
class QueueModel(Model):
    def __init__(self):
        super().__init__()
        self._schedule_next_arrival()
    
    def _schedule_next_arrival(self):
        delay = self.random.expovariate(self.arrival_rate)
        self.schedule(self.customer_arrival, start_after=delay)
    
    def customer_arrival(self):
        Customer(self)
        self._schedule_next_arrival()  # Chain to next

Time Control

model.run_for(100)                           # Run for 100 time units
model.run_until(500)                         # Run until time 500
model.run_while(lambda m: m.running)         # Run while condition true
model.run_next_event()                       # Execute next event (debugging)

Comparison: only_if vs end_when

# end_when: Stops scheduling permanently when condition becomes true
@scheduled(interval=1, end_when=lambda m: m.crisis_resolved)
def monitor(self):
    self.check_status()
# Once crisis_resolved=True, monitoring stops forever

# only_if: Pauses/resumes based on condition
@scheduled(interval=1, only_if=lambda m: m.in_crisis)
def crisis_handler(self):
    self.handle_crisis()
# Skips when in_crisis=False, resumes when in_crisis=True

Migration from Mesa 3.x

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

# New (Mesa 3.5+)
@scheduled
def step(self):
    self.agents.do("step")

model.run_for(100)

9 replies

EwoutH Jan 19, 2026
Maintainer Author

But you cannot specify a variable interval at the moment, as far as I can see.
In #3155 not yet. But with this proposal you will.

model.schedule(
    self.customer_arrival,
    interval=lambda m: m.random.expovariate(2.0),  # rate = 2.0/time unit
    count=1000
)

But then it might be better to flip the logic. In your model, you can be much more efficient in figuring out whether to start scheduling something. Moreover, scheduling and then not executing is not free.

This is an interesting situation. If you need to determine if you do something at the moment, you need to schedule an event at that moment to check anyways. And it that case I don't think it matters that much where you do that check exactly.

You can't check beforehand, because you don't know the future model state yet. So you need an precise event to check.

Of course, if you do know the state beforehand (like if it's time bound) there are much more efficient ways. So this isn't a good example, because you know what time it is at a certain time:

# model.py
@scheduled(
    interval=1,
    only_if=lambda m: 90 <= m.time % 365 < 270  # Seasonal breeding (spring/summer only)
)
def breeding_season(self):
    self.agents.select(lambda a: a.can_breed).do("reproduce")

Some agent state you can't know in advance, so you need an event to check.

@scheduled(interval=1, only_if=lambda a: a.energy >50)
def breed(self):
    self.reproduce()

But I see your point, maybe the condition can better be checked in the function you scheduled itself.

@scheduled(interval=1)
def breed(self):
    if self.energy > 50:
        self.reproduce()

EwoutH Jan 20, 2026
Maintainer Author

I removed the start_when and only_if from the schedule() API proposal.

One thing we have to think about: Do we recommend users to save their event object somewhere? Especially if it's a recurring event object?

# Save reference when you need pause/resume/stop
self.trading_event = model.schedule(
    self.process_trades,
    interval=1)

# Do other stuff
...
# Close market
self.trading_event.pause()
...

# Reopen market
self.trading_event.resume()
...

# End trading
self.trading_event.stop()

quaquel Jan 20, 2026
Maintainer

events are typically lightweight and easy to create on the fly so I see little reason to save them. Also the pause, resume, stop kind of syntax I would not necissarly add to the event. Those are more process modelling style concepts (which is its own paradigm for discrete event).

EwoutH Jan 20, 2026
Maintainer Author

Thanks of all the input. Based on it, I continued development, leading to #3188

EwoutH Jan 21, 2026
Maintainer Author

Also the pause, resume, stop kind of syntax I would not necissarly add to the event.

I think this is fixed (among other things) in my proposal below.

ShreyasN707 · 2026-01-17T10:10:18Z

ShreyasN707
Jan 17, 2026

This proposal helped something click for me: scheduling and run control really are separate concerns, but recurring behavior sits right at the boundary between them.

What feels most powerful here isn’t so much run_for vs run_until, but the idea of having one expressive scheduling primitive that can naturally represent one-off events, fixed or variable recurrence, conditional execution (only_if), and bounded lifetimes (count, end_at).

From that angle, step() stops being a special case and just becomes a recurring scheduled event with interval=1, which honestly feels like the right mental model.
I also really like the only_if vs end_when distinction — pausing vs permanently stopping is a subtle difference, but it matters a lot in real models.

The only thing I’d be cautious about is API surface vs learnability. A single powerful schedule() with a small number of explicit convenience wrappers like schedule_at and schedule_after feels like a good balance before adding decorators or more syntactic sugar.

Overall, this direction feels like it genuinely unifies ABM and DEVS semantics, rather than just layering one on top of the other.

0 replies

EwoutH · 2026-01-21T18:29:42Z

EwoutH
Jan 21, 2026
Maintainer Author

We learn as we go.

When scheduling things in a simulation, there are really two different concepts:

Event: A single thing that happens at a specific time. “A disaster strikes at t=50.” Fire once, done.
Pattern: A rule for when things should happen repeatedly. “Collect data every 7 time units.” Ongoing, can be paused/resumed/stopped.

These deserve different names and different return types. An event is ephemeral. A pattern is persistent.

# One-off events
event = model.event(callback, at=50)
event = model.event(callback, after=10)
event.cancel()

# Recurring patterns
pattern = model.pattern(callback, interval=1)
pattern = model.pattern(callback, interval=lambda m: m.random.expovariate(2.0))
pattern.pause()
pattern.resume()
pattern.stop()

The method names signal what you’re creating. The return types give you appropriate controls.

Why not a single `schedule()` method?

We considered a unified method with many parameters. But “schedule an event” and “schedule a pattern” are conceptually different operations. Separate methods make the intent clear and keep signatures simple. The return type is always obvious from which method you called.

Pattern stuff

Patterns support callable intervals for stochastic processes:

# Poisson arrivals
model.pattern(self.customer_arrival, interval=lambda m: m.random.expovariate(2.0))

Patterns can be bounded three ways (mutually exclusive):

model.pattern(callback, interval=1, count=10)      # Run exactly 10 times
model.pattern(callback, interval=1, end_at=100)    # Stop at t=100
model.pattern(callback, interval=1, end_after=50)  # Run for 50 time units from first execution

Of course, you can omit the end condition, or just tack it on later. (end_in, end_at, etc.)

The step as heartbeat

So we still want to be a bit classic ABM right? We could consider making the step a “hearthbest”:

Every Mesa model has a step() method. Rather than special-casing it, we simply auto-schedule it as a pattern:

class Model:
    def __init__(self):
        # ...
        self.step_pattern = self.pattern(self.step, interval=1)

This means step() is just another scheduled callback. Users can access self.step_pattern to pause, resume, or inspect it. The familiar step() method remains - it’s just scheduled automatically now.

(or not, and we ask users to add this single line of code)

Running the Model

Nothing changes, I think this was quite clear from the beginning.

model.run_for(100)                        # Run for 100 time units
model.run_until(500)                      # Run until t=500  
model.run_while(lambda m: m.running)      # Run while condition true
model.run_next_event()                    # Single event (debugging)

These replace the old for _ in range(100): model.step() pattern. Time advances to each event, events execute, patterns reschedule themselves.

Do we need Scheduler and RunControl objects?

We initially had a Scheduler class that held the EventList and provided scheduling methods. But looking closer, it might not be needed. Event and Pattern need access to the model anyway (for model.time). The EventList can live directly on Model. The scheduling methods become model.event() and model.pattern().

Same for RunControl - those are simple methods that can live directly on Model.

Fewer objects, simpler mental model: “Model has events” rather than “Model has Scheduler which has events.”

Pattern vs RecurringEvent

We originally had RecurringEvent - a special event that clones itself after execution. Problem: the user’s reference becomes stale after the first execution. The “live” event is a different object.

Pattern is a persistent object that generates regular SimulationEvents internally. The user holds a stable reference throughout. pause(), resume(), stop() always work on the right thing.

Agent access

Agents get the same API through properties:

class Agent:
    def event(self, callback, **kwargs) -> Event:
        return self.model.event(callback, **kwargs)
    
    def pattern(self, callback, **kwargs) -> Pattern:
        return self.model.pattern(callback, **kwargs)

So agents can write:

class Prisoner(Agent):
    def get_arrested(self, sentence):
        self.in_jail = True
        self.event(self.release, after=sentence)

Backwards compatibility

Direct model.step() calls will show a deprecation warning and internally call run_for(1). Old code keeps working but users are guided toward the new API.

Other stuff

model.running = False could be a way to stop executing events
We could do model.event_at() and model.event_after() instead of model.event(at=...). I think the latter is clearer that it creates an event. .event() then is of course now. But whatever.
The @scheduled decorator or whatever we could rename it to, is probably not needed. At least not initially.

Summary

Concept	API	Returns
One-off	`model.event(callback, at=..., after=...)`	`Event`
Recurring	`model.pattern(callback, interval=...)`	`Pattern`
Run	`model.run_for()`, `model.run_until()`, `model.run_while()`	-
Step	Auto-scheduled, stored in `model.step_pattern`	`Pattern`

The whole system is: EventList on Model, Event and Pattern classes that register themselves, run methods that pop and execute.

A no fuss API.

6 replies

quaquel Jan 21, 2026
Maintainer

Do we need Scheduler and RunControl objects?

The risk of just putting everything into the model is that this becomes an unmanagable blob of functionality. So I prefer encapsulating different functionality into their own objects and then compose the Model out of those objects. Just to push your reasoning to the extremee: why would we need a stand alone object or several objects for data registration and data collection? They also need access to time.

We originally had RecurringEvent - a special event that clones itself after execution. Problem: the user’s reference becomes stale after the first execution. The “live” event is a different object.

Pattern is a persistent object that generates regular SimulationEvents internally. The user holds a stable reference throughout. pause(), resume(), stop() always work on the right thing.

This is a good improvement, although I am still not sure about the name.

Also, I don't like model.pattern and model.event. These are method calls and so should have a verb in then. Better would be model.schedule_pattern and model.schedule_event. We might use @pattern and @event as syntactic suggar that internally rely on these two methods.

Every Mesa model has a step() method. Rather than special-casing it, we simply auto-schedule it as a pattern:

See my previous remark. I still think I prefer an annotation of model.step over making a big assumption over the name of the step method.

Do we need something else/better than the current priority? Also considering with the ordering paradigms of Agent activation?

I would not mess with priority. Its a classic devs way of handling events at the same instant. I see no reason to mess with that. If you want to schedule the activation of multiple agents, you can instead schedule a callable that takes an agentset and then handle the randomization inside the callable.

EwoutH Jan 21, 2026
Maintainer Author

The risk of just putting everything into the model is that this becomes an unmanagable blob of functionality. So I prefer encapsulating different functionality into their own objects and then compose the Model out of those objects. Just to push your reasoning to the extremee: why would we need a stand alone object or several objects for data registration and data collection? They also need access to time.

Fair point. But in this case the functionality and complexity is in EventList, Event and Pattern (or however we're going to call them). So does that need another wrapper layer (Schedule/RunControl) around it?

EwoutH Jan 21, 2026
Maintainer Author

Also, I don't like model.pattern and model.event. These are method calls and so should have a verb in then.

Do note though that the brackets on the end already signal it's a function/method: pattern() and event().

But I don't disagree. Just not sure about which verb. Maybe just keep it simple and call it create_event() and create_pattern().

Every Mesa model has a step() method.

We could keep this for 3.x, since that's the current pattern. Then we could consider deprecating it for 4.0.

We could have a longer discussion then about if Mesa benefits from a (fixed-interval) "heart beat" concept.

I would not mess with priority.

Agree. It was a honest question since we're now going to lean more on it.

Are we good on the big picture stuff? (mainly the Pattern approach instead of RecurringEvent)

codebreaker32 Jan 22, 2026
Collaborator

Hey @EwoutH,

Thanks for laying this out so clearly. I think the overall direction is solid, and I'm on board with the Pattern approach over RecurringEvent - the stable reference issue you identified is a real problem that this solves elegantly.

Do we need something else/better than the current priority? Also considering with the ordering paradigms of Agent activation?

I agree with @quaquel - let's not mess with priority right now. The current priority system (HIGH/DEFAULT/LOW) works well. For agent activation ordering, keeping that logic in a separate callable (e.g., an agentset method) makes more sense than trying to merge these two concerns. They serve different purposes.

Also, I don't like model.pattern and model.event. These are method calls and so should have a verb in then. Better would be model.schedule_pattern and model.schedule_event

I see both sides here. I think @quaquel has a point about clarity However, create_event() and create_pattern() might be more intuitive than schedule_* since they return objects you can manipulate (cancel, pause, etc.). The word "schedule" implies fire-and-forget to me.

Maybe:

model.create_event(callback, at=...) → returns Event
model.create_pattern(callback, interval=...) → returns Pattern

Do we need Scheduler and RunControl objects?

I lean toward keeping some separation here. While EventList, Event, and Pattern handle the core complexity, having Scheduler and RunControl as thin wrappers provides clear separation of concerns and makes testing or debugging easier. For future contributors, it will be easy for them to understand the entire flow instead of just looking at bloated model.py
For eg.

Class	Responsibility
EventList	Stores and orders events (data structure)
Event (Pattern)	Represents an individual event
Scheduler	Decides when things should happen (scheduling)
RunControl	Controls how time advances (execution logic)
Model	Defines what the simulation is about (domain)

Summarising, I'm good with the Pattern approach. The conceptual distinction between one-off events and recurring patterns is clear and the API reflects that well. The return types giving appropriate controls (.cancel() vs .pause()/.resume()/.stop()) is exactly right.

One question: For patterns with callable intervals (the Poisson example), does the lambda get evaluated before or after the callback executes? Might be worth documenting that explicitly.

EwoutH Jan 24, 2026
Maintainer Author

I'm going to slice it into smaller steps instead of one-shotting it. Mainly because there are A) still some design decisions that need to be made and B) keeping (some level of) backwards compatibility makes implementation it more complex.

First step in #3201.

EwoutH · 2026-01-24T15:26:06Z

EwoutH
Jan 24, 2026
Maintainer Author

Does Mesa need a "heartbeat"?

With the new Event/Pattern architecture, step() becomes just another scheduled pattern rather than a special construct. This also removes the certainty of a step being performed at all. This raises a question: do we still need a guaranteed regular "heartbeat" in Mesa?

Use cases that might benefit from a heartbeat:

Data collection: Collect metrics at regular intervals regardless of event timing
Visualization: Update displays at consistent frame rates, not every micro-event
Garbage collection: Periodic cleanup of removed agents, stale references, etc.
Checkpointing: Save model state at regular intervals for recovery/analysis
Progress reporting: Log or display simulation progress predictably

In pure discrete-event simulation, time jumps directly between events: there's no concept of "ticks." But many practical concerns (UI updates, data sampling, resource management) may benefit from predictable periodic execution.

The main questions:

Do any Mesa components need such a heartbeat, and if so which?
If needed, do we want to keep it internal or expose it?
Are there specific interactions between Mesa components that could benefit from a heartbeat (i.e. data recording happening always just before visualisation rending)?

Everyone's opinion welcome, but especially @quaquel and @Sahil-Chhoker.

7 replies

quaquel Jan 26, 2026
Maintainer

I guess what I was trying to say is that if time is reactive, any listener can distill their own frequency for action from this. So, there is no need at all to provide an additional "heartbeat".

For example, a reactive collector could simply collect data on every full integer (i.e., 1, 2, 3, etc.). It listens for TimeAdvanced signals. When it receives the signal, it can just check the new value in it and see if action is needed. If the new time goes over the full integer increment, it collects. Otherwise, it does nothing. This approach works whether you have a pure devs model or a classic ABM model. A UI likewise can do the same. Again, indicate the frequency at which the UI should update as time advances, and you are done.

EwoutH Feb 8, 2026
Maintainer Author

Any updated insights on this?

I'm thinking, it might be useful to have a default scheduled method. By default that could be step, with a frequency of 1. By having a default scheduled method, we always have a default to trigger visualisation updates, data collection, condition updates, and other relevant events.

The default_schedule could easily be overwritten by any EventGenerator.

quaquel Feb 8, 2026
Maintainer

For new style data_collection, there is no need to provide a default step method. Instead, it observes model.time and reacts to changes in this. For the visualization we can in principle do the same, so again no need to provide a default scheduled method. The advantage also is that both data collection and visualization will work out of the box for pure devs models.

EwoutH Feb 8, 2026
Maintainer Author

I did some internal refactoring, and I think it turned out really nice:

Refactor step scheduling to use EventGenerator internally #3260

It exposes the "magic" of scheduling the step by default, so users can easily change or disable it.

jackiekazil Feb 19, 2026
Maintainer

In response to this: #3260 (comment)

And this (above): #2921 (reply in thread)

I'm thinking, it might be useful to have a default scheduled method. By default that could be step, with a frequency of 1. By having a default scheduled method, we always have a default to trigger visualisation updates, data collection, condition updates, and other relevant events.

The default_schedule could easily be overwritten by any EventGenerator.

I agree with the defaul that Ewout is proposing. There are a lot of new users to abms and to Mesa and some to programming if you add understanding how to setup the right construct of time in Mesa -- that is a lot to process cognitively and a pathway to frustration. Also, conceptually the idea of "step" is so intertwined with literature that new individual read it is an easily recognized pattern.

EwoutH · 2026-01-26T07:46:14Z

EwoutH
Jan 26, 2026
Maintainer Author

Now that we can generate recurring events (#3201) and refactored the internals (#3204), we're in a good state to build a public API on this.

First, to recap:

What's Been Implemented

Unified Event List (Unify event list between Model and Simulator #3204)

Model now owns _event_list directly

Simulators access it via a property rather than owning their own

model.step() internally uses _advance_time() which processes events

Both model.step() and simulator.run_until()/run_for() use the same event list

EventGenerator (Add EventGenerator class for recurring event patterns #3201)

New class for recurring event patterns (separate from one-off SimulationEvent)

Supports fixed or callable intervals (enabling stochastic processes like Poisson arrivals)

Has start(at=..., after=...) and stop(at=..., after=..., count=...) methods

Returns self for method chaining

Tracks execution_count and is_active state

Existing Simulator Classes

DEVSimulator: Pure discrete-event (float time)

ABMSimulator: Fixed time-step + events (integer time), auto-schedules model.step

There are still quite a few open questions / design decisions that need to be made. Here are the ones I think are now most important.

Architectural

Do we still need separate Simulator classes? EventList, SimulationEvent and EventGenerator contain a lot of the complexity already (EventGenerator internalizing a lot of the old ABMSimulator functionality), so the main questions is, how much is left, and is there's value in splitting that off?
- I do want to note that an internal refactor is always possible.
The recurring parameter debate: How should users specify what methods run automatically? Options discussed:
- super().__init__(recurring="step") or recurring={"step": 1, "weekly": 7}
- @scheduled decorator
- Explicit self.schedule_every(self.step, interval=1) in __init__

My personal proposal is to expose the current stuff though a simple, low-hanging API, with exactly 4 methods:

Add convenience methods to Model for scheduling without needing a Simulator:

# Two scheduling functions
def schedule_event(callback, *, at=None, after=None):
    """Create and schedule a one-off event."""
    # Delegates to internal _event_list

def schedule_every(callback, interval, *, start_at=None, ...):
    """Create and start recurring event generator."""

# Two run functions
def run_for(self, duration):
    """Run the model for the specified duration."""
    self._advance_time(self.time + duration)

def run_until(self, end_time):
    """Run the model until the specified time."""
    self._advance_time(end_time)

With the scheduling function, a Event or EventGenerator is returned, which can respectively be cancelled and stopped, restarted or modified otherwi

From there we can start updating models, and see what's missing. I think that will help ground our discussions in:

How conditionals are handled
If we need a hearth beat (and is so how to configure it)
Which other functionality might be missing
Which syntactic suger needs/could be handled

0 replies

quaquel · 2026-01-26T08:33:50Z

quaquel
Jan 26, 2026
Maintainer

Do we still need separate Simulator classes?

Conceptually, you have an event list containing the ordered list of events, a blob of objects that schedule events (also known as the model), and something that controls the time advancement of the event list (a simulator or run control). So, yes, I would favor a separate run-control/simulator object. How to expose the functionality to the user is a separate question. Because of the separation of concerns, it makes sense to cleanly separate these three fundamentally different things into their own separate classes, which can be tested and developed in isolation.

The recurring parameter debate

A decorator is, in my view, just syntactic sugar on top of an existing method/function-based API. So, although I like a @scheduled decorator, it would be built on something like event_list.schedule_every.

My personal proposal is to expose the current stuff through a simple, low-hanging API, with exactly 4 methods:

I agree with the methods, but note that scheduling is event-list interaction, while running is run-control interaction. They are conceptually really different things, and I would be careful not to conflate them.

0 replies

EwoutH · 2026-01-27T07:35:43Z

EwoutH
Jan 27, 2026
Maintainer Author

Conditional running and stopping

Following up on the proposal for run_for() and run_until() methods, we need to address how models handle conditional stopping.

Core Use Cases

Time-based stopping is covered by the proposed run_for(100) and run_until(1000) methods. But models often need to stop based on conditions: equilibrium reached, target state achieved (50% infected), resources exhausted, or emergent behavior detected. Real models frequently combine these: "run for 1000 steps OR until equilibrium" or "run until infection spreads OR max 500 steps."

The model itself may also need to stop from within step logic. For example, detecting that an outbreak is contained mid-simulation and stopping execution.

What to do with `model.running`

Currently, Mesa has model.running as a boolean flag. The legacy run_model() uses while self.running: self.step(), making it a global stop flag. With new time advancement methods, the semantics become unclear.

Should run_for(100) respect running=False or run anyway? If the model sets running=False internally during a run_for() call, should that stop execution early? Does running persist across calls, requiring manual reset? When exactly is running checked—between integer timesteps, after every event, or only when users explicitly check it?

Different stopping patterns

There are distinct patterns with different requirements.

External conditions where the user wants to run until something happens ("run until 50% infected, but no more than 1000 steps").
Internal conditions where the model stops itself (detecting equilibrium in step() and setting a flag).
Time-based execution with an escape hatch ("run for 1000 steps, but model can stop itself if needed").

Each pattern raises questions about who checks conditions, when they're checked, and how different stopping mechanisms interact.

Additionally, there may be different stopping semantics needed. Agent-based models with daily cycles might want to finish the current day before stopping for data integrity. Discrete event simulations might need immediate halt when critical events occur. Whether this distinction is necessary or adds unnecessary complexity is unclear.

Open Questions

What should model.running semantically mean? Is it a request to stop that run methods respect, a status flag users check themselves, or something else entirely? Or do we replace it with something else?
How should conditional stops be expressed? Through callbacks like run_until(lambda m: m.equilibrium_reached()), a separate method like run_while(condition), reusable condition objects like run_until(Equilibrium()), or purely model-internal using the running flag?
How expensive are conditions to check? Checking every time unit (or even event) might be costly for complex conditions like computing network statistics or detecting equilibrium. Do we need a check_interval parameter, or is this premature optimization?
Should running persist across calls? If model.run_for(100) stops itself at t=50, should a subsequent model.run_for(100) run or is running still False?
We have a model.init() for setting up stuff in Mesa, do we need some stop/exit method that users can fill with stuff that needs to happen on stopping a run?

@quaquel I was thinking if we can do something with signals here. Would it make sense to make model.running an observable, and let all kinds of methods listen to it? It might be way easier if it just emits a signal when it changes (push) instead of all methods needing to check in continuously (pull). Or do we still always need to poll/check somewhere and isn't it that much of an advantage?

Minimal requirements

At minimum, we need to decide whether run_for()/run_until() check model.running, and if so, when. Should we add a stop() method as the canonical way to set running=False or do something else to stop event execution / time advancement? How do we document the semantics clearly?

These questions affect the API design and user mental model. Getting this right will determine whether the time advancement API is intuitive or confusing.

38 replies

EwoutH Feb 7, 2026
Maintainer Author

I think that’s a fair point. A request_stop method could just fire an event to set an (internal) flag false, and that event can be scheduled (now with highest priority, now with lowest priority, at the first integer timestep, etc.)

EwoutH Feb 8, 2026
Maintainer Author

I’m thinking in the direction of:

A Condition object (can be set, returns a boolean)
a add_condition() method that takes a Condition and a Schedule and schedules a recurring event to check the condition
stop() and resume() methods that update the running state (and possibly do other stuff)
Keeping running as bool

quaquel Feb 8, 2026
Maintainer

I like the cleanliness of the first two bullets. I still fail to see the point of keeping running with the other stuff added in. (Clearly under mesa 3, we have to keep it for semver).

EwoutH Feb 8, 2026
Maintainer Author

For performance you need a boolean to performantly check if the next event should be executed. It could also be internal.

Usage example:

model = MyModel()
condition = Condition(some_function)
model.add_condition(condition, Schedule())
model.run_for(100)

quaquel Feb 8, 2026
Maintainer

For performance you need a boolean to performantly check if the next event should be executed

I don't understand what this has to do with the usage example. You are already specifying a Condition with some_function. So, you are running some_function anyway according to Schedule. Whether or not some_function is just checking an internal flag that is set or is doing something else (e.g., checking the behavior of the last n time steps) is in my view up to the user. We don't need to reserve an attribute on Model for this.

On the usage example itself, I find the name model.add_condition not particularly clear. At least something like add_stop_condition would already be clearer. But I still prefer something like run_while(Condition(some_func), Schedule()).

EwoutH · 2026-02-06T15:35:56Z

EwoutH
Feb 6, 2026
Maintainer Author

Two updates:

After some discussion in Add DataRecorder for reactive Data Storage and DatasetConfig for Configuration #3145 (comment), I opened a PR with a new Schedule dataclass. It cleans stuff up nicely Add Schedule dataclass and refactor EventGenerator #3250
In EwoutH@440fdbe I look ahead how a public user API could look for schedule and run methods.

6 replies

quaquel Feb 9, 2026
Maintainer

Sounds good to me. A tricky part of this will be figuring out how to let this interact with SolaraViz.

On your open discussion questions you broadly know my take but to summarize them here

With model.time being observable, and as you so clearly put it in Add public event scheduling and time advancement methods #3266, "we need public methods that let users think in terms of time rather than steps". So, there is no need for a separate heartbeat concept. Everything can just listen to time and distill its own relevant frequency for action from this.
I don't favor a _default_schedule attribute, but I do think we need an easy way of specifying what the step method is for the classic ABM use case. I think a decorator is a nice way of exposing the underlying API.
the conditional stuff we might better discuss in person. I think we don't differ that much on this as might appear from the discussions here.
I still think we might need a run setup class that specifies the start time and end time of a model. More sophisticated use cases of this might use proper data time and calendars for this.
We still need a signal that a run has completed to ensure data collection on run completion (see Add DataRecorder for reactive Data Storage and DatasetConfig for Configuration #3145).

EwoutH Feb 9, 2026
Maintainer Author

We still need a signal that a run has completed to ensure data collection on run completion

Now we're on the signals train, could we fire an RUN_STARTED and RUN_ENDED event?

EwoutH Feb 9, 2026
Maintainer Author

I do agree. Was playing devils advocate for a bit. We might pit a few classic ABM people against us. But I always was a be free to do whatever you want-person.
continues from 1. Easy adding it back and easy deprecation is important here. @scheduled (or @recurring) decorator would be nice.
Agree. Also not a priority in my view. First clean-up the old stuff, then add it to Mesa 4.
Would that change public exposed methods? Like having to do model.run.schedule_event()? Or would it be merely an internal construct?

quaquel Feb 9, 2026
Maintainer

Now we're on the signals train, could we fire an RUN_STARTED and RUN_ENDED event?

I guess you mean signal, but yes. RUN_STARTED would be potentially redundant because it can be derived from the first update to model.time. But in a pure devs context it might be helpful to gather the data at t=0. RUN_ENDED is critical to ensure the final tilmestep can be collected.

Would that change public exposed methods? Like having to do model.run.schedule_event()? Or would it be merely an internal construct?

I don't think it would change any of the public methods, but it would potentially be an additional dataclass that is passed to model.__init__. In its simplest form we might do something like what's shown below. The key thing is that if we want to fire a RUN_ENDED signal, we need to know when the run is ended. With a stopping conditions, this will be clear, but if the stopping condition is only time based it might be useful to do it via a RunSetup thing. The other option is always have a condition that is time based and that defaults to infinity. Most simulation packages that I have worked with use a RunSetup style approach rather than collapsing it into the stopping condition (if the even support that which many don't).

@dataclass
class RunSetup:
    starttime: float|int = 0.0
    endtime: float|int = np.nan # run to infinity

EwoutH Feb 11, 2026
Maintainer Author

Quick update: the initial unified time and event scheduling API is now stabilized!

This includes:

Event scheduling moved from experimental to stable mesa.time module
- Stabilize event scheduling system from experimental to mesa.time #3276
All examples and tutorials migrated to model.run_for()
- Migrate tutorials and examples to model.run_for() #3270
- Update wolf-sheep example to use new event scheduling API #3278
Old Simulator classes deprecated
- Deprecate Simulator classes, add migration guide entry #3277

Two open questions remain (see tracking issue #3132): whether to expose _default_schedule publicly, and conditional running/stopping API design. And then maybe adding some syntactic sugar (like a @recurring decorator).

Uh oh!

Proposal: Unified Time and Event Scheduling API #2921

Uh oh!

Uh oh!

EwoutH Dec 3, 2025 Maintainer

Summary

Motivation

The problem with two objects

The simplest API imaginable

Proposed API

Running models

Scheduling events

Model initialization

Usage progression

Level 1: Just define step()

Level 2: Add scheduled events

Level 3: Agents scheduling events

Level 4: Agents with event-driven behavior

Level 5: Multiple time scales

Level 6: Pure event-driven

Configuration reference

Migration

From current step-based models

From experimental Simulator API

Open questions

Feedback welcome

Replies: 12 comments · 76 replies

Uh oh!

EwoutH Dec 3, 2025 Maintainer Author

Uh oh!

quaquel Dec 3, 2025 Maintainer

Uh oh!

EwoutH Dec 4, 2025 Maintainer Author

Uh oh!

Uh oh!

quaquel Dec 5, 2025 Maintainer

Uh oh!

Uh oh!

EwoutH Dec 5, 2025 Maintainer Author

Uh oh!

quaquel Dec 6, 2025 Maintainer

Uh oh!

EwoutH Dec 6, 2025 Maintainer Author

Uh oh!

quaquel Dec 8, 2025 Maintainer

Uh oh!

EwoutH Dec 8, 2025 Maintainer Author

Uh oh!

quaquel Dec 8, 2025 Maintainer

Uh oh!

Uh oh!

EwoutH Jan 17, 2026 Maintainer Author

Core method

Convenience Functions

Decorator

Examples

One-off Events

Simple Recurring

Conditional Execution (Pausing)

Time-Bounded Recurring

Variable & Stochastic Intervals

Combining only_if with other constraints

Agent Self-Scheduling

Event Chaining (User Pattern)

Time Control

Comparison: only_if vs end_when

Migration from Mesa 3.x

Uh oh!

Uh oh!

EwoutH Jan 19, 2026 Maintainer Author

Uh oh!

Uh oh!

EwoutH Jan 20, 2026 Maintainer Author

Uh oh!

quaquel Jan 20, 2026 Maintainer

Uh oh!

EwoutH Jan 20, 2026 Maintainer Author

Uh oh!

EwoutH Jan 21, 2026 Maintainer Author

Uh oh!

EwoutH
Dec 3, 2025
Maintainer

Replies: 12 comments 76 replies

EwoutH
Dec 3, 2025
Maintainer Author

quaquel
Dec 3, 2025
Maintainer

EwoutH Dec 4, 2025
Maintainer Author

quaquel
Dec 5, 2025
Maintainer

EwoutH
Dec 5, 2025
Maintainer Author

quaquel Dec 6, 2025
Maintainer

EwoutH Dec 6, 2025
Maintainer Author

quaquel Dec 8, 2025
Maintainer

EwoutH Dec 8, 2025
Maintainer Author

quaquel Dec 8, 2025
Maintainer

EwoutH
Jan 17, 2026
Maintainer Author

EwoutH Jan 19, 2026
Maintainer Author

EwoutH Jan 20, 2026
Maintainer Author

quaquel Jan 20, 2026
Maintainer

EwoutH Jan 20, 2026
Maintainer Author

EwoutH Jan 21, 2026
Maintainer Author

ShreyasN707
Jan 17, 2026

EwoutH
Jan 21, 2026
Maintainer Author

Why not a single `schedule()` method?