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

mesa/experimental/devs/simulator.py

@@ -1,3 +1,10 @@
+"""Provides several simulator classes.
+
+A Simulator is responsible for executing a simulation model. It controls time advancement and enables event scheduling.
+
+
+"""
+
 from __future__ import annotations
 
 import numbers
@@ -27,6 +34,12 @@ class Simulator:
     # TODO: add experimentation support
 
     def __init__(self, time_unit: type, start_time: int | float):
+        """Initialize a Simulator instance.
+
+        Args:
+            time_unit: type of the smulaiton time
+            start_time: the starttime of the simulator
+        """
         # should model run in a separate thread,
         # and we can then interact with start, stop, run_until, and step?
         self.event_list = EventList()
@@ -36,10 +49,10 @@ class Simulator:
         self.time = self.start_time
         self.model = None
 
-    def check_time_unit(self, time: int | float) -> bool: ...
+    def check_time_unit(self, time: int | float) -> bool: ...  # noqa: D102
 
     def setup(self, model: Model) -> None:
-        """Set up the simulator with the model to simulate
+        """Set up the simulator with the model to simulate.
 
         Args:
             model (Model): The model to simulate
@@ -49,12 +62,13 @@ class Simulator:
         self.model = model
 
     def reset(self):
-        """Reset the simulator by clearing the event list and removing the model to simulate"""
+        """Reset the simulator by clearing the event list and removing the model to simulate."""
         self.event_list.clear()
         self.model = None
         self.time = self.start_time
 
     def run_until(self, end_time: int | float) -> None:
+        """Run the simulator until the end time."""
         while True:
             try:
                 event = self.event_list.pop_event()
@@ -71,7 +85,7 @@ class Simulator:
                 break
 
     def run_for(self, time_delta: int | float):
-        """run the simulator for the specified time delta
+        """Run the simulator for the specified time delta.
 
         Args:
             time_delta (float| int): The time delta. The simulator is run from the current time to the current time
@@ -88,7 +102,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the current time instant
+        """Schedule event for the current time instant.
 
         Args:
             function (Callable): The callable to execute for this event
@@ -116,7 +130,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the specified time instant
+        """Schedule event for the specified time instant.
 
         Args:
             function (Callable): The callable to execute for this event
@@ -150,7 +164,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the current time plus the time delta
+        """Schedule event for the current time plus the time delta.
 
         Args:
             function (Callable): The callable to execute for this event
@@ -174,13 +188,12 @@ class Simulator:
         return event
 
     def cancel_event(self, event: SimulationEvent) -> None:
-        """remove the event from the event list
+        """Remove the event from the event list.
 
         Args:
             event (SimulationEvent): The simulation event to remove
 
         """
-
         self.event_list.remove(event)
 
     def _schedule_event(self, event: SimulationEvent):
@@ -204,13 +217,29 @@ class ABMSimulator(Simulator):
     """
 
     def __init__(self):
+        """Initialize a ABM simulator."""
         super().__init__(int, 0)
 
     def setup(self, model):
+        """Set up the simulator with the model to simulate.
+
+        Args:
+            model (Model): The model to simulate
+
+        """
         super().setup(model)
         self.schedule_event_now(self.model.step, priority=Priority.HIGH)
 
     def check_time_unit(self, time) -> bool:
+        """Check whether the time is of the correct unit.
+
+        Args:
+            time (int | float): the time
+
+        Returns:
+            bool: whether the time is of the correct unit
+
+        """
         if isinstance(time, int):
             return True
         if isinstance(time, float):
@@ -225,9 +254,9 @@ class ABMSimulator(Simulator):
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule a SimulationEvent for the next tick
+        """Schedule a SimulationEvent for the next tick.
 
-        Args
+        Args:
             function (Callable): the callable to execute
             priority (Priority): the priority of the event
             function_args (List[Any]): List of arguments to pass to the callable
