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

mesa/experimental/components/altair.py

@@ -1,3 +1,5 @@
+"""Altair components."""
+
 import contextlib
 
 import solara
@@ -8,6 +10,14 @@ with contextlib.suppress(ImportError):
 
 @solara.component
 def SpaceAltair(model, agent_portrayal, dependencies: list[any] | None = None):
+    """A component that renders a Space using Altair.
+
+    Args:
+        model: a model instance
+        agent_portrayal: agent portray specification
+        dependencies: optional list of dependencies (currently not used)
+
+    """
     space = getattr(model, "grid", None)
     if space is None:
         # Sometimes the space is defined as model.space instead of model.grid

mesa/experimental/components/matplotlib.py

@@ -1,3 +1,5 @@
+"""Support for using matplotlib to draw spaces."""
+
 from collections import defaultdict
 
 import networkx as nx
@@ -11,6 +13,14 @@ from mesa.experimental.cell_space import VoronoiGrid
 
 @solara.component
 def SpaceMatplotlib(model, agent_portrayal, dependencies: list[any] | None = None):
+    """A component for rendering a space using Matplotlib.
+
+    Args:
+        model: a model instance
+        agent_portrayal: a specification of how to portray an agent.
+        dependencies: list of dependencies.
+
+    """
     space_fig = Figure()
     space_ax = space_fig.subplots()
     space = getattr(model, "grid", None)
@@ -205,6 +215,14 @@ def _draw_voronoi(space, space_ax, agent_portrayal):
 
 @solara.component
 def PlotMatplotlib(model, measure, dependencies: list[any] | None = None):
+    """A solara component for creating a matplotlib figure.
+
+    Args:
+        model: Model instance
+        measure: measure to plot
+        dependencies: list of additional dependencies
+
+    """
     fig = Figure()
     ax = fig.subplots()
     df = model.datacollector.get_model_vars_dataframe()

mesa/experimental/devs/__init__.py

@@ -1,3 +1,5 @@
+"""Support for event scheduling."""
+
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator
 

mesa/experimental/devs/eventlist.py

@@ -1,3 +1,5 @@
+"""Eventlist which is at the core of event scheduling."""
+
 from __future__ import annotations
 
 import itertools
@@ -10,15 +12,17 @@ from weakref import WeakMethod, ref
 
 
 class Priority(IntEnum):
+    """Enumeration of priority levels."""
+
     LOW = 10
     DEFAULT = 5
     HIGH = 1
 
 
 class SimulationEvent:
-    """A simulation event
+    """A simulation event.
 
-    the callable is wrapped using weakref, so there is no need to explicitly cancel event if e.g., an agent
+    The callable is wrapped using weakref, so there is no need to explicitly cancel event if e.g., an agent
     is removed from the simulation.
 
     Attributes:
@@ -34,7 +38,7 @@ class SimulationEvent:
     _ids = itertools.count()
 
     @property
-    def CANCELED(self) -> bool:
+    def CANCELED(self) -> bool:  # noqa: D102
         return self._canceled
 
     def __init__(
@@ -45,6 +49,15 @@ class SimulationEvent:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> None:
+        """Initialize a simulation event.
+
+        Args:
+            time: the instant of time of the simulation event
+            function: the callable to invoke
+            priority: the priority of the event
+            function_args: arguments for callable
+            function_kwargs: keyword arguments for the callable
+        """
         super().__init__()
         if not callable(function):
             raise Exception()
@@ -64,20 +77,20 @@ class SimulationEvent:
         self.function_kwargs = function_kwargs if function_kwargs else {}
 
     def execute(self):
-        """execute this event"""
+        """Execute this event."""
         if not self._canceled:
             fn = self.fn()
             if fn is not None:
                 fn(*self.function_args, **self.function_kwargs)
 
     def cancel(self) -> None:
-        """cancel this event"""
+        """Cancel this event."""
         self._canceled = True
         self.fn = None
         self.function_args = []
         self.function_kwargs = {}
 
-    def __lt__(self, other):
+    def __lt__(self, other):  # noqa
         # Define a total ordering for events to be used by the heapq
         return (self.time, self.priority, self.unique_id) < (
             other.time,
@@ -87,30 +100,31 @@ class SimulationEvent:
 
 
 class EventList:
-    """An event list
+    """An event list.
 
     This is a heap queue sorted list of events. Events are always removed from the left, so heapq is a performant and
     appropriate data structure. Events are sorted based on their time stamp, their priority, and their unique_id
     as a tie-breaker, guaranteeing a complete ordering.
 
+
     """
 
     def __init__(self):
+        """Initialize an event list."""
         self._events: list[SimulationEvent] = []
         heapify(self._events)
 
     def add_event(self, event: SimulationEvent):
-        """Add the event to the event list
+        """Add the event to the event list.
 
         Args:
             event (SimulationEvent): The event to be added
 
         """
-
         heappush(self._events, event)
 
     def peak_ahead(self, n: int = 1) -> list[SimulationEvent]:
-        """Look at the first n non-canceled event in the event list
+        """Look at the first n non-canceled event in the event list.
 
         Args:
             n (int): The number of events to look ahead
@@ -139,7 +153,7 @@ class EventList:
         return peek
 
     def pop_event(self) -> SimulationEvent:
-        """pop the first element from the event list"""
+        """Pop the first element from the event list."""
         while self._events:
             event = heappop(self._events)
             if not event.CANCELED:
@@ -147,16 +161,17 @@ class EventList:
         raise IndexError("Event list is empty")
 
     def is_empty(self) -> bool:
+        """Return whether the event list is empty."""
         return len(self) == 0
 
-    def __contains__(self, event: SimulationEvent) -> bool:
+    def __contains__(self, event: SimulationEvent) -> bool:  # noqa
         return event in self._events
 
-    def __len__(self) -> int:
+    def __len__(self) -> int:  # noqa
         return len(self._events)
 
     def __repr__(self) -> str:
-        """Return a string representation of the event list"""
+        """Return a string representation of the event list."""
         events_str = ", ".join(
             [
                 f"Event(time={e.time}, priority={e.priority}, id={e.unique_id})"
@@ -167,7 +182,12 @@ class EventList:
         return f"EventList([{events_str}])"
 
     def remove(self, event: SimulationEvent) -> None:
-        """remove an event from the event list"""
+        """Remove an event from the event list.
+
+        Args:
+            event (SimulationEvent): The event to be removed
+
+        """
         # we cannot simply remove items from _eventlist because this breaks
         # heap structure invariant. So, we use a form of lazy deletion.
         # SimEvents have a CANCELED flag that we set to True, while popping and peak_ahead
@@ -175,4 +195,5 @@ class EventList:
         event.cancel()
 
     def clear(self):
+        """Clear the event list."""
         self._events.clear()

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,23 @@
-"""
-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.cell_space import FixedAgent
 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 +25,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 +43,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 +64,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 +77,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:
@@ -88,13 +91,11 @@ class Wolf(Animal):
             sheep_to_eat.die()
 
 
-class GrassPatch(mesa.Agent):
-    """
-    A patch of grass that grows at a fixed rate and it is eaten by sheep
-    """
+class GrassPatch(FixedAgent):
+    """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 +110,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 +127,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 +152,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 +166,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 +230,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__":