Refactor step scheduling to use `EventGenerator` internally by EwoutH · Pull Request #3260 · mesa/mesa

EwoutH · 2026-02-08T17:45:08Z

See the "Does Mesa need a "heartbeat"?" discussion in #2921 (comment).

Summary

Replaces the hand-rolled step rescheduling loop in Model with an internal EventGenerator, simplifying the code while keeping all behavior and API identical.

Motive

The current step scheduling uses a manual pattern: _do_step() calls _schedule_step(), which creates a SimulationEvent that calls _do_step() again. This is functionally an EventGenerator — but reimplemented ad-hoc. Now that EventGenerator exists (#3201), we should use it.

This also removes _schedule_step() entirely and simplifies both _do_step() and _wrapped_step(), reducing the amount of scheduling logic in Model.

Implementation

The self-rescheduling loop (_do_step() → _schedule_step() → SimulationEvent → _do_step()) is replaced by a single _default_schedule EventGenerator created and started in Model.__init__(). This simplifies _wrapped_step() to just self._advance_time(self.time + 1), reduces _do_step() to incrementing steps and calling the user's step method, and removes _schedule_step() entirely.

On the simulator side, Simulator.setup() now checks model._simulator is not None instead of event_list.is_empty() (since the event list has events from _default_schedule at init), ABMSimulator.setup() no longer needs to manually schedule the first step, and DEVSSimulator.setup() explicitly stops _default_schedule before clearing the event list.

Additional Notes

No public API changes: this is purely an internal refactor
All existing model.step(), run_for(), run_until() behavior is unchanged
_default_schedule is private (_-prefixed). Exposing it as a public API with a property setter is left for a follow-up PR
The Simulator.setup() guard change from checking event_list.is_empty() to model._simulator is not None is necessary because the event list now contains events from _default_schedule immediately after init

Replace manual SimulationEvent scheduling with an EventGenerator-based default schedule. The model now stores the user's step as _user_step and installs a default_schedule EventGenerator (interval 1.0, start 1.0, high priority) that calls _do_step and is started during init. Removed the old _schedule_step helper and the SimulationEvent-based scheduling; _do_step no longer reschedules itself (rescheduling is handled by the EventGenerator). Updated imports to include EventGenerator and Schedule.

Remove the ABMSimulator explicit initial step scheduling because the model's default_schedule is started in Model.__init__. In DEVSimulator.setup explicitly stop the model.default_schedule and clear any pre-scheduled events to avoid automatic step scheduling for pure DEVS models.

Turn default_schedule into a managed property: assigning a new EventGenerator stops any existing one and auto-starts the new one, and assigning None disables the schedule. Remove the immediate .start() call from the constructor so the setter handles lifecycle. Add a docstring clarifying behavior.

quaquel · 2026-02-08T17:53:35Z

Thanks for this PR. I agree with the basic premise of using EvenGenerator for this, but I am not sure about the current implementation. I'll try to take a closer look asap.

This is potential groundwork for a "heartbeat" concept: a default recurring event that Mesa components (data collection, visualization, stop conditions) can (by default) attach to. By exposing it as default_schedule, we make this pattern explicit and user-configurable without committing to a larger API yet.

With model.time being reactive, there is simply no need for a heartbeat. Anything that is triggered by time changing can just observe model.time and take if from there.

Disable stepping for pure event-driven models:

I don't really like this I prefer opt-in over opt-out.

Currently model.step() is overloaded to mean two things:

the user's model logic ("what happens each step")
time advancement ("advance the clock by 1").

I agree wtih you on this completely and decoupling the two is the way to go. Time then becomes the purview of the evenlists and the run control. And this is also why I wanted time to be reactive.

github-actions · 2026-02-08T18:01:22Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -0.2% [-1.4%, +0.8%]	🔵 -2.0% [-2.3%, -1.7%]
BoltzmannWealth	large	🔵 -0.5% [-1.1%, +0.1%]	🔵 +1.3% [-0.1%, +2.7%]
Schelling	small	🔵 +2.2% [+1.7%, +2.6%]	🔵 +1.3% [+1.2%, +1.5%]
Schelling	large	🔵 +0.9% [+0.2%, +1.6%]	🔵 +4.8% [+2.7%, +6.8%]
WolfSheep	small	🔵 +0.6% [+0.2%, +1.0%]	🔵 +0.3% [+0.1%, +0.4%]
WolfSheep	large	🔵 +0.4% [-1.4%, +1.8%]	🔵 +3.3% [+1.4%, +5.1%]
BoidFlockers	small	🔵 +0.4% [+0.1%, +0.7%]	🔵 +1.3% [+1.1%, +1.6%]
BoidFlockers	large	🔵 -0.3% [-0.8%, +0.1%]	🔵 +0.2% [-0.2%, +0.5%]

EwoutH · 2026-02-08T18:18:30Z

I don't really like this I prefer opt-in over opt-out.

I think we almost go to a philosophical level of "are ticks core to ABM or were they just the easy implementation and everybody stuck with it".

Anyway, we can't change that in Mesa 3.x, but it's something to discuss for Mesa 4. In that case it just will be as easy as setting default_schedule to None by default.

But discussing the merrit of a default_schedule is important.

quaquel · 2026-02-08T18:57:04Z

But discussing the merrit of a default_schedule is important.

As indicated, I am not convinced by it, but without diving into the code I am also not sure how you could otherwise achieve the things that are clearly valuable here. Namely, replacing "the internal hand-rolled step rescheduling mechanism with an exposed EventGenerator", and more cleanly separating the step method from the time increment.

What I would like to see is an easy way for the user to specify that e.g. model.step is to be run on a given schedule with meaningful defaults (i.e., interval=1, start=0, stop=None, count=None). Where I guess I make a difference is that would prefer (even if only in MESA 4) to not make an assumption about this and leave it to the user to specify it. This was also behind the earlier idea of just adding a @scheduled to model.step.

EwoutH · 2026-02-08T19:25:09Z

If we do see value in this refactor but not in exposing it (currently) to the public, we could of course make default_schedule private (_default_schedule).

@mesa/maintainers I would like some more opinions and perspectives if we need a default scheduled method ("heart beat") or not. You don't need to dive in to the code, just conceptually if you see use/need for it. See also: #2921 (comment).

quaquel · 2026-02-08T20:43:05Z

mesa/model.py

+        self.default_schedule = EventGenerator(
+            self,
+            self._do_step,
+            Schedule(interval=1.0, start=1.0),


why start at 1 instead of at zero? zero is just the state of the system prior to any events I guess (so the initial condition)?

Basically because it’s the current convention in Mesa. 0 is setup, 1 the first step. Original discussion: #2229 (comment)

(thank our excellent migration guide to help me find this back).

I recall that discussion, so yes this makes perfect sense.

I quick semi related question: do we allow Schedule(start=0)? Or should start always be larger than 0?

In my view we explicitly allow that. The default is just to start after one interval, but that can be any non-negative number.

mesa/model.py

quaquel · 2026-02-08T20:50:49Z

I reviewed the code. I don't have major issues with this. I think it is helpful to separate mesa 3 from mesa 4 going forward. We currently have a lot of baggage with wrapped_step and model.steps etc. This makes finding an elegant backward compatible solution clearly non trivial. So, I am fine with this solution in Mesa 3, but would prefer to revisit this for mesa 4.

Also, coverage is a bit low, so I assume you'll update some tests after which I am fine with approving this.

Create an internal _default_schedule EventGenerator (and store the original user step in _user_step), start it immediately, and assign the wrapped step to self.step. Remove the public default_schedule property and its getter/setter to simplify lifecycle management. Update DEVSimulator to stop model._default_schedule instead of model.default_schedule. This avoids accidental recursion/misuse and ensures the recurring step event is started and stopped reliably.

EwoutH · 2026-02-09T17:44:44Z

I realized this PR was doing two things: An internal refactor and exposing a new user API surface. That doesn't make it atomic, and so, let's split the two.

I refactored this PR to only do the former. Then we can later discuss the latter.

Since we don't expose a new API or enable new behavior, no additional tests are needed.

quaquel · 2026-02-09T18:11:39Z

Since we don't expose a new API or enable new behavior, no additional tests are needed.

I don't agree with this claim. The relevant question is how the coverage has changed due to refactoring and ensuring that the refactored code is still properly covered. That is the case here judged by codecov, but it also makes me wonder how the percentage is so low. I guess because the number of lines changed is quite small.

EwoutH · 2026-02-09T18:14:25Z

Fair point. I'm planning on fully revising the test suite once we have done the post branching to Mesa 4 cleanup.

EwoutH added 4 commits February 8, 2026 18:04

Add Guard against passing step

889c398

EwoutH added the feature Release notes label label Feb 8, 2026

quaquel reviewed Feb 8, 2026

View reviewed changes

mesa/model.py Show resolved Hide resolved

EwoutH changed the title ~~Expose step scheduling as default_schedule EventGenerator~~ Refactor step scheduling to use EventGenerator internally Feb 9, 2026

EwoutH added maintenance Release notes label enhancement Release notes label and removed feature Release notes label maintenance Release notes label labels Feb 9, 2026

Merge branch 'main' into default_schedule

d608e35

EwoutH mentioned this pull request Feb 9, 2026

Mesa 4 development tracking issue #3132

Open

42 tasks

quaquel approved these changes Feb 9, 2026

View reviewed changes

EwoutH merged commit 05e2a0a into mesa:main Feb 9, 2026
12 of 14 checks passed

Uh oh!

Conversation

EwoutH commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motive

Implementation

Additional Notes

Uh oh!

quaquel commented Feb 8, 2026

Uh oh!

github-actions bot commented Feb 8, 2026

Uh oh!

EwoutH commented Feb 8, 2026

Uh oh!

quaquel commented Feb 8, 2026

Uh oh!

EwoutH commented Feb 8, 2026

Uh oh!

quaquel Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

EwoutH Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

quaquel Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

EwoutH Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

quaquel commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

EwoutH commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quaquel commented Feb 9, 2026

Uh oh!

Uh oh!

EwoutH commented Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

EwoutH commented Feb 8, 2026 •

edited

Loading

quaquel commented Feb 8, 2026 •

edited

Loading

EwoutH commented Feb 9, 2026 •

edited

Loading