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

mesa/experimental/devs/examples/epstein_civil_violence.py

@@ -1,3 +1,5 @@
+"""Epstein civil violence example using ABMSimulator."""
+
 import enum
 import math
 
@@ -7,21 +9,32 @@ from mesa.space import SingleGrid
 
 
 class EpsteinAgent(Agent):
+    """Epstein Agent."""
+
     def __init__(self, model, vision, movement):
+        """Initialize the agent.
+
+        Args:
+            model: a model instance
+            vision: size of neighborhood
+            movement: boolean whether agent can move or not
+        """
         super().__init__(model)
         self.vision = vision
         self.movement = movement
 
 
 class AgentState(enum.IntEnum):
+    """Agent states."""
+
     QUIESCENT = enum.auto()
     ARRESTED = enum.auto()
     ACTIVE = enum.auto()
 
 
 class Citizen(EpsteinAgent):
-    """
-    A member of the general population, may or may not be in active rebellion.
+    """A member of the general population, may or may not be in active rebellion.
+
     Summary of rule: If grievance - risk > threshold, rebel.
 
     Attributes:
@@ -55,10 +68,13 @@ class Citizen(EpsteinAgent):
         threshold,
         arrest_prob_constant,
     ):
-        """
-        Create a new Citizen.
+        """Create a new Citizen.
+
         Args:
             model : model instance
+            vision: number of cells in each direction (N, S, E and W) that
+                agent can inspect. Exogenous.
+            movement: whether agent can move or not
             hardship: Agent's 'perceived hardship (i.e., physical or economic
                 privation).' Exogenous, drawn from U(0,1).
             regime_legitimacy: Agent's perception of regime legitimacy, equal
@@ -66,8 +82,8 @@ class Citizen(EpsteinAgent):
             risk_aversion: Exogenous, drawn from U(0,1).
             threshold: if (grievance - (risk_aversion * arrest_probability)) >
                 threshold, go/remain Active
-            vision: number of cells in each direction (N, S, E and W) that
-                agent can inspect. Exogenous.
+            arrest_prob_constant : agent's assessment of arrest probability
+
         """
         super().__init__(model, vision, movement)
         self.hardship = hardship
@@ -80,9 +96,7 @@ class Citizen(EpsteinAgent):
         self.arrest_prob_constant = arrest_prob_constant
 
     def step(self):
-        """
-        Decide whether to activate, then move if applicable.
-        """
+        """Decide whether to activate, then move if applicable."""
         self.update_neighbors()
         self.update_estimated_arrest_probability()
         net_risk = self.risk_aversion * self.arrest_probability
@@ -95,9 +109,7 @@ class Citizen(EpsteinAgent):
             self.model.grid.move_agent(self, new_pos)
 
     def update_neighbors(self):
-        """
-        Look around and see who my neighbors are
-        """
+        """Look around and see who my neighbors are."""
         self.neighborhood = self.model.grid.get_neighborhood(
             self.pos, moore=True, radius=self.vision
         )
@@ -107,10 +119,7 @@ class Citizen(EpsteinAgent):
         ]
 
     def update_estimated_arrest_probability(self):
-        """
-        Based on the ratio of cops to actives in my neighborhood, estimate the
-        p(Arrest | I go active).
-        """
+        """Based on the ratio of cops to actives in my neighborhood, estimate the p(Arrest | I go active)."""
         cops_in_vision = len([c for c in self.neighbors if isinstance(c, Cop)])
         actives_in_vision = 1.0  # citizen counts herself
         for c in self.neighbors:
@@ -121,18 +130,25 @@ class Citizen(EpsteinAgent):
         )
 
     def sent_to_jail(self, value):
+        """Sent agent to jail.
+
+        Args:
+            value: duration of jail sentence
+
+        """
         self.model.active_agents.remove(self)
         self.condition = AgentState.ARRESTED
         self.model.simulator.schedule_event_relative(self.release_from_jail, value)
 
     def release_from_jail(self):
+        """Release agent from jail."""
         self.model.active_agents.add(self)
         self.condition = AgentState.QUIESCENT
 
 
 class Cop(EpsteinAgent):
-    """
-    A cop for life.  No defection.
+    """A cop for life.  No defection.
+
     Summary of rule: Inspect local vision and arrest a random active agent.
 
     Attributes:
@@ -143,14 +159,19 @@ class Cop(EpsteinAgent):
     """
 
     def __init__(self, model, vision, movement, max_jail_term):
