Deprecate `seed` parameter in favor of `rng` in Model by quaquel · Pull Request #3147 · mesa/mesa

quaquel · 2026-01-16T07:50:02Z

This PR deprecates the seed parameter in Model.__init__() and Model.reset_randomizer() in favor of the SPEC-7 compliant rng parameter. Users will now see a FutureWarning when using seed, encouraging migration to rng.

Migration

This is a simple parameter name change with no behavioral differences:

# Old (now deprecated)
model = MyModel(seed=42)

# New
model = MyModel(rng=42)

The functionality remains identical - both approaches seed the random number generators in the same way. This change is part of aligning Mesa with SPEC-7 (scientific Python community standards for random number generation).

Notes

model.random (Python's random.Random) continues to exist and function as before
model.rng (NumPy's Generator) continues to exist and function as before
Both are seeded identically whether you use seed or rng parameter
The deprecation will be removed in Mesa 4.0

Ref: #2352 (original rng implementation)

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

github-actions · 2026-01-16T07:56:55Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +0.6% [-0.4%, +1.5%]	🔵 +0.3% [+0.1%, +0.4%]
BoltzmannWealth	large	🔵 +0.9% [+0.1%, +1.7%]	🔵 +0.5% [-2.6%, +4.8%]
Schelling	small	🔵 +1.4% [+1.0%, +1.9%]	🔵 +1.5% [+1.1%, +1.9%]
Schelling	large	🔵 +0.4% [-0.5%, +1.5%]	🔵 +0.5% [-2.6%, +3.7%]
WolfSheep	small	🔵 -1.5% [-2.0%, -0.9%]	🔵 -1.7% [-2.6%, -0.7%]
WolfSheep	large	🔵 +1.1% [-1.1%, +3.2%]	🔵 +3.8% [+0.6%, +7.0%]
BoidFlockers	small	🔴 +3.9% [+3.1%, +4.7%]	🔵 +2.7% [+2.3%, +3.2%]
BoidFlockers	large	🔵 +0.2% [-0.3%, +0.7%]	🔵 +0.6% [+0.2%, +1.0%]

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

EwoutH

Thanks for this extensive effort, appreciated.

Overal looks good, a (small) note in the migration guide should be added and a few nitpicks.

EwoutH · 2026-01-17T15:25:14Z

mesa/model.py

            self._seed = seed  # this allows for reproducing stdlib.random
        elif rng is None:
+            warnings.warn(
+                "the use of seed is deprecated, use rng instead",


Add link to migration guide

There is nothing in the migration guide on this. Also, I would argue that the message is all you need. Just use rng instead of seed.

While the actual code change is indeed very small, that change is made for a reason and has implications. Therefor I do think an entry is warranted.

Completeness is also important here. The migration guide should contain everything you need to know when updating to a new Mesa version.

It's also a chance to educate our users.

I think something like this would be a good start (feel free to edit of course).

## Mesa 3.5.0 ### Deprecation of `seed` in favor of `rng` The `seed` parameter on `Model.__init__` and the `reset_randomizer` method are deprecated in favor of [[SPEC-7](https://scientific-python.org/specs/spec-0007/)](https://scientific-python.org/specs/spec-0007/) compliant NumPy random number generation. NumPy's `Generator` class provides higher-quality random number generation compared to Python's built-in `random` module or NumPy's legacy `RandomState`. The new `rng` parameter follows scientific Python community standards and offers better reproducibility controls. ```python # Old model = MyModel(seed=42) model.reset_randomizer(seed=42) # New model = MyModel(rng=42) model.reset_rng(rng=42) ``` Within your model, use `model.rng` (a `numpy.random.Generator`) instead of `model.random` for random number generation. The `rng` parameter accepts integers, sequences of integers, `numpy.random.SeedSequence`, `numpy.random.Generator`, or `numpy.random.BitGenerator`. * Ref: [PR #2352](https://github.com/mesa/mesa/pull/2352)](https://github.com/mesa/mesa/pull/2352)

But most of what is said in your suggested text is not what this PR does. Model.random still exists. If you used seed and now shift to rng, the model will even behave the same. Really, the only thing that has changed is that we prefer using the rng keyword over the seed keyword, without any change in underlying logic or behavior.

Ah right, I thought this was a bigger shift.

EwoutH · 2026-01-17T15:25:26Z

mesa/model.py

            seed: A new seed for the RNG; if None, reset using the current seed
        """
+        warnings.warn(
+            "the use of seed is deprecated, use rng instead",


link to migration guide

mesa/model.py

tests/test_model.py

Co-authored-by: Ewout ter Hoeven <[email protected]>

…odel

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

…odel

EwoutH · 2026-01-18T09:15:23Z

For my context, is this the first step in a series of deprecations towards SPEC-7 compliance, of is this (for now) the only one?

What's the future of .random()?

I feel somehow we should communicate to our users why we're changing this and how that impacts them.

quaquel · 2026-01-18T09:24:31Z

For my context, is this the first step in a series of deprecations towards SPEC-7 compliance, of is this (for now) the only one?

This is all that is required to become compliant with spec-7. Spec-7 specifies the use of rng as keyword argument and the use of non-global random number generators. The latter we already have with model.rng and model.random

What's the future of .random()?

To be decided. I prefer fully removing it inside Mesa, but this has profound performance consequences. I also figured out that random.Random, which we use in mesa, is a non-global instance of a seeded stdlib random number generator. So one of my reasons for removing model.random is not valid.

I feel somehow we should communicate to our users why we're changing this and how that impacts them.

Like I said, the impact at the moment is only a change in preferred keyword (to become spec-7 compliant). We could explain this in the release notes.

EwoutH

Thanks for the context.

Minor suggestion on the message, and if we include it in the release notes that should be enough.

mesa/model.py

Co-authored-by: Ewout ter Hoeven <[email protected]>

quaquel and others added 2 commits January 16, 2026 08:48

Update model.py

f4783c6

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

fa5503e

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

quaquel and others added 5 commits January 16, 2026 09:37

fix all tests for deprecation of seed

15632b5

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

12c4bd7

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

updates

6f93a21

Update test_model.py

5aef3c3

Update test_examples.py

ddf681c

quaquel added the deprecation When a new deprecation is introduced label Jan 16, 2026

quaquel requested a review from EwoutH January 16, 2026 17:44

EwoutH reviewed Jan 17, 2026

View reviewed changes

quaquel and others added 11 commits January 17, 2026 17:04

Update mesa/model.py

5d47c0c

Co-authored-by: Ewout ter Hoeven <[email protected]>

Update mesa/model.py

cbeef90

Co-authored-by: Ewout ter Hoeven <[email protected]>

Update test_model.py

debfebd

Merge remote-tracking branch 'upstream/main' into deprecate_seed_on_m…

f584934

…odel

Update model.py

0caa1a1

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

e740688

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

Update test_mesa_signals.py

ccace5c

Merge branch 'main' into deprecate_seed_on_model

3404822

Update test_model.py

8ab0654

Merge remote-tracking branch 'upstream/main' into deprecate_seed_on_m…

083c65a

…odel

Update test_mesa_signals.py

f727c3f

EwoutH approved these changes Jan 18, 2026

View reviewed changes

mesa/model.py Outdated Show resolved Hide resolved

mesa/model.py Outdated Show resolved Hide resolved

EwoutH changed the title ~~Add deprecation warnings for seed on Model.__init__~~ Deprecate seed parameter in favor of rng in Model Jan 18, 2026

quaquel and others added 2 commits January 18, 2026 11:03

Update mesa/model.py

bce6d7a

Co-authored-by: Ewout ter Hoeven <[email protected]>

Update mesa/model.py

c23f5a3

Co-authored-by: Ewout ter Hoeven <[email protected]>

quaquel merged commit b6da37e into mesa:main Jan 18, 2026
9 of 12 checks passed

EwoutH mentioned this pull request Jan 18, 2026

Update Termites and Warehouse examples to use rng parameter mesa/mesa-examples#307

Merged

quaquel added a commit to quaquel/mesa that referenced this pull request Jan 18, 2026

Deprecate seed parameter in favor of rng in Model (mesa#3147)

822e9f0

quaquel mentioned this pull request Jan 18, 2026

replace seed with rng in benchmarking #3175

Merged

quaquel deleted the deprecate_seed_on_model branch January 19, 2026 21:02

Uh oh!

Conversation

quaquel commented Jan 16, 2026 • edited by EwoutH Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Migration

Notes

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

EwoutH left a comment

Choose a reason for hiding this comment

Uh oh!

EwoutH Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

quaquel Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

EwoutH Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

quaquel Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

EwoutH Jan 18, 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!

EwoutH Jan 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

quaquel commented Jan 18, 2026

Uh oh!

EwoutH left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

quaquel commented Jan 16, 2026 •

edited by EwoutH

Loading

EwoutH Jan 18, 2026 •

edited

Loading

EwoutH commented Jan 18, 2026 •

edited

Loading