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

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):
-    def __init__(self, unique_id, model, vision, movement):
-        super().__init__(unique_id, model)
+    """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:
@@ -46,7 +59,6 @@ class Citizen(EpsteinAgent):
 
     def __init__(
         self,
-        unique_id,
         model,
         vision,
         movement,
@@ -56,11 +68,13 @@ class Citizen(EpsteinAgent):
         threshold,
         arrest_prob_constant,
     ):
-        """
-        Create a new Citizen.
+        """Create a new Citizen.
+
         Args:
-            unique_id: unique int
             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
@@ -68,10 +82,10 @@ 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__(unique_id, model, vision, movement)
+        super().__init__(model, vision, movement)
         self.hardship = hardship
         self.regime_legitimacy = regime_legitimacy
         self.risk_aversion = risk_aversion
@@ -82,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
@@ -97,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
         )
@@ -109,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:
@@ -123,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:
@@ -144,15 +158,20 @@ class Cop(EpsteinAgent):
             able to inspect
     """
 
-    def __init__(self, unique_id, model, vision, movement, max_jail_term):
-        super().__init__(unique_id, model, vision, movement)
+    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:
@@ -166,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
         )
@@ -179,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
@@ -220,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")
@@ -236,7 +269,6 @@ class EpsteinCivilViolence(Model):
         for _, pos in self.grid.coord_iter():
             if self.random.random() < self.cop_density:
                 agent = Cop(
-                    self.next_id(),
                     self,
                     cop_vision,
                     movement,
@@ -244,7 +276,6 @@ class EpsteinCivilViolence(Model):
                 )
             elif self.random.random() < (self.cop_density + self.citizen_density):
                 agent = Citizen(
-                    self.next_id(),
                     self,
                     citizen_vision,
                     movement,
@@ -261,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__":
@@ -270,4 +302,4 @@ if __name__ == "__main__":
 
     simulator.setup(model)
 
-    simulator.run(time_delta=100)
+    simulator.run_for(time_delta=100)

mesa/experimental/devs/examples/wolf_sheep.py

@@ -1,36 +1,39 @@
-"""
-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):
-    def __init__(self, unique_id, model, moore, energy, p_reproduce, energy_from_food):
-        super().__init__(unique_id, model)
+    """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
         self.energy_from_food = energy_from_food
         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.next_id(),
             self.model,
             self.moore,
             self.energy,
@@ -39,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
 
@@ -58,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))
@@ -74,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:
@@ -90,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,15 +108,16 @@ class GrassPatch(mesa.Agent):
                 function_args=[self, "fully_grown", True],
             )
 
-    def __init__(self, unique_id, model, fully_grown, countdown, grass_regrowth_time):
-        """
-        Creates a new patch of grass
+    def __init__(self, model, fully_grown, countdown, grass_regrowth_time):
+        """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__(unique_id, model)
+        super().__init__(model)
         self._fully_grown = fully_grown
         self.grass_regrowth_time = grass_regrowth_time
 
@@ -126,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.
     """
@@ -152,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
@@ -165,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
@@ -191,7 +193,6 @@ class WolfSheep(mesa.Model):
             )
             energy = self.random.randrange(2 * sheep_gain_from_food)
             sheep = Sheep(
-                self.next_id(),
                 self,
                 moore,
                 energy,
@@ -208,7 +209,6 @@ class WolfSheep(mesa.Model):
             )
             energy = self.random.randrange(2 * wolf_gain_from_food)
             wolf = Wolf(
-                self.next_id(),
                 self,
                 moore,
                 energy,
@@ -225,14 +225,13 @@ class WolfSheep(mesa.Model):
                 countdown = grass_regrowth_time
             else:
                 countdown = self.random.randrange(grass_regrowth_time)
-            patch = GrassPatch(
-                self.next_id(), self, fully_grown, countdown, grass_regrowth_time
-            )
+            patch = GrassPatch(self, fully_grown, countdown, grass_regrowth_time)
             self.grid.place_agent(patch, pos)
 
     def step(self):
-        self.get_agents_of_type(Sheep).shuffle(inplace=True).do("step")
-        self.get_agents_of_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__":