Mesa 3.0.0a3__py3-none-any.whl → 3.0.0a5__py3-none-any.whl

mesa/model.py

@@ -1,5 +1,4 @@
-"""
-The model class for Mesa framework.
+"""The model class for Mesa framework.
 
 Core Objects: Model
 """
@@ -28,23 +27,8 @@ class Model:
     Attributes:
         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.
-
-    Properties:
-        agents: An AgentSet containing all agents in the model
-        agent_types: A list of different agent types present in the model.
-        steps: An integer representing the number of steps the model has taken.
-               It increases automatically at the start of each step() call.
-
-    Methods:
-        get_agents_of_type: Returns an AgentSet of agents of the specified type.
-        run_model: Runs the model's simulation until a defined end condition is reached.
-        step: Executes a single step of the model's simulation process.
-        next_id: Generates and returns the next unique identifier for an agent.
-        reset_randomizer: Resets the model's random number generator with a new or existing seed.
-        initialize_data_collector: Sets up the data collector for the model, requiring an initialized scheduler and agents.
-        register_agent : register an agent with the model
-        deregister_agent : remove an agent from the model
+        steps: the number of times `model.step()` has been called.
+        random: a seeded random number generator.
 
     Notes:
         Model.agents returns the AgentSet containing all agents registered with the model. Changing
@@ -53,30 +37,30 @@ class Model:
 
     """
 
-    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
-        """Create a new model object and instantiate its RNG automatically."""
-        obj = object.__new__(cls)
-        obj._seed = kwargs.get("seed")
-        if obj._seed is None:
-            # We explicitly specify the seed here so that we know its value in
-            # advance.
-            obj._seed = random.random()
-        obj.random = random.Random(obj._seed)
-        return obj
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """Create a new model. Overload this method with the actual code to
-        start the model. Always start with super().__init__() to initialize the
-        model object properly.
-        """
+    def __init__(self, *args: Any, seed: float | None = None, **kwargs: Any) -> None:
+        """Create a new model.
 
+        Overload this method with the actual code to initialize the model. Always start with super().__init__()
+        to initialize the model object properly.
+
+        Args:
+            args: arguments to pass onto super
+            seed: the seed for the random number generator
+            kwargs: keyword arguments to pass onto super
+        """
         self.running = True
         self.schedule = None
-        self.current_id = 0
         self.steps: int = 0
 
         self._setup_agent_registration()
 
+        self._seed = seed
+        if self._seed is None:
+            # We explicitly specify the seed here so that we know its value in
+            # advance.
+            self._seed = random.random()
+        self.random = random.Random(self._seed)
+
         # Wrap the user-defined step method
         self._user_step = self.step
         self.step = self._wrapped_step
@@ -88,6 +72,14 @@ class Model:
         # Call the original user-defined step method
         self._user_step(*args, **kwargs)
 
+    def next_id(self) -> int:  # noqa: D102
+        warnings.warn(
+            "using model.next_id() is deprecated. Agents track their unique ID automatically",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return 0
+
     @property
     def agents(self) -> AgentSet:
         """Provides an AgentSet of all agents in the model, combining agents from all types."""
@@ -106,29 +98,31 @@ class Model:
         """Return a list of all unique agent types registered with the model."""
         return list(self._agents_by_type.keys())
 
-    def get_agents_of_type(self, agenttype: type[Agent]) -> AgentSet:
-        """Retrieves an AgentSet containing all agents of the specified type.
-
-        Args:
-            agenttype: The type of agent to retrieve.
-
-        Raises:
-            KeyError: If agenttype does not exist
-
+    @property
+    def agents_by_type(self) -> dict[type[Agent], AgentSet]:
+        """A dictionary where the keys are agent types and the values are the corresponding AgentSets."""
+        return self._agents_by_type
 
-        """
-        return self._agents_by_type[agenttype]
+    def get_agents_of_type(self, agenttype: type[Agent]) -> AgentSet:
+        """Deprecated: Retrieves an AgentSet containing all agents of the specified type."""
+        warnings.warn(
+            f"Model.get_agents_of_type() is deprecated, please replace get_agents_of_type({agenttype})"
+            f"with the property agents_by_type[{agenttype}].",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.agents_by_type[agenttype]
 
     def _setup_agent_registration(self):
-        """helper method to initialize the agent registration datastructures"""
+        """Helper method to initialize the agent registration datastructures."""
         self._agents = {}  # the hard references to all agents in the model
         self._agents_by_type: dict[
-            type, AgentSet
+            type[Agent], AgentSet
         ] = {}  # a dict with an agentset for each class of agents
         self._all_agents = AgentSet([], self)  # an agenset with all agents
 
     def register_agent(self, agent):
-        """Register the agent with the model
+        """Register the agent with the model.
 
         Args:
             agent: The agent to register.
@@ -165,10 +159,13 @@ class Model:
         self._all_agents.add(agent)
 
     def deregister_agent(self, agent):
-        """Deregister the agent with the model
+        """Deregister the agent with the model.
+
+        Args:
+            agent: The agent to deregister.
 
-        Notes::
-        This method is called automatically by ``Agent.remove``
+        Notes:
+            This method is called automatically by ``Agent.remove``
 
         """
         del self._agents[agent]
@@ -176,8 +173,9 @@ class Model:
         self._all_agents.remove(agent)
 
     def run_model(self) -> None:
-        """Run the model until the end condition is reached. Overload as
-        needed.
+        """Run the model until the end condition is reached.
+
+        Overload as needed.
         """
         while self.running:
             self.step()
@@ -185,18 +183,12 @@ class Model:
     def step(self) -> None:
         """A single step. Fill in here."""
 
-    def next_id(self) -> int:
-        """Return the next unique ID for agents, increment current_id"""
-        self.current_id += 1
-        return self.current_id
-
     def reset_randomizer(self, seed: int | None = None) -> None:
         """Reset the model random number generator.
 
         Args:
             seed: A new seed for the RNG; if None, reset using the current seed
         """
-
         if seed is None:
             seed = self._seed
         self.random.seed(seed)
@@ -206,8 +198,18 @@ class Model:
         self,
         model_reporters=None,
         agent_reporters=None,
+        agenttype_reporters=None,
         tables=None,
     ) -> None:
+        """Initialize the data collector for the model.
+
+        Args:
+            model_reporters: model reporters to collect
+            agent_reporters: agent reporters to collect
+            agenttype_reporters: agent type reporters to collect
+            tables: tables to collect
+
+        """
         if not hasattr(self, "schedule") or self.schedule is None:
             raise RuntimeError(
                 "You must initialize the scheduler (self.schedule) before initializing the data collector."
@@ -219,6 +221,7 @@ class Model:
         self.datacollector = DataCollector(
             model_reporters=model_reporters,
             agent_reporters=agent_reporters,
+            agenttype_reporters=agenttype_reporters,
             tables=tables,
         )
         # Collect data for the first time during initialization.