Mesa 3.0.0a4__py3-none-any.whl → 3.0.0b0__py3-none-any.whl

mesa/time.py

@@ -1,6 +1,9 @@
-"""
-Mesa Time Module
-================
+"""Mesa Time Module.
+
+.. warning::
+    The time module and all its Schedulers are deprecated and will be removed in a future version.
+    They can be replaced with AgentSet functionality. See the migration guide for details:
+    https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers
 
 Objects for handling the time component of a model. In particular, this module
 contains Schedulers, which handle agent activation. A Scheduler is an object
@@ -39,23 +42,16 @@ TimeT = float | int
 
 
 class BaseScheduler:
-    """
-    A simple scheduler that activates agents one at a time, in the order they were added.
+    """A simple scheduler that activates agents one at a time, in the order they were added.
 
     This scheduler is designed to replicate the behavior of the scheduler in MASON, a multi-agent simulation toolkit.
     It assumes that each agent added has a `step` method which takes no arguments and executes the agent's actions.
 
     Attributes:
-        - model (Model): The model instance associated with the scheduler.
-        - steps (int): The number of steps the scheduler has taken.
-        - time (TimeT): The current time in the simulation. Can be an integer or a float.
-
-    Methods:
-        - add: Adds an agent to the scheduler.
-        - remove: Removes an agent from the scheduler.
-        - step: Executes a step, which involves activating each agent once.
-        - get_agent_count: Returns the number of agents in the scheduler.
-        - agents (property): Returns a list of all agent instances.
+        model (Model): The model instance associated with the scheduler.
+        steps (int): The number of steps the scheduler has taken.
+        time (TimeT): The current time in the simulation. Can be an integer or a float.
+
     """
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
@@ -66,6 +62,14 @@ class BaseScheduler:
             agents (Iterable[Agent], None, optional): An iterable of agents who are controlled by the schedule
 
         """
