Introduce AbstractAgentSet to agent.py and refactor AgentSet to inherit from it by codebreaker32 · Pull Request #3210 · mesa/mesa

codebreaker32 · 2026-01-26T06:49:51Z

Summary

This PR introduces AbstractAgentSet as an abstract base class for all agent collection implementations in Mesa. This establishes a formal interface and sets the foundation for introducing alternative storage mechanisms (strong vs weak references) while maintaining backward compatibility. Further, It refactors AgentSet class to inherit from it

Motive

For complete discussion: see #3128 and #3160

Changes

New: AbstractAgentSet class: Defines the minimal interface for agent collections via abstract methods.
Refactored: AgentSet class

Now inherits from AbstractAgentSet
All existing functionality preserved
Implements all abstract methods with weakref-optimized versions
Retains performance optimizations:

Fully backward compatible - No breaking changes

Ticks (1) from #3209

github-actions · 2026-01-26T07:07:40Z

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -2.3% [-2.9%, -1.7%]	🟢 -5.8% [-6.0%, -5.6%]
BoltzmannWealth	large	🔵 +0.0% [-1.0%, +1.2%]	🔵 -1.2% [-5.8%, +3.2%]
Schelling	small	🔵 +0.1% [-0.5%, +0.7%]	🔵 -1.2% [-1.6%, -0.7%]
Schelling	large	🔵 -0.5% [-1.1%, +0.0%]	🔵 -3.0% [-6.3%, +0.5%]
WolfSheep	small	🔵 -0.5% [-1.5%, +0.5%]	🔵 -1.2% [-1.7%, -0.8%]
WolfSheep	large	🔵 -2.1% [-3.5%, -0.9%]	🟢 -6.1% [-7.7%, -4.6%]
BoidFlockers	small	🔵 -0.5% [-0.9%, -0.2%]	🔵 +1.1% [+0.9%, +1.4%]
BoidFlockers	large	🔵 -0.3% [-0.9%, +0.4%]	🔵 -0.0% [-0.5%, +0.4%]

codebreaker32 · 2026-01-26T07:11:30Z

I also have a refactoring suggestion:

In groupby:

Instead of passing a string result_type="list" or "agentset", can we pass a boolean flag as_list.
If as_list=True, list will be returned otherwise agentset(or strongagentset)

I have not introduced it here to keep it atomic

mesa/agent.py

quaquel · 2026-01-26T07:24:45Z

I also have a refactoring suggestion:

In groupby:

Instead of passing a string result_type="list" or "agentset", can we pass a boolean flag as_list.

If as_list=True, list will be returned otherwise agentset(or strongagentset)

I have not introduced it here to keep it atomic

It would also be a backward-incompatibility change, so we cannot do that in Mesa 3.x because of semver.

1. AbstractAgentSet no longer inherits from Sequence 2. AgentSet explicitly inherits from Sequence to maintain backward compatibility

codebyNJ · 2026-01-26T13:18:23Z

few observations @codebreaker32:

Typo: "ABstractAgentSet" in _update docstring
Question: select() uses type(self) while groupby() hardcodes AgentSet - is this intentional? (For Phase 2 Tracking Issue: AgentSet Refactoring and _HardKeyAgentSet Implementation using AbstractAgentSet #3209, should StrongAgentSet return weak refs from all methods, or should the base class use type(self) and StrongAgentSet override?)

codebreaker32 · 2026-01-26T14:23:16Z

select() uses type(self) while groupby() hardcodes AgentSet

You are mistaken, both are using type(self)

should StrongAgentSet return weak refs from all methods, or should the base class use type(self) and StrongAgentSet override?)

See The main agenda for StrongAgentSet is performance and determinism, but we know that handling strong references manually creates a high risk of memory leaks for end-users.

The goal is that operations creating a "view" or "copy" of the data (like shuffle(inplace=False) or copy()) should default to returning a standard AgentSet (weak refs). This ensures that while the Model uses strong refs internally for stability, objects handed back to the user are "safe" by default and won't keep dead agents alive.

So yes StrongAgentSet will override them

quaquel · 2026-01-27T20:57:55Z

with the update to agent.py, there is now a conflict. I guess it has to do with deprecating sequence behavior on AgentSet. Can you take a look at the conflict and resolve it? I think this will be ready to be merged afterwards.

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

codebreaker32 · 2026-01-28T07:47:42Z

Can you take a look at the conflict and resolve it?

Done.

Add AbstractAgentSet to agent.py and make AgentSet inherit from it

3a23006

codebreaker32 force-pushed the refactor/agentset#1 branch from c4f36e1 to c75459b Compare January 26, 2026 07:09

codebreaker32 mentioned this pull request Jan 26, 2026

Tracking Issue: AgentSet Refactoring and _HardKeyAgentSet Implementation using AbstractAgentSet #3209

Closed

4 tasks