@@ -243,7 +272,7 @@ class ABMSimulator(Simulator):
         )
 
     def run_until(self, end_time: int) -> None:
-        """run the simulator up to and included the specified end time
+        """Run the simulator up to and included the specified end time.
 
         Args:
             end_time (float| int): The end_time delta. The simulator is until the specified end time
@@ -270,7 +299,7 @@ class ABMSimulator(Simulator):
                 break
 
     def run_for(self, time_delta: int):
-        """run the simulator for the specified time delta
+        """Run the simulator for the specified time delta.
 
         Args:
             time_delta (float| int): The time delta. The simulator is run from the current time to the current time
@@ -282,13 +311,24 @@ class ABMSimulator(Simulator):
 
 
 class DEVSimulator(Simulator):
-    """A simulator where the unit of time is a float. Can be used for full-blown discrete event simulating using
-    event scheduling.
+    """A simulator where the unit of time is a float.
+
+    Can be used for full-blown discrete event simulating using event scheduling.
 
     """
 
     def __init__(self):
+        """Initialize a DEVS simulator."""
         super().__init__(float, 0.0)
 
     def check_time_unit(self, time) -> bool:
+        """Check whether the time is of the correct unit.
+
+        Args:
+            time (float): the time
+
+        Returns:
+        bool: whether the time is of the correct unit
+
+        """
         return isinstance(time, numbers.Number)

mesa/experimental/solara_viz.py

@@ -1,5 +1,4 @@
-"""
-Mesa visualization module for creating interactive model visualizations.
+"""Mesa visualization module for creating interactive model visualizations.
 
 This module provides components to create browser- and Jupyter notebook-based visualizations of
 Mesa models, allowing users to watch models run step-by-step and interact with model parameters.
@@ -39,8 +38,7 @@ from mesa.experimental.UserParam import Slider
 def Card(
     model, measures, agent_portrayal, space_drawer, dependencies, color, layout_type
 ):
-    """
-    Create a card component for visualizing model space or measures.
+    """Create a card component for visualizing model space or measures.
 
     Args:
         model: The Mesa model instance
@@ -95,8 +93,7 @@ def SolaraViz(
     play_interval=150,
     seed=None,
 ):
-    """
-    Initialize a component to visualize a model.
+    """Initialize a component to visualize a model.
 
     Args:
         model_class: Class of the model to instantiate
@@ -212,8 +209,7 @@ JupyterViz = SolaraViz
 
 @solara.component
 def ModelController(model, play_interval, current_step, reset_counter):
-    """
-    Create controls for model execution (step, play, pause, reset).
+    """Create controls for model execution (step, play, pause, reset).
 
     Args:
         model: The model being visualized
@@ -315,8 +311,7 @@ def ModelController(model, play_interval, current_step, reset_counter):
 
 
 def split_model_params(model_params):
-    """
-    Split model parameters into user-adjustable and fixed parameters.
+    """Split model parameters into user-adjustable and fixed parameters.
 
     Args:
         model_params: Dictionary of all model parameters
@@ -335,8 +330,7 @@ def split_model_params(model_params):
 
 
 def check_param_is_fixed(param):
-    """
-    Check if a parameter is fixed (not user-adjustable).
+    """Check if a parameter is fixed (not user-adjustable).
 
     Args:
         param: Parameter to check
@@ -354,8 +348,8 @@ def check_param_is_fixed(param):
 
 @solara.component
 def UserInputs(user_params, on_change=None):
-    """
-    Initialize user inputs for configurable model parameters.
+    """Initialize user inputs for configurable model parameters.
+
     Currently supports :class:`solara.SliderInt`, :class:`solara.SliderFloat`,
     :class:`solara.Select`, and :class:`solara.Checkbox`.
 
@@ -364,7 +358,6 @@ def UserInputs(user_params, on_change=None):
         min and max values, and other fields specific to the input type.
         on_change: Function to be called with (name, value) when the value of an input changes.
     """