+        warnings.warn(
+            "The time module and all its Schedulers are deprecated and will be removed in a future version. "
+            "They can be replaced with AgentSet functionality. See the migration guide for details. "
+            "https://mesa.readthedocs.io/latest/migration_guide.html#time-and-schedulers",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         self.model = model
         self.steps = 0
         self.time: TimeT = 0
@@ -82,10 +86,8 @@ class BaseScheduler:
         """Add an Agent object to the schedule.
 
         Args:
-            agent: An Agent to be added to the schedule. NOTE: The agent must
-            have a step() method.
+            agent (Agent): An Agent to be added to the schedule.
         """
-
         if agent not in self._agents:
             self._agents.add(agent)
         else:
@@ -94,12 +96,13 @@ class BaseScheduler:
     def remove(self, agent: Agent) -> None:
         """Remove all instances of a given agent from the schedule.
 
+        Args:
+            agent: An `Agent` instance.
+
         Note:
             It is only necessary to explicitly remove agents from the schedule if
             the agent is not removed from the model.
 
-        Args:
-            agent: An agent object.
         """
         self._agents.remove(agent)
 
@@ -117,10 +120,12 @@ class BaseScheduler:
 
     @property
     def agents(self) -> AgentSet:
+        """Return agents in the scheduler."""
         # a bit dirty, but returns a copy of the internal agent set
         return self._agents.select()
 
     def get_agent_keys(self, shuffle: bool = False) -> list[int]:
+        """Deprecated."""
         # To be able to remove and/or add agents during stepping
         # it's necessary to cast the keys view to a list.
 
@@ -138,14 +143,21 @@ class BaseScheduler:
         return agent_keys
 
     def do_each(self, method, shuffle=False):
+        """Perform `method` on each agent.
+
+        Args:
+            method: method to call
+            shuffle: shuffle the agents or not prior to calling method
+
+
+        """
         if shuffle:
             self._agents.shuffle(inplace=True)
         self._agents.do(method)
 
 
 class RandomActivation(BaseScheduler):
-    """
-    A scheduler that activates each agent once per step, in a random order, with the order reshuffled each step.
+    """A scheduler that activates each agent once per step, in a random order, with the order reshuffled each step.
 
     This scheduler is equivalent to the NetLogo 'ask agents...' behavior and is a common default for ABMs.
     It assumes that all agents have a `step` method.
@@ -155,23 +167,17 @@ class RandomActivation(BaseScheduler):
 
     Inherits all attributes and methods from BaseScheduler.
 
-    Methods:
-        - step: Executes a step, activating each agent in a random order.
     """
 
     def step(self) -> None:
-        """Executes the step of all agents, one at a time, in
-        random order.
-
-        """
+        """Executes the step of all agents, one at a time, in random order."""
         self.do_each("step", shuffle=True)
         self.steps += 1
         self.time += 1
 
 
 class SimultaneousActivation(BaseScheduler):
-    """
-    A scheduler that simulates the simultaneous activation of all agents.
+    """A scheduler that simulates the simultaneous activation of all agents.
 
     This scheduler is unique in that it requires agents to have both `step` and `advance` methods.
     - The `step` method is for activating the agent and staging any changes without applying them immediately.
@@ -182,8 +188,6 @@ class SimultaneousActivation(BaseScheduler):
 
     Inherits all attributes and methods from BaseScheduler.
 
-    Methods:
-        - step: Executes a step for all agents, first calling `step` then `advance` on each.
     """
 
     def step(self) -> None:
@@ -198,9 +202,9 @@ class SimultaneousActivation(BaseScheduler):
 
 
 class StagedActivation(BaseScheduler):
-    """
-    A scheduler allowing agent activation to be divided into several stages, with all agents executing one stage
-    before moving on to the next. This class is a generalization of SimultaneousActivation.
+    """A scheduler allowing agent activation to be divided into several stages.
+
+    All agents executing one stage before moving on to the next. This class is a generalization of SimultaneousActivation.
 
     This scheduler is useful for complex models where actions need to be broken down into distinct phases
     for each agent in each time step. Agents must implement methods for each defined stage.
@@ -215,8 +219,6 @@ class StagedActivation(BaseScheduler):
         - shuffle (bool): Determines whether to shuffle the order of agents each step.
         - shuffle_between_stages (bool): Determines whether to shuffle agents between each stage.
 
-    Methods:
-        - step: Executes all the stages for all agents in the defined order.
     """
 
     def __init__(
@@ -261,8 +263,7 @@ class StagedActivation(BaseScheduler):
 
 
 class RandomActivationByType(BaseScheduler):
-    """
-    A scheduler that activates each type of agent once per step, in random order, with the order reshuffled every step.
+    """A scheduler that activates each type of agent once per step, in random order, with the order reshuffled every step.
 
     This scheduler is useful for models with multiple types of agents, ensuring that each type is treated
     equitably in terms of activation order. The randomness in activation order helps in reducing biases
@@ -278,14 +279,10 @@ class RandomActivationByType(BaseScheduler):
     Attributes:
         - agents_by_type (defaultdict): A dictionary mapping agent types to dictionaries of agents.
 
-    Methods:
-        - step: Executes the step of each agent type in a random order.
-        - step_type: Activates all agents of a given type.
-        - get_type_count: Returns the count of agents of a specific type.
     """
 
     @property
-    def agents_by_type(self):
+    def agents_by_type(self):  # noqa: D102
         warnings.warn(
             "Because of the shift to using AgentSet, in the future this attribute will return a dict with"
             "type as key as AgentSet as value. Future behavior is available via RandomActivationByType._agents_by_type",
@@ -300,14 +297,13 @@ class RandomActivationByType(BaseScheduler):
         return agentsbytype
 
     def __init__(self, model: Model, agents: Iterable[Agent] | None = None) -> None:
-        super().__init__(model, agents)
-        """
+        """Initialize RandomActivationByType instance.
 
         Args:
             model (Model): The model to which the schedule belongs
             agents (Iterable[Agent], None, optional): An iterable of agents who are controlled by the schedule
         """
-
+        super().__init__(model, agents)
         # can't be a defaultdict because we need to pass model to AgentSet
         self._agents_by_type: [type, AgentSet] = {}
 
@@ -319,8 +315,7 @@ class RandomActivationByType(BaseScheduler):
                     self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
 
     def add(self, agent: Agent) -> None:
-        """
-        Add an Agent object to the schedule
+        """Add an Agent object to the schedule.
 
         Args:
             agent: An Agent to be added to the schedule.
@@ -333,21 +328,21 @@ class RandomActivationByType(BaseScheduler):
             self._agents_by_type[type(agent)] = AgentSet([agent], self.model)
 
     def remove(self, agent: Agent) -> None:
-        """
-        Remove all instances of a given agent from the schedule.
+        """Remove all instances of a given agent from the schedule.
+
+        Args:
+            agent: An Agent to be removed from the schedule.
+
         """
         super().remove(agent)
         self._agents_by_type[type(agent)].remove(agent)
 
     def step(self, shuffle_types: bool = True, shuffle_agents: bool = True) -> None:
-        """
-        Executes the step of each agent type, one at a time, in random order.
+        """Executes the step of each agent type, one at a time, in random order.
 
         Args:
-            shuffle_types: If True, the order of execution of each types is
-                           shuffled.
-            shuffle_agents: If True, the order of execution of each agents in a
-                            type group is shuffled.
+            shuffle_types: If True, the order of execution of each types is shuffled.
+            shuffle_agents: If True, the order of execution of each agents in a type group is shuffled.
         """
         # To be able to remove and/or add agents during stepping
         # it's necessary to cast the keys view to a list.
@@ -360,12 +355,11 @@ class RandomActivationByType(BaseScheduler):
         self.time += 1
 
     def step_type(self, agenttype: type[Agent], shuffle_agents: bool = True) -> None:
-        """
-        Shuffle order and run all agents of a given type.
-        This method is equivalent to the NetLogo 'ask [breed]...'.
+        """Shuffle order and run all agents of a given type.
 
         Args:
             agenttype: Class object of the type to run.
+            shuffle_agents: If True, shuffle agents
         """
         agents = self._agents_by_type[agenttype]
 
@@ -374,19 +368,15 @@ class RandomActivationByType(BaseScheduler):
         agents.do("step")
 
     def get_type_count(self, agenttype: type[Agent]) -> int:
-        """
-        Returns the current number of agents of certain type in the queue.
-        """
+        """Returns the current number of agents of certain type in the queue."""
         return len(self._agents_by_type[agenttype])
 
 
 class DiscreteEventScheduler(BaseScheduler):
-    """
-    This class has been deprecated and replaced by the functionality provided by experimental.devs
-    """
+    """This class has been deprecated and replaced by the functionality provided by experimental.devs."""
 
     def __init__(self, model: Model, time_step: TimeT = 1) -> None:
-        """
+        """Initialize DiscreteEventScheduler.
 
         Args:
             model (Model): The model to which the schedule belongs

mesa/visualization/UserParam.py

@@ -1,7 +1,12 @@
+"""Solara visualization related helper classes."""
+
+
 class UserParam:
+    """UserParam."""
+
     _ERROR_MESSAGE = "Missing or malformed inputs for '{}' Option '{}'"
 
-    def maybe_raise_error(self, param_type, valid):
+    def maybe_raise_error(self, param_type, valid):  # noqa: D102
         if valid:
             return
         msg = self._ERROR_MESSAGE.format(param_type, self.label)
@@ -9,11 +14,9 @@ class UserParam:
 
 
 class Slider(UserParam):
-    """
-    A number-based slider input with settable increment.
+    """A number-based slider input with settable increment.
 
     Example:
-
     slider_option = Slider("My Slider", value=123, min=10, max=200, step=0.1)
 
     Args:
@@ -34,6 +37,16 @@ class Slider(UserParam):
         step=1,
         dtype=None,
     ):
+        """Initializes a slider.
+
+        Args:
+            label: The displayed label in the UI
+            value: The initial value of the slider
+            min: The minimum possible value of the slider
+            max: The maximum possible value of the slider
+            step: The step between min and max for a range of possible values
+            dtype: either int or float
+        """
         self.label = label
         self.value = value
         self.min = min
@@ -49,8 +62,8 @@ class Slider(UserParam):
         else:
             self.is_float_slider = dtype is float
 
-    def _check_values_are_float(self, value, min, max, step):
+    def _check_values_are_float(self, value, min, max, step):  # D103
         return any(isinstance(n, float) for n in (value, min, max, step))
 
-    def get(self, attr):
+    def get(self, attr):  # noqa: D102
         return getattr(self, attr)

mesa/visualization/__init__.py

@@ -1,12 +1,13 @@
+"""Solara based visualization for Mesa models."""
+
 from .components.altair import make_space_altair
 from .components.matplotlib import make_plot_measure, make_space_matplotlib
-from .solara_viz import JupyterViz, SolaraViz, make_text
+from .solara_viz import JupyterViz, SolaraViz
 from .UserParam import Slider
 
 __all__ = [
     "JupyterViz",
     "SolaraViz",
-    "make_text",
     "Slider",
     "make_space_altair",
     "make_space_matplotlib",

mesa/visualization/components/altair.py

@@ -1,3 +1,5 @@
+"""Altair based solara components for visualization mesa spaces."""
+
 import contextlib
 
 import solara
@@ -8,7 +10,7 @@ with contextlib.suppress(ImportError):
 from mesa.visualization.utils import update_counter
 
 
-def make_space_altair(agent_portrayal=None):
+def make_space_altair(agent_portrayal=None):  # noqa: D103
     if agent_portrayal is None:
 
         def agent_portrayal(a):
@@ -21,7 +23,7 @@ def make_space_altair(agent_portrayal=None):
 
 
 @solara.component
-def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):  # noqa: D103
     update_counter.get()
     space = getattr(model, "grid", None)
     if space is None: