Mesa 3.0.0__py3-none-any.whl → 3.0.0a0__py3-none-any.whl

mesa/experimental/cell_space/grid.py

@@ -1,5 +1,3 @@
-"""Various Grid Spaces."""
-
 from __future__ import annotations
 
 from collections.abc import Sequence
@@ -12,8 +10,8 @@ from mesa.experimental.cell_space import Cell, DiscreteSpace
 T = TypeVar("T", bound=Cell)
 
 
-class Grid(DiscreteSpace[T], Generic[T]):
-    """Base class for all grid classes.
+class Grid(DiscreteSpace, Generic[T]):
+    """Base class for all grid classes
 
     Attributes:
         dimensions (Sequence[int]): the dimensions of the grid
@@ -22,21 +20,8 @@ class Grid(DiscreteSpace[T], Generic[T]):
         random (Random): the random number generator
         _try_random (bool): whether to get empty cell be repeatedly trying random cell
 
-    Notes:
-        width and height are accessible via properties, higher dimensions can be retrieved via dimensions
-
     """
 
-    @property
-    def width(self) -> int:
-        """Convenience access to the width of the grid."""
-        return self.dimensions[0]
-
-    @property
-    def height(self) -> int:
-        """Convenience access to the height of the grid."""
-        return self.dimensions[1]
-
     def __init__(
         self,
         dimensions: Sequence[int],
@@ -45,15 +30,6 @@ class Grid(DiscreteSpace[T], Generic[T]):
         random: Random | None = None,
         cell_klass: type[T] = Cell,
     ) -> None:
-        """Initialise the grid class.
-
-        Args:
-            dimensions: the dimensions of the space
-            torus: whether the space wraps
-            capacity: capacity of the grid cell
-            random: a random number generator
-            cell_klass: the base class to use for the cells
-        """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
         self.torus = torus
         self.dimensions = dimensions
@@ -87,7 +63,7 @@ class Grid(DiscreteSpace[T], Generic[T]):
         if self.capacity is not None and not isinstance(self.capacity, float | int):
             raise ValueError("Capacity must be a number or None.")
 
-    def select_random_empty_cell(self) -> T:  # noqa
+    def select_random_empty_cell(self) -> T:
         # FIXME:: currently just a simple boolean to control behavior
         # FIXME:: basically if grid is close to 99% full, creating empty list can be faster
         # FIXME:: note however that the old results don't apply because in this implementation
@@ -113,7 +89,7 @@ class Grid(DiscreteSpace[T], Generic[T]):
             if self.torus:
                 n_coord = tuple(nc % d for nc, d in zip(n_coord, self.dimensions))
             if all(0 <= nc < d for nc, d in zip(n_coord, self.dimensions)):
-                cell.connect(self._cells[n_coord], d_coord)
+                cell.connect(self._cells[n_coord])
 
     def _connect_single_cell_2d(self, cell: T, offsets: list[tuple[int, int]]) -> None:
         i, j = cell.coordinate
@@ -124,7 +100,7 @@ class Grid(DiscreteSpace[T], Generic[T]):
             if self.torus:
                 ni, nj = ni % height, nj % width
             if 0 <= ni < height and 0 <= nj < width:
-                cell.connect(self._cells[ni, nj], (di, dj))
+                cell.connect(self._cells[ni, nj])
 
 
 class OrthogonalMooreGrid(Grid[T]):
@@ -146,6 +122,7 @@ class OrthogonalMooreGrid(Grid[T]):
             ( 1, -1), ( 1, 0), ( 1, 1),
         ]
         # fmt: on
+        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
@@ -177,12 +154,13 @@ class OrthogonalVonNeumannGrid(Grid[T]):
                     ( 1, 0),
         ]
         # fmt: on
+        height, width = self.dimensions
 
         for cell in self.all_cells:
             self._connect_single_cell_2d(cell, offsets)
 
     def _connect_cells_nd(self) -> None:
-        offsets: list[tuple[int, ...]] = []
+        offsets = []
         dimensions = len(self.dimensions)
         for dim in range(dimensions):
             for delta in [
@@ -198,8 +176,6 @@ class OrthogonalVonNeumannGrid(Grid[T]):
 
 
 class HexGrid(Grid[T]):
-    """A Grid with hexagonal tilling of the space."""
-
     def _connect_cells_2d(self) -> None:
         # fmt: off
         even_offsets = [

mesa/experimental/cell_space/network.py

@@ -1,5 +1,3 @@
-"""A Network grid."""
-
 from random import Random
 from typing import Any
 
@@ -7,8 +5,8 @@ from mesa.experimental.cell_space.cell import Cell
 from mesa.experimental.cell_space.discrete_space import DiscreteSpace
 
 
-class Network(DiscreteSpace[Cell]):
-    """A networked discrete space."""
+class Network(DiscreteSpace):
+    """A networked discrete space"""
 
     def __init__(
         self,
@@ -17,13 +15,13 @@ class Network(DiscreteSpace[Cell]):
         random: Random | None = None,
         cell_klass: type[Cell] = Cell,
     ) -> None:
-        """A Networked grid.
+        """A Networked grid
 
         Args:
             G: a NetworkX Graph instance.
             capacity (int) : the capacity of the cell
-            random (Random): a random number generator
-            cell_klass (type[Cell]): The base Cell class to use in the Network
+            random (Random):
+            CellKlass (type[Cell]): The base Cell class to use in the Network
 
         """
         super().__init__(capacity=capacity, random=random, cell_klass=cell_klass)
@@ -34,12 +32,9 @@ class Network(DiscreteSpace[Cell]):
                 node_id, capacity, random=self.random
             )
 
-        self._connect_cells()
-
-    def _connect_cells(self) -> None:
         for cell in self.all_cells:
             self._connect_single_cell(cell)
 
-    def _connect_single_cell(self, cell: Cell):
+    def _connect_single_cell(self, cell):
         for node_id in self.G.neighbors(cell.coordinate):
-            cell.connect(self._cells[node_id], node_id)
+            cell.connect(self._cells[node_id])

mesa/experimental/devs/__init__.py

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

mesa/experimental/devs/eventlist.py

@@ -1,5 +1,3 @@
-"""Eventlist which is at the core of event scheduling."""
-
 from __future__ import annotations
 
 import itertools
@@ -12,17 +10,15 @@ 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:
@@ -33,18 +29,12 @@ class SimulationEvent:
         function_args (list[Any]): Argument for the function
         function_kwargs (Dict[str, Any]): Keyword arguments for the function
 
-
-    Notes:
-        simulation events use a weak reference to the callable. Therefore, you cannot pass a lambda function in fn.
-        A simulation event where the callable no longer exists (e.g., because the agent has been removed from the model)
-        will fail silently.
-
     """
 
     _ids = itertools.count()
 
     @property
-    def CANCELED(self) -> bool:  # noqa: D102
+    def CANCELED(self) -> bool:
         return self._canceled
 
     def __init__(
@@ -55,15 +45,6 @@ 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()
@@ -83,20 +64,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):  # noqa
+    def __lt__(self, other):
         # Define a total ordering for events to be used by the heapq
         return (self.time, self.priority, self.unique_id) < (
             other.time,
@@ -106,31 +87,30 @@ 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
@@ -159,7 +139,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:
@@ -167,33 +147,16 @@ 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:  # noqa
+    def __contains__(self, event: SimulationEvent) -> bool:
         return event in self._events
 
-    def __len__(self) -> int:  # noqa
+    def __len__(self) -> int:
         return len(self._events)
 
-    def __repr__(self) -> str:
-        """Return a string representation of the event list."""
-        events_str = ", ".join(
-            [
-                f"Event(time={e.time}, priority={e.priority}, id={e.unique_id})"
-                for e in self._events
-                if not e.CANCELED
-            ]
-        )
-        return f"EventList([{events_str}])"
-
     def remove(self, event: SimulationEvent) -> None:
-        """Remove an event from the event list.
-
-        Args:
-            event (SimulationEvent): The event to be removed
-
-        """
+        """remove an event from the event list"""
         # 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
@@ -201,5 +164,4 @@ class EventList:
         event.cancel()
 
     def clear(self):
-        """Clear the event list."""
         self._events.clear()

mesa/experimental/devs/examples/epstein_civil_violence.py

@@ -1,5 +1,3 @@
-"""Epstein civil violence example using ABMSimulator."""
-
 import enum
 import math
 
@@ -9,32 +7,21 @@ 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)
+    def __init__(self, unique_id, model, vision, movement):
+        super().__init__(unique_id, 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:
@@ -59,6 +46,7 @@ class Citizen(EpsteinAgent):
 
     def __init__(
         self,
+        unique_id,
         model,
         vision,
         movement,
@@ -68,13 +56,11 @@ 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
@@ -82,10 +68,10 @@ class Citizen(EpsteinAgent):
             risk_aversion: Exogenous, drawn from U(0,1).
             threshold: if (grievance - (risk_aversion * arrest_probability)) >
                 threshold, go/remain Active
-            arrest_prob_constant : agent's assessment of arrest probability
-
+            vision: number of cells in each direction (N, S, E and W) that
+                agent can inspect. Exogenous.
         """
-        super().__init__(model, vision, movement)
+        super().__init__(unique_id, model, vision, movement)
         self.hardship = hardship
         self.regime_legitimacy = regime_legitimacy
         self.risk_aversion = risk_aversion
@@ -96,7 +82,9 @@ 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
@@ -109,7 +97,9 @@ 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
         )
@@ -119,7 +109,10 @@ 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:
@@ -130,25 +123,18 @@ 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:
@@ -158,20 +144,15 @@ class Cop(EpsteinAgent):
             able to inspect
     """
 
-    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)
+    def __init__(self, unique_id, model, vision, movement, max_jail_term):
+        super().__init__(unique_id, 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:
@@ -185,7 +166,9 @@ 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
         )
@@ -196,8 +179,9 @@ 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
@@ -236,23 +220,6 @@ 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")
@@ -269,6 +236,7 @@ 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,
@@ -276,6 +244,7 @@ class EpsteinCivilViolence(Model):
                 )
             elif self.random.random() < (self.cop_density + self.citizen_density):
                 agent = Citizen(
+                    self.next_id(),
                     self,
                     citizen_vision,
                     movement,
@@ -292,8 +261,7 @@ class EpsteinCivilViolence(Model):
         self.active_agents = self.agents
 
     def step(self):
-        """Run one step of the model."""
-        self.active_agents.shuffle_do("step")
+        self.active_agents.shuffle(inplace=True).do("step")
 
 
 if __name__ == "__main__":
@@ -302,4 +270,4 @@ if __name__ == "__main__":
 
     simulator.setup(model)
 
-    simulator.run_for(time_delta=100)
+    simulator.run(time_delta=100)