model.agents: Store agents in nested dict keys

This commit introduces dics nested into a single defaultdict for agent storage, using agent instances as inner keys and None as inner values. The decision is based on:

1. Determinism: A dictionary ensures deterministic behavior for reproducible research outcomes.
2. Performance: Benchmarks showed that dictionaries offer a good balance between performance and functionality, especially in models with frequent agent updates.
3. Usability and Explicitness: While the use of None values is unconventional, this approach is practical and avoids the complexity of nested structures or external dependencies. It aligns with clear and explicit coding practices, making the framework more accessible and maintainable.

The choice of a defaultdict with None values addresses the need for deterministic behavior, performance efficiency, and clarity in implementation. Additional utility functions like `select_agents()` will be added to enhance usability.

Discussion for historical reference: projectmesa#1894 (comment)

mesa/agent.py

@@ -42,11 +42,11 @@ def __init__(self, unique_id: int, model: Model) -> None:
         self.pos: Position | None = None
 
         # Register the agent with the model using defaultdict
-        self.model.agents[type(self)].append(self)
+        self.model.agents[type(self)][self] = None
 
     def remove(self) -> None:
         """Remove and delete the agent from the model."""
-        self.model.agents[type(self)].remove(self)
+        self.model.agents[type(self)].pop(self)
 
     def step(self) -> None:
         """A single step of the agent."""

mesa/model.py

@@ -27,7 +27,8 @@ class Model:
         running: A boolean indicating if the model should continue running.
         schedule: An object to manage the order and execution of agent steps.
         current_id: A counter for assigning unique IDs to agents.
-        agents: A defaultdict mapping each agent type to a list of its instances.
+        agents: A defaultdict mapping each agent type to a dict of its instances.
+                Agent instances are saved in the nested dict keys, with the values being None.
     """
 
     def __new__(cls, *args: Any, **kwargs: Any) -> Any:
@@ -50,7 +51,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.running = True
         self.schedule = None
         self.current_id = 0
-        self.agents: defaultdict[type, list] = defaultdict(list)
+        self.agents: defaultdict[type, dict] = defaultdict(dict)
 
     @property
     def agent_types(self) -> list: