Updating Scenario in preparation for replacing batch runner by quaquel · Pull Request #3493 · mesa/mesa

quaquel · 2026-03-09T21:02:50Z

This PR updates the Scenario class and how it is used inside Model. It is inspired by ideas in #3483.

Scenario becomes the sole place where rng and stdlib random are defined. Model just uses these.
Model.__init__ is updated to take either a Scenario subclass or instance. (supersedes ENH: Accept Scenario as class or instance in Model init #3450)
Scenario is now fully frozen after instantiation without a complicated ref back to model.
Scenarios can spawn replications. This builds on fix-spawn-generator #3195 but updates the idea for use inside Scenario. See also the numpy docs for more details on how this all works.
I added two class methods for creating scenarios from either a numpy array or a pandas dataframe.
I updated all relevant examples to use the new machinery.

So what are the API implications from this?

# this now works and uses the default values from your custom scenario
model = MyModel(scenario=MyScenario)

# rng will be passed to MyScenario(rng=rng)
model = MyModel(scenario=MyScenario, rng=42) 

# running 10 replications of a given scenario.
# the rng is different for all 10 and derived via numpy.random.default_rng(42).spawn(10)
scenario = MyScenario(a=1, b=2, rng-42)
for replication in scenario.spawn_replications(n=10):
    model = MyModel(scenario=replication)

# scenario is frozen
my_scenario = MyScenario(a=1, b=2)
my_scenario.a = 4  # raises a TypeError - inline with e.g. frozen dataclasses and tuples

# just using the base scenario still works as before
# custom scenarios just exist to specify defaults
scenario = Scenario(rng=42, a=1, b=2)

Make Scenario the single source of truth for RNG state Scenario now owns the canonical RNG state. Model derives self.rng and self.random from the scenario rather than maintaining parallel `_seed`/`_rng` state, eliminating the broken scenario._seed reference in `Model.__init__`. Key changes: - `Scenario._stdlib_seed` property derives a reproducible integer seed for random.Random from initial_rng_state without advancing the generator - `Model.__init__` always creates a Scenario first (rng= is a convenience shorthand), raises ValueError if both rng and scenario are passed - Removed `Model.reset_rng()`` and the now-dead `_seed`/`_rng` instance vars from Model - replication_id defaults to None to distinguish base scenarios from replication 0; scenario_id uses None as sentinel so id=0 is preserved - Fixed docstring references to removed `_seed` attribute - Updated tests to use `scenario.initial_rng_state` instead of `model._rng`

remove none as an option because now covered by the class

for more information, see https://pre-commit.ci

github-actions · 2026-03-09T21:24:11Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -0.8% [-1.4%, -0.1%]	🔵 +0.4% [+0.2%, +0.6%]
BoltzmannWealth	large	🔵 +2.1% [+1.3%, +2.9%]	🔵 -1.1% [-2.2%, +0.0%]
Schelling	small	🔵 -0.1% [-0.6%, +0.4%]	🔵 +0.4% [-0.2%, +1.1%]
Schelling	large	🔵 -0.0% [-0.6%, +0.6%]	🔵 -1.1% [-2.4%, +0.4%]
WolfSheep	small	🔵 -3.2% [-4.3%, -2.1%]	🔵 +8.0% [+2.2%, +14.1%]
WolfSheep	large	🔵 +0.4% [-0.2%, +0.9%]	🔵 +4.0% [+2.4%, +5.8%]
SugarscapeG1mt	small	🔵 -1.3% [-1.9%, -0.7%]	🔵 -0.7% [-1.8%, +0.4%]
SugarscapeG1mt	large	🔵 -0.5% [-2.0%, +0.8%]	🔵 +1.4% [+0.5%, +2.5%]
BoidFlockers	small	🔵 -2.2% [-3.0%, -1.6%]	🔵 -0.3% [-0.5%, -0.0%]
BoidFlockers	large	🔵 -0.6% [-1.5%, +0.2%]	🔵 -0.2% [-0.5%, +0.2%]

EwoutH

Thanks for working on this. I think you’re looking in the right direction.

EwoutH · 2026-03-10T07:00:10Z

mesa/experimental/scenarios/scenario.py

        scenario_id: A unique identifier for this scenario, auto-generated starting from 0
-        rng: Random number generator or seed value
+        experiment_id: Identifies the design point (e.g., row in a QMC sample matrix)
+        replication_id: Identifies the stochastic replication within a design point


Could you elaborate on why we now need 3 different id variables? Are there other options?

Based on my experience with the workbench, there are no clean other options.

We need scenario_id as a link to the original experiment matrix (e.g., from numpy.qmc, or salib)

We need a replication_id for reproduction. Only by knowing this can you reproduce the exact results for a given experiment.

We need a high entropy starting RNG value for high quality random number generation (and no 42 is not a high entropy starting value because this has 30 0 in front of it.

I also fail to see what the problem is. Scenario_id and replication_id are in principle generated by Mesa itself so the user need not worry about them at all.

EwoutH · 2026-03-10T07:03:05Z

mesa/experimental/scenarios/scenario.py

+            "initial_rng_state": self.initial_rng_state,
+        }
+
+    def spawn_replications(self, n: int) -> list["Scenario"]:


Would this make sense as a Class method? Like we do with Agent.create_agents() I believe?

No it cannot be a class method. spawn_replication takes a base scenario instance with the scenario-specific user-provided arguments and creates n versions of it, each with a unique, independent, seeded numpy generator.

for more information, see https://pre-commit.ci

github-actions · 2026-03-12T10:25:56Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🟢 -8.5% [-9.4%, -7.7%]	🔵 -0.8% [-1.0%, -0.6%]
BoltzmannWealth	large	🔵 -1.6% [-3.0%, +0.0%]	🔵 -4.1% [-8.2%, -0.2%]
Schelling	small	🔵 +0.5% [-0.7%, +1.6%]	🔵 +0.7% [-0.7%, +1.8%]
Schelling	large	🔵 -1.2% [-2.6%, +0.1%]	🔵 -2.1% [-4.7%, +0.7%]
WolfSheep	small	🔵 +1.0% [+0.1%, +1.9%]	🔵 +6.1% [+1.5%, +10.3%]
WolfSheep	large	🔵 -1.8% [-3.8%, +0.1%]	🔵 -2.6% [-4.9%, -0.2%]
SugarscapeG1mt	small	🔵 -2.1% [-3.2%, -1.0%]	🔵 -3.0% [-4.3%, -1.6%]
SugarscapeG1mt	large	🔵 -5.0% [-7.9%, -2.2%]	🔵 -3.3% [-4.4%, -2.0%]
BoidFlockers	small	🟢 -5.5% [-6.4%, -4.6%]	🔵 -1.3% [-1.7%, -0.9%]
BoidFlockers	large	🔵 -3.5% [-4.6%, -2.2%]	🔵 -1.9% [-2.3%, -1.6%]

mesa/examples/advanced/alliance_formation/model.py

EwoutH

Cleans up the model nicely. Thanks.

quaquel added 3 commits March 9, 2026 21:37

allow scenario class

8a20daf

remove none as an option because now covered by the class

update examples

9c3d389

quaquel added enhancement Release notes label breaking Release notes label labels Mar 9, 2026

pre-commit-ci bot and others added 4 commits March 9, 2026 21:04

[pre-commit.ci] auto fixes from pre-commit.com hooks

830eac9

for more information, see https://pre-commit.ci

Update test_examples.py

c7d24aa

ruff fixes

359fb02

[pre-commit.ci] auto fixes from pre-commit.com hooks

eb4b9ca

for more information, see https://pre-commit.ci

EwoutH reviewed Mar 10, 2026

View reviewed changes

quaquel added 4 commits March 10, 2026 12:39

ongoing

bd1c3dd

ongoing

82c6424

Update datarecorders.py

5b1a623

docstring fix

677391c

This was referenced Mar 10, 2026

ENH: Accept Scenario as class or instance in Model init #3450

Closed

fix-spawn-generator #3195

Closed

quaquel and others added 7 commits March 10, 2026 15:02

Merge remote-tracking branch 'upstream/main' into scenario_update

5df7af0

add class methods for creating scenarios

30806c1

[pre-commit.ci] auto fixes from pre-commit.com hooks

c9920d5

for more information, see https://pre-commit.ci

Merge branch 'main' into scenario_update

a5114a5

add tests

eeb51c5

[pre-commit.ci] auto fixes from pre-commit.com hooks

5277627

for more information, see https://pre-commit.ci

Merge remote-tracking branch 'upstream/main' into scenario_update

6d0265e

quaquel marked this pull request as ready for review March 12, 2026 10:02

quaquel mentioned this pull request Mar 13, 2026

Add M/M/c queue example as canonical DES model mesa/mesa-examples#340

Merged

EwoutH reviewed Mar 13, 2026

View reviewed changes

mesa/examples/advanced/alliance_formation/model.py Show resolved Hide resolved

EwoutH approved these changes Mar 13, 2026

View reviewed changes

quaquel merged commit 166e094 into mesa:main Mar 13, 2026
15 checks passed

satharyasin-hub mentioned this pull request Mar 14, 2026

Accept Scenario as class or instance in Model init #3435

Closed

quaquel mentioned this pull request Mar 14, 2026

Update benchmarks to use the new Scenario API #3531

Merged

quaquel deleted the scenario_update branch March 14, 2026 07:19

quaquel mentioned this pull request Mar 14, 2026

Update release notes and version for 4.0.0a0 (alpha 0) #3527

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Updating Scenario in preparation for replacing batch runner#3493

Updating Scenario in preparation for replacing batch runner#3493
quaquel merged 18 commits intomesa:mainfrom
quaquel:scenario_update

quaquel commented Mar 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 9, 2026

Uh oh!

EwoutH left a comment

Uh oh!

EwoutH Mar 10, 2026

Uh oh!

quaquel Mar 10, 2026

Uh oh!

EwoutH Mar 10, 2026

Uh oh!

quaquel Mar 10, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 12, 2026

Uh oh!

Uh oh!

EwoutH left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Uh oh!

github-actions bot commented Mar 9, 2026

Uh oh!

EwoutH left a comment

Choose a reason for hiding this comment

Uh oh!

EwoutH Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

quaquel Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

EwoutH Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 12, 2026

Uh oh!

Uh oh!

EwoutH left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

quaquel commented Mar 9, 2026 •

edited

Loading

quaquel Mar 10, 2026 •

edited

Loading