Skip to content

Deprecate model.steps in favor of model.time#3136

Merged
EwoutH merged 3 commits intomesa:mainfrom
EwoutH:depr_steps
Jan 15, 2026
Merged

Deprecate model.steps in favor of model.time#3136
EwoutH merged 3 commits intomesa:mainfrom
EwoutH:depr_steps

Conversation

@EwoutH
Copy link
Copy Markdown
Member

@EwoutH EwoutH commented Jan 14, 2026 •
edited
Loading

This PR was reverted in #3151 due to advancing insight.

Summary

Deprecates model.steps with a FutureWarning directing users to use model.time instead. The attribute will be removed in Mesa 4.0.

Motive

Following the introduction of model.time as the universal source of truth for simulation time in #2903, model.steps is now redundant.

Implementation

  • Rename self.steps to self._steps (internal attribute)
  • Add steps property with getter and setter that:
    • Emit FutureWarning on access
    • Delegate to self._steps
  • Update _wrapped_step() to use self._steps directly (avoiding deprecation warning in internal code)
  • Update docstring to remove steps from the public attributes list
  • Add migration guide entry

batch_run changes are in a separate commit, for an easy cherry pick if needed.

Usage

Users will see this warning when accessing model.steps:

FutureWarning: model.steps is deprecated and will be removed in Mesa 4.0.
Use model.time instead.
See: https://mesa.readthedocs.io/latest/migration_guide.html#model-steps-deprecated

Migration Path

# Old
if model.steps >= 100:
    model.running = False

# New
if model.time >= 100:
    model.running = False

Checklist

  • Documentation updated to use model.time
  • Migration guide entry added
  • Example models updated to use model.time
  • Tests updated to use model.time (or suppress expected warnings)

Related

EwoutH added 3 commits January 14, 2026 18:37
@EwoutH
Deprecate model.steps in favor of model.time
71d74e4 
Deprecates `model.steps` with a `FutureWarning` directing users to use `model.time` instead. The attribute will be removed in Mesa 4.0.
@EwoutH
batch_run: Use ._steps instead of ._time
8d73309
@EwoutH
Document deprecation of model.steps in favor of model.time
00f6de7 
Updated the migration guide for Mesa 3.5 to note that `model.steps` is deprecated and will be removed in Mesa 4.0. Added instructions for migrating to `model.time` and provided code examples and references to relevant pull requests.
@EwoutH EwoutH requested a review from quaquel January 14, 2026 18:04
@EwoutH EwoutH added the deprecation When a new deprecation is introduced label Jan 14, 2026
@github-actions

This comment was marked as off-topic.

Sign in to view
EwoutH added a commit to mesa/mesa-examples that referenced this pull request Jan 14, 2026
@EwoutH
Update test to assert model.time instead of model.steps
7c00b4b 
Changed the test assertion to check the model's 'time' attribute equals 10.0 instead of 'steps' equaling 10.

Removes a Mesa FutureWarning. See mesa/mesa#3136
@EwoutH EwoutH mentioned this pull request Jan 14, 2026
Merged
@quaquel
Copy link
Copy Markdown
Member

quaquel commented Jan 14, 2026

I agree with this.

What else to deprecate in 3.5? At least seed on model, probably agent.pos, mesa.space, batch_run, and `datacollector.

@EwoutH
Copy link
Copy Markdown
Member Author

EwoutH commented Jan 14, 2026

My suggestion would be:

  • Let's deprecate everything now that we already have a (stable) replacement for
  • Wait a bit with deprecations if we don't have a replacement yet

@quaquel
Copy link
Copy Markdown
Member

quaquel commented Jan 14, 2026

But then its a bit strange that you start removing stuff like the datacollector

@EwoutH
Copy link
Copy Markdown
Member Author

EwoutH commented Jan 14, 2026

Yeah, I didn’t make this clear indeed:

  • Before branching of 3.x maintenance, let’s deprecate everything we already got a replacement for. Those deprecations will be included in a 3.5 release.
  • After that, we can deprecate/remove everything else, since that will only be included in 4.0.

@quaquel
Copy link
Copy Markdown
Member

quaquel commented Jan 14, 2026

So that does mean at least seed on Model and mesa.space. seed is replaced with rng in line with spec-7. mesa.space is fully replaced. We probably then should also move the continuous space out of experimental and make it stable?

@EwoutH
Copy link
Copy Markdown
Member Author

EwoutH commented Jan 14, 2026 •
edited
Loading

  1. yes
  2. I’m a bit afraid we’re going to ask people to move twice, considering we’re continuing development on the ContinuousSpace. So maybe backport a deprecation once we know that and how the final API works.

As soon as we have branched of 3.x, we can move ContinuousSpace out of experimental. Since we’re then in 4.0 alpha, it isn’t immediately API frozen, but it will be after 4.0 stable.

@EwoutH EwoutH merged commit 7a9299c into mesa:main Jan 15, 2026
29 of 33 checks passed
EwoutH added a commit to EwoutH/mesa that referenced this pull request Jan 16, 2026
@EwoutH
Revert "Deprecate model.steps in favor of model.time (mesa#3136)"
9a5e364 
This reverts commit 7a9299c.
@EwoutH EwoutH mentioned this pull request Jan 16, 2026
Merged
@EwoutH EwoutH added ignore-for-release PRs that aren't included in the release notes and removed deprecation When a new deprecation is introduced labels Jan 16, 2026
EwoutH added a commit that referenced this pull request Jan 16, 2026
@EwoutH
Revert "Deprecate model.steps in favor of model.time (#3136)" (#3151
bf76c1c 
)

This reverts commit 7a9299c.
Harshini2411 pushed a commit to Harshini2411/mesa-examples that referenced this pull request Mar 16, 2026
@EwoutH
Update test to assert model.time instead of model.steps
623796f 
Changed the test assertion to check the model's 'time' attribute equals 10.0 instead of 'steps' equaling 10.

Removes a Mesa FutureWarning. See mesa/mesa#3136
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@quaquel quaquel quaquel approved these changes

Assignees

No one assigned

Labels

ignore-for-release PRs that aren't included in the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@EwoutH @quaquel