-
     for name, options in user_params.items():
 
         def change_handler(value, name=name):
@@ -423,8 +416,7 @@ def UserInputs(user_params, on_change=None):
 
 
 def make_text(renderer):
-    """
-    Create a function that renders text using Markdown.
+    """Create a function that renders text using Markdown.
 
     Args:
         renderer: Function that takes a model and returns a string
@@ -440,8 +432,7 @@ def make_text(renderer):
 
 
 def make_initial_grid_layout(layout_types):
-    """
-    Create an initial grid layout for visualization components.
+    """Create an initial grid layout for visualization components.
 
     Args:
         layout_types: List of layout types (Space or Measure)

mesa/main.py

@@ -1,3 +1,5 @@
+"""main module for running mesa models with a server."""
+
 import os
 import sys
 from pathlib import Path
@@ -19,13 +21,13 @@ CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
 
 @click.group(context_settings=CONTEXT_SETTINGS)
 def cli():
-    "Manage Mesa projects"
+    """Manage Mesa projects."""
 
 
 @cli.command()
 @click.argument("project", type=PROJECT_PATH, default=".")
 def runserver(project):
-    """Run mesa project PROJECT
+    """Run mesa project PROJECT.
 
     PROJECT is the path to the directory containing `run.py`, or the current
     directory if not specified.
@@ -45,7 +47,7 @@ def runserver(project):
     "--no-input", is_flag=True, help="Do not prompt user for custom mesa model input."
 )
 def startproject(no_input):
-    """Create a new mesa project"""
+    """Create a new mesa project."""
     args = ["cookiecutter", COOKIECUTTER_PATH]
     if no_input:
         args.append("--no-input")
@@ -54,7 +56,7 @@ def startproject(no_input):
 
 @click.command()
 def version():
-    """Show the version of mesa"""
+    """Show the version of mesa."""
     print(f"mesa {__version__}")
 
 

mesa/model.py

@@ -1,5 +1,4 @@
-"""
-The model class for Mesa framework.
+"""The model class for Mesa framework.
 
 Core Objects: Model
 """
@@ -28,24 +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.
-
-    Properties:
-        agents: An AgentSet containing all agents in the model
-        agent_types: A list of different agent types present in the model.
-        agents_by_type: A dictionary where the keys are agent types and the values are the corresponding AgentSets.
-        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.
-            Deprecated: Use agents_by_type[agenttype] instead.
-        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
@@ -54,29 +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
+        """
+        super().__init__(*args, **kwargs)
         self.running = True
-        self.schedule = None
         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,7 +72,7 @@ class Model:
         # Call the original user-defined step method
         self._user_step(*args, **kwargs)
 
-    def next_id(self) -> int:
+    def next_id(self) -> int:  # noqa: D102
         warnings.warn(
             "using model.next_id() is deprecated. Agents track their unique ID automatically",
             DeprecationWarning,
@@ -130,7 +114,7 @@ class Model:
         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[Agent], AgentSet
@@ -138,7 +122,7 @@ class Model:
         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.
@@ -175,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]
@@ -186,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()
@@ -201,7 +189,6 @@ class Model:
         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)
@@ -211,19 +198,29 @@ class Model:
         self,
         model_reporters=None,
         agent_reporters=None,
+        agenttype_reporters=None,
         tables=None,
     ) -> None:
-        if not hasattr(self, "schedule") or self.schedule is None:
-            raise RuntimeError(
-                "You must initialize the scheduler (self.schedule) before initializing the data collector."
-            )
-        if self.schedule.get_agent_count() == 0:
-            raise RuntimeError(
-                "You must add agents to the scheduler before initializing the data collector."
-            )
+        """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
+
+        """
+        warnings.warn(
+            "initialize_data_collector() is deprecated. Please use the DataCollector class directly. "
+            "by using `self.datacollector = DataCollector(...)`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         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.