Skip to content

Document Agent hashability requirement#3104

Merged
quaquel merged 4 commits intomesa:mainfrom
Sonu0305:hashability
Jan 12, 2026
Merged

Document Agent hashability requirement#3104
quaquel merged 4 commits intomesa:mainfrom
Sonu0305:hashability

Conversation

@Sonu0305
Copy link
Copy Markdown
Contributor

@Sonu0305 Sonu0305 commented Jan 9, 2026 •
edited
Loading

Summary

Clarifies the requirement for Mesa agents to be hashable and adds tests to verify this behavior, particularly when __eq__ is overridden in subclasses.

Motive

AgentSet requires agents to be hashable because it uses them in a WeakKeyDictionary. This requirement was previously implicit. An earlier attempt to enforce this via the type system (collections.abc.Hashable) was reverted due to significant performance regressions.

Implementation

Usage Examples

Additional Notes

@github-actions
Copy link
Copy Markdown

github-actions bot commented Jan 9, 2026

Performance benchmarks:

Model Size Init time [95% CI] Run time [95% CI]
BoltzmannWealth small 🔴 +45.0% [+44.6%, +45.5%] 🔵 -0.6% [-0.7%, -0.6%]
BoltzmannWealth large 🔴 +4710.0% [+4695.2%, +4725.0%] 🔵 +0.6% [+0.0%, +1.2%]
Schelling small 🔴 +153.5% [+151.0%, +155.9%] 🔵 +0.8% [+0.2%, +1.4%]
Schelling large 🔴 +989.2% [+984.0%, +995.1%] 🔵 +0.3% [-0.2%, +0.6%]
WolfSheep small 🔴 +329.2% [+327.0%, +331.4%] 🔴 +288.1% [+254.5%, +322.9%]
WolfSheep large 🔴 +6028.4% [+5838.7%, +6141.4%] 🔴 +3453.4% [+3411.4%, +3491.1%]
BoidFlockers small 🔴 +105.6% [+104.8%, +106.3%] 🔴 +13.6% [+13.5%, +13.7%]
BoidFlockers large 🔴 +213.4% [+211.8%, +215.1%] 🔴 +52.0% [+51.2%, +52.7%]

@quaquel quaquel mentioned this pull request Jan 9, 2026
Closed
@EwoutH
Copy link
Copy Markdown
Member

EwoutH commented Jan 10, 2026

Wow I didn’t expect this much performance impact. Especially WolfSheep is terrible, it’s the only model that actively removes and adds agents during the run.

I don’t think this is a proportional performance trade-off, glad we have the benchmarks.

Curious if there are more efficient ways to enforce hashibility.

@Sonu0305
Copy link
Copy Markdown
Contributor Author

Sonu0305 commented Jan 10, 2026

Wow I didn’t expect this much performance impact. Especially WolfSheep is terrible, it’s the only model that actively removes and adds agents during the run.

I don’t think this is a proportional performance trade-off, glad we have the benchmarks.

Curious if there are more efficient ways to enforce hashibility.

Right, benchmarks got us safe.
I also agree to @quaquel regarding we should just include in the documentation that I have already added to the Notes section of the class Agent.

@Sonu0305 Sonu0305 marked this pull request as draft January 10, 2026 06:01
@Sonu0305 Sonu0305 changed the title Make Agent hashability explicit in type system Document Agent hashability requirement Jan 10, 2026
@Sonu0305 Sonu0305 marked this pull request as ready for review January 10, 2026 06:04
@Sonu0305
Copy link
Copy Markdown
Contributor Author

Sonu0305 commented Jan 10, 2026

I have updated the pr description to be precise.
I am a bit confused regarding how do I cover the lines added to the test file itself? (the lines which are causing the codecov test to fail).

@github-actions
Copy link
Copy Markdown

github-actions bot commented Jan 10, 2026

Performance benchmarks:

Model Size Init time [95% CI] Run time [95% CI]
BoltzmannWealth small 🟢 -4.3% [-5.3%, -3.3%] 🔵 -0.6% [-0.7%, -0.5%]
BoltzmannWealth large 🔵 -0.5% [-1.1%, +0.2%] 🔵 -1.0% [-2.3%, +0.5%]
Schelling small 🔵 -0.1% [-1.1%, +0.9%] 🔵 +0.6% [+0.0%, +1.1%]
Schelling large 🔵 +0.6% [-0.1%, +1.3%] 🔵 -0.5% [-1.5%, +0.5%]
WolfSheep small 🔵 -1.2% [-1.6%, -0.8%] 🔵 -3.3% [-4.1%, -2.4%]
WolfSheep large 🔵 -0.7% [-2.8%, +0.7%] 🔵 +0.3% [-1.4%, +1.9%]
BoidFlockers small 🔵 +0.2% [-0.2%, +0.5%] 🔵 +0.1% [-0.1%, +0.3%]
BoidFlockers large 🔵 -0.4% [-0.5%, -0.2%] 🔵 +0.2% [-0.0%, +0.4%]

@quaquel quaquel added the docs Release notes label label Jan 10, 2026
quaquel
quaquel reviewed Jan 10, 2026
View reviewed changes
quaquel
quaquel reviewed Jan 10, 2026
View reviewed changes
@Sonu0305 Sonu0305 requested a review from quaquel January 11, 2026 14:15
@quaquel quaquel merged commit b5bd3cc into mesa:main Jan 12, 2026
13 of 14 checks passed
@Sonu0305 Sonu0305 deleted the hashability branch January 12, 2026 14:21
@quaquel quaquel linked an issue Jan 12, 2026 that may be closed by this pull request
Make Agent hashability requirement explicit in type system #3101
Closed
EwoutH pushed a commit to EwoutH/mesa that referenced this pull request Jan 23, 2026
@Sonu0305 @EwoutH
Explicitly document Agent hashability requirement (mesa#3104)
12250ae
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

docs Release notes label

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Make Agent hashability requirement explicit in type system

3 participants

@Sonu0305 @EwoutH @quaquel