+        """Initialize a Cop agent.
+
+        Args:
+            model: a model instance
+            vision: size of neighborhood
+            movement: whether agent can move or not
+            max_jail_term: maximum jail sentence
+        """
         super().__init__(model, vision, movement)
         self.max_jail_term = max_jail_term
 
     def step(self):
-        """
-        Inspect local vision and arrest a random active agent. Move if
-        applicable.
-        """
+        """Inspect local vision and arrest a random active agent. Move if applicable."""
         self.update_neighbors()
         active_neighbors = []
         for agent in self.neighbors:
@@ -164,9 +185,7 @@ class Cop(EpsteinAgent):
             self.model.grid.move_agent(self, new_pos)
 
     def update_neighbors(self):
-        """
-        Look around and see who my neighbors are.
-        """
+        """Look around and see who my neighbors are."""
         self.neighborhood = self.model.grid.get_neighborhood(
             self.pos, moore=True, radius=self.vision
         )
@@ -177,9 +196,8 @@ class Cop(EpsteinAgent):
 
 
 class EpsteinCivilViolence(Model):
-    """
-    Model 1 from "Modeling civil violence: An agent-based computational
-    approach," by Joshua Epstein.
+    """Model 1 from "Modeling civil violence: An agent-based computational approach," by Joshua Epstein.
+
     http://www.pnas.org/content/99/suppl_3/7243.full
     Attributes:
         height: grid height
@@ -218,6 +236,23 @@ class EpsteinCivilViolence(Model):
         max_iters=1000,
         seed=None,
     ):
+        """Initialize the Eppstein civil violence model.
+
+        Args:
+            width: the width of the grid
+            height: the height of the grid
+            citizen_density: density of citizens
+            cop_density: density of cops
+            citizen_vision: size of citizen vision
+            cop_vision: size of cop vision
+            legitimacy: perceived legitimacy
+            max_jail_term: maximum jail term
+            active_threshold: threshold for citizen to become active
+            arrest_prob_constant: arrest probability
+            movement: allow agent movement or not
+            max_iters: number of iterations
+            seed: seed for random number generator
+        """
         super().__init__(seed)
         if cop_density + citizen_density > 1:
             raise ValueError("Cop density + citizen density must be less than 1")
@@ -257,7 +292,8 @@ class EpsteinCivilViolence(Model):
         self.active_agents = self.agents
 
     def step(self):
-        self.active_agents.shuffle(inplace=True).do("step")
+        """Run one step of the model."""
+        self.active_agents.shuffle_do("step")
 
 
 if __name__ == "__main__":

mesa/experimental/devs/examples/wolf_sheep.py

@@ -1,20 +1,22 @@
-"""
-Wolf-Sheep Predation Model
-================================
-
-Replication of the model found in NetLogo:
-    Wilensky, U. (1997). NetLogo Wolf Sheep Predation model.
-    http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation.
-    Center for Connected Learning and Computer-Based Modeling,
-    Northwestern University, Evanston, IL.
-"""
+"""Example of using ABM simulator for Wolf-Sheep Predation Model."""
 
 import mesa
 from mesa.experimental.devs.simulator import ABMSimulator
 
 
 class Animal(mesa.Agent):
+    """Base Animal class."""
+
     def __init__(self, model, moore, energy, p_reproduce, energy_from_food):
+        """Initialize Animal instance.
+
+        Args:
+            model: a model instance
+            moore: using moore grid or not
+            energy: initial energy
+            p_reproduce: probability of reproduction
+            energy_from_food: energy gained from 1 unit of food
+        """
         super().__init__(model)
         self.energy = energy
         self.p_reproduce = p_reproduce
@@ -22,12 +24,14 @@ class Animal(mesa.Agent):
         self.moore = moore
 
     def random_move(self):
+        """Move to random neighboring cell."""
         next_moves = self.model.grid.get_neighborhood(self.pos, self.moore, True)
         next_move = self.random.choice(next_moves)
         # Now move:
         self.model.grid.move_agent(self, next_move)
 
     def spawn_offspring(self):
+        """Create offspring."""
         self.energy /= 2
         offspring = self.__class__(
             self.model,
@@ -38,13 +42,15 @@ class Animal(mesa.Agent):
         )
         self.model.grid.place_agent(offspring, self.pos)
 
-    def feed(self): ...
+    def feed(self): ...  # noqa: D102
 
     def die(self):
+        """Die."""
         self.model.grid.remove_agent(self)
         self.remove()
 
     def step(self):
+        """Execute one step of the agent."""
         self.random_move()
         self.energy -= 1
 
@@ -57,13 +63,10 @@ class Animal(mesa.Agent):
 
 
 class Sheep(Animal):
-    """
-    A sheep that walks around, reproduces (asexually) and gets eaten.
-
-    The init is the same as the RandomWalker.
-    """
+    """A sheep that walks around, reproduces (asexually) and gets eaten."""
 
     def feed(self):
+        """Eat grass and gain energy."""
         # If there is grass available, eat it
         agents = self.model.grid.get_cell_list_contents(self.pos)
         grass_patch = next(obj for obj in agents if isinstance(obj, GrassPatch))
@@ -73,11 +76,10 @@ class Sheep(Animal):
 
 
 class Wolf(Animal):
-    """
-    A wolf that walks around, reproduces (asexually) and eats sheep.
-    """
+    """A wolf that walks around, reproduces (asexually) and eats sheep."""
 
     def feed(self):
+        """Eat wolf and gain energy."""
         agents = self.model.grid.get_cell_list_contents(self.pos)
         sheep = [obj for obj in agents if isinstance(obj, Sheep)]
         if len(sheep) > 0:
@@ -89,12 +91,10 @@ class Wolf(Animal):
 
 
 class GrassPatch(mesa.Agent):
-    """
-    A patch of grass that grows at a fixed rate and it is eaten by sheep
-    """
+    """A patch of grass that grows at a fixed rate and it is eaten by sheep."""
 
     @property
-    def fully_grown(self) -> bool:
+    def fully_grown(self) -> bool:  # noqa: D102
         return self._fully_grown
 
     @fully_grown.setter
@@ -109,12 +109,13 @@ class GrassPatch(mesa.Agent):
             )
 
     def __init__(self, model, fully_grown, countdown, grass_regrowth_time):
-        """
-        Creates a new patch of grass
+        """Creates a new patch of grass.
 
         Args:
-            grown: (boolean) Whether the patch of grass is fully grown or not
+            model: a model instance
+            fully_grown: (boolean) Whether the patch of grass is fully grown or not
             countdown: Time for the patch of grass to be fully grown again
+            grass_regrowth_time: regrowth time for the grass
         """
         super().__init__(model)
         self._fully_grown = fully_grown
@@ -125,13 +126,12 @@ class GrassPatch(mesa.Agent):
                 setattr, countdown, function_args=[self, "fully_grown", True]
             )
 
-    def set_fully_grown(self):
+    def set_fully_grown(self):  # noqa
         self.fully_grown = True
 
 
 class WolfSheep(mesa.Model):
-    """
-    Wolf-Sheep Predation Model
+    """Wolf-Sheep Predation Model.
 
     A model for simulating wolf and sheep (predator-prey) ecosystem modelling.
     """
@@ -151,10 +151,11 @@ class WolfSheep(mesa.Model):
         simulator=None,
         seed=None,
     ):
-        """
-        Create a new Wolf-Sheep model with the given parameters.
+        """Create a new Wolf-Sheep model with the given parameters.
 
         Args:
+            height: height of the grid
+            width: width of the grid
             initial_sheep: Number of sheep to start with
             initial_wolves: Number of wolves to start with
             sheep_reproduce: Probability of each sheep reproducing each step
@@ -164,7 +165,9 @@ class WolfSheep(mesa.Model):
             grass_regrowth_time: How long it takes for a grass patch to regrow
                                  once it is eaten
             sheep_gain_from_food: Energy sheep gain from grass, if enabled.
-            moore:
+            moore: whether to use moore or von Neumann grid
+            simulator: Simulator to use for simulating wolf and sheep
+            seed: Random seed
         """
         super().__init__(seed=seed)
         # Set parameters
@@ -226,8 +229,9 @@ class WolfSheep(mesa.Model):
             self.grid.place_agent(patch, pos)
 
     def step(self):
-        self.agents_by_type[Sheep].shuffle(inplace=True).do("step")
-        self.agents_by_type[Wolf].shuffle(inplace=True).do("step")
+        """Perform one step of the model."""
+        self.agents_by_type[Sheep].shuffle_do("step")
+        self.agents_by_type[Wolf].shuffle_do("step")
 
 
 if __name__ == "__main__":

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)