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

mesa/space.py

@@ -1,16 +1,24 @@
-"""
-Mesa Space Module
-=================
+"""Mesa Space Module.
 
 Objects used to add a spatial component to a model.
 
-Grid: base grid, which creates a rectangular grid.
-SingleGrid: extension to Grid which strictly enforces one agent per cell.
-MultiGrid: extension to Grid where each cell can contain a set of agents.
-HexGrid: extension to Grid to handle hexagonal neighbors.
-ContinuousSpace: a two-dimensional space where each agent has an arbitrary
-                 position of `float`'s.
-NetworkGrid: a network where each node contains zero or more agents.
+.. note::
+    All Grid classes (:class:`_Grid`, :class:`SingleGrid`, :class:`MultiGrid`,
+    :class:`HexGrid`, etc.) are now in maintenance-only mode. While these classes remain
+    fully supported, new development occurs in the experimental cell space module
+    (:mod:`mesa.experimental.cell_space`).
+
+    The :class:`PropertyLayer` and :class:`ContinuousSpace` classes remain fully supported
+    and actively developed.
+
+Classes
+-------
+* PropertyLayer: A data layer that can be added to Grids to store cell properties
+* SingleGrid: a Grid which strictly enforces one agent per cell.
+* MultiGrid: a Grid where each cell can contain a set of agents.
+* HexGrid: a Grid to handle hexagonal neighbors.
+* ContinuousSpace: a two-dimensional space where each agent has an arbitrary position of `float`'s.
+* NetworkGrid: a network where each node contains zero or more agents.
 """
 
 # Mypy; for the `|` operator purpose
@@ -23,9 +31,9 @@ import inspect
 import itertools
 import math
 import warnings
-from collections.abc import Iterable, Iterator, Sequence
+from collections.abc import Callable, Iterable, Iterator, Sequence
 from numbers import Real
-from typing import Any, Callable, TypeVar, Union, cast, overload
+from typing import Any, TypeVar, cast, overload
 from warnings import warn
 
 with contextlib.suppress(ImportError):
@@ -35,28 +43,29 @@ import numpy as np
 import numpy.typing as npt
 
 # For Mypy
-from .agent import Agent
+from .agent import Agent, AgentSet
 
 # for better performance, we calculate the tuple to use in the is_integer function
 _types_integer = (int, np.integer)
 
 Coordinate = tuple[int, int]
 # used in ContinuousSpace
-FloatCoordinate = Union[tuple[float, float], npt.NDArray[float]]
+FloatCoordinate = tuple[float, float] | npt.NDArray[float]
 NetworkCoordinate = int
 
-Position = Union[Coordinate, FloatCoordinate, NetworkCoordinate]
+Position = Coordinate | FloatCoordinate | NetworkCoordinate
 
-GridContent = Union[Agent, None]
+GridContent = Agent | None
 MultiGridContent = list[Agent]
 
 F = TypeVar("F", bound=Callable[..., Any])
 
 
 def accept_tuple_argument(wrapped_function: F) -> F:
-    """Decorator to allow grid methods that take a list of (x, y) coord tuples
-    to also handle a single position, by automatically wrapping tuple in
-    single-item list rather than forcing user to do it."""
+    """Decorator to allow grid methods that take a list of (x, y) coord tuples to also handle a single position.
+
+    Tuples are wrapped in a single-item list rather than forcing user to do it.
+    """
 
     def wrapper(grid_instance, positions) -> Any:
         if len(positions) == 2 and not isinstance(positions[0], tuple):
@@ -67,11 +76,13 @@ def accept_tuple_argument(wrapped_function: F) -> F:
 
 
 def is_integer(x: Real) -> bool:
-    # Check if x is either a CPython integer or Numpy integer.
+    """Check if x is either a CPython integer or Numpy integer."""
     return isinstance(x, _types_integer)
 
 
 def warn_if_agent_has_position_already(placement_func):
+    """Decorator to give warning if agent has position already set."""
+
     def wrapper(self, agent, *args, **kwargs):
         if agent.pos is not None:
             warnings.warn(
@@ -102,7 +113,8 @@ class _Grid:
         """Create a new grid.
 
         Args:
-            width, height: The width and height of the grid
+            width: The grid's width.
+            height: The grid's height.
             torus: Boolean whether the grid wraps or not.
         """
         self.height = height
@@ -152,6 +164,26 @@ class _Grid:
     @overload
     def __getitem__(self, index: int | Sequence[Coordinate]) -> list[GridContent]: ...
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for entry in self:
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]  # noqa PLW2901
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @overload
     def __getitem__(
         self, index: tuple[int | slice, int | slice]
@@ -159,7 +191,6 @@ class _Grid:
 
     def __getitem__(self, index):
         """Access contents from the grid."""
-
         if isinstance(index, int):
             # grid[x]
             return self._grid[index]
@@ -192,8 +223,7 @@ class _Grid:
             return [cell for rows in self._grid[x] for cell in rows[y]]
 
     def __iter__(self) -> Iterator[GridContent]:
-        """Create an iterator that chains the rows of the grid together
-        as if it is one list:"""
+        """Create an iterator that chains the rows of the grid together as if it is one list."""
         return itertools.chain(*self._grid)
 
     def coord_iter(self) -> Iterator[tuple[GridContent, Coordinate]]:
@@ -209,8 +239,7 @@ class _Grid:
         include_center: bool = False,
         radius: int = 1,
     ) -> Iterator[Coordinate]:
-        """Return an iterator over cell coordinates that are in the
-        neighborhood of a certain point.
+        """Return an iterator over cell coordinates that are in the neighborhood of a certain point.
 
         Args:
             pos: Coordinate tuple for the neighborhood to get.
@@ -237,8 +266,7 @@ class _Grid:
         include_center: bool = False,
         radius: int = 1,
     ) -> Sequence[Coordinate]:
-        """Return a list of cells that are in the neighborhood of a
-        certain point.
+        """Return a list of cells that are in the neighborhood of a certain point.
 
         Args:
             pos: Coordinate tuple for the neighborhood to get.
@@ -381,8 +409,7 @@ class _Grid:
             return pos[0] % self.width, pos[1] % self.height
 
     def out_of_bounds(self, pos: Coordinate) -> bool:
-        """Determines whether position is off the grid, returns the out of
-        bounds coordinate."""
+        """Determines whether position is off the grid, returns the out of bounds coordinate."""
         x, y = pos
         return x < 0 or x >= self.width or y < 0 or y >= self.height
 
@@ -390,8 +417,7 @@ class _Grid:
     def iter_cell_list_contents(
         self, cell_list: Iterable[Coordinate]
     ) -> Iterator[Agent]:
-        """Returns an iterator of the agents contained in the cells identified
-        in `cell_list`; cells with empty content are excluded.
+        """Returns an iterator of the agents contained in the cells identified in `cell_list`; cells with empty content are excluded.
 
         Args:
             cell_list: Array-like of (x, y) tuples, or single tuple.
@@ -407,8 +433,7 @@ class _Grid:
 
     @accept_tuple_argument
     def get_cell_list_contents(self, cell_list: Iterable[Coordinate]) -> list[Agent]:
-        """Returns an iterator of the agents contained in the cells identified
-        in `cell_list`; cells with empty content are excluded.
+        """Returns an iterator of the agents contained in the cells identified in `cell_list`; cells with empty content are excluded.
 
         Args:
             cell_list: Array-like of (x, y) tuples, or single tuple.
@@ -441,8 +466,7 @@ class _Grid:
         selection: str = "random",
         handle_empty: str | None = None,
     ) -> None:
-        """
-        Move an agent to one of the given positions.
+        """Move an agent to one of the given positions.
 
         Args:
             agent: Agent object to move. Assumed to have its current location stored in a 'pos' tuple.
@@ -494,9 +518,7 @@ class _Grid:
             )
 
     def _distance_squared(self, pos1: Coordinate, pos2: Coordinate) -> float:
-        """
-        Calculate the squared Euclidean distance between two points for performance.
-        """
+        """Calculate the squared Euclidean distance between two points for performance."""
         # Use squared Euclidean distance to avoid sqrt operation
         dx, dy = abs(pos1[0] - pos2[0]), abs(pos1[1] - pos2[1])
         if self.torus:
@@ -505,7 +527,7 @@ class _Grid:
         return dx**2 + dy**2
 
     def swap_pos(self, agent_a: Agent, agent_b: Agent) -> None:
-        """Swap agents positions"""
+        """Swap agents positions."""
         agents_no_pos = []
         if (pos_a := agent_a.pos) is None:
             agents_no_pos.append(agent_a)
@@ -566,16 +588,16 @@ def is_single_argument_function(function):
     )
 
 
-def ufunc_requires_additional_input(ufunc):
+def ufunc_requires_additional_input(ufunc):  # noqa: D103
     # NumPy ufuncs have a 'nargs' attribute indicating the number of input arguments
     # For binary ufuncs (like np.add), nargs is 2
     return ufunc.nargs > 1
 
 
 class PropertyLayer:
-    """
-    A class representing a layer of properties in a two-dimensional grid. Each cell in the grid
-    can store a value of a specified data type.
+    """A class representing a layer of properties in a two-dimensional grid.
+
+    Each cell in the grid can store a value of a specified data type.
 
     Attributes:
         name (str): The name of the property layer.
@@ -583,13 +605,6 @@ class PropertyLayer:
         height (int): The height of the grid (number of rows).
         data (numpy.ndarray): A NumPy array representing the grid data.
 
-    Methods:
-        set_cell(position, value): Sets the value of a single cell.
-        set_cells(value, condition=None): Sets the values of multiple cells, optionally based on a condition.
-        modify_cell(position, operation, value): Modifies the value of a single cell using an operation.
-        modify_cells(operation, value, condition_function): Modifies the values of multiple cells using an operation.
-        select_cells(condition, return_list): Selects cells that meet a specified condition.
-        aggregate_property(operation): Performs an aggregate operation over all cells.
     """
 
     propertylayer_experimental_warning_given = False
@@ -597,8 +612,7 @@ class PropertyLayer:
     def __init__(
         self, name: str, width: int, height: int, default_value, dtype=np.float64
     ):
-        """
-        Initializes a new PropertyLayer instance.
+        """Initializes a new PropertyLayer instance.
 
         Args:
             name (str): The name of the property layer.
@@ -649,14 +663,11 @@ class PropertyLayer:
             self.__class__.propertylayer_experimental_warning_given = True
 
     def set_cell(self, position: Coordinate, value):
-        """
-        Update a single cell's value in-place.
-        """
+        """Update a single cell's value in-place."""
         self.data[position] = value
 
     def set_cells(self, value, condition=None):
-        """
-        Perform a batch update either on the entire grid or conditionally, in-place.
+        """Perform a batch update either on the entire grid or conditionally, in-place.
 
         Args:
             value: The value to be used for the update.
@@ -685,8 +696,8 @@ class PropertyLayer:
             np.copyto(self.data, value, where=condition_result)
 
     def modify_cell(self, position: Coordinate, operation, value=None):
-        """
-        Modify a single cell using an operation, which can be a lambda function or a NumPy ufunc.
+        """Modify a single cell using an operation, which can be a lambda function or a NumPy ufunc.
+
         If a NumPy ufunc is used, an additional value should be provided.
 
         Args:
@@ -707,8 +718,8 @@ class PropertyLayer:
             raise ValueError("Invalid operation or missing value for NumPy ufunc.")
 
     def modify_cells(self, operation, value=None, condition_function=None):
-        """
-        Modify cells using an operation, which can be a lambda function or a NumPy ufunc.
+        """Modify cells using an operation, which can be a lambda function or a NumPy ufunc.
+
         If a NumPy ufunc is used, an additional value should be provided.
 
         Args:
@@ -742,8 +753,7 @@ class PropertyLayer:
         self.data = np.where(condition_array, modified_data, self.data)
 
     def select_cells(self, condition, return_list=True):
-        """
-        Find cells that meet a specified condition using NumPy's boolean indexing, in-place.
+        """Find cells that meet a specified condition using NumPy's boolean indexing, in-place.
 
         Args:
             condition: A callable that returns a boolean array when applied to the data.
@@ -768,9 +778,9 @@ class PropertyLayer:
 
 
 class _PropertyGrid(_Grid):
-    """
-    A private subclass of _Grid that supports the addition of property layers, enabling
-    the representation and manipulation of additional data layers on the grid. This class is
+    """A private subclass of _Grid that supports the addition of property layers.
+
+    This enables the representation and manipulation of additional data layers on the grid. This class is
     intended for internal use within the Mesa framework and is currently utilized by SingleGrid
     and MultiGrid classes to provide enhanced grid functionality.
 
@@ -783,22 +793,15 @@ class _PropertyGrid(_Grid):
         properties (dict): A dictionary mapping property layer names to PropertyLayer instances.
         empty_mask (np.ndarray): A boolean array indicating empty cells on the grid.
 
-    Methods:
-        add_property_layer(property_layer): Adds a new property layer to the grid.
-        remove_property_layer(property_name): Removes a property layer from the grid by its name.
-        get_neighborhood_mask(pos, moore, include_center, radius): Generates a boolean mask of the neighborhood.
-        select_cells(conditions, extreme_values, masks, only_empty, return_list): Selects cells based on multiple conditions,
-            extreme values, masks, with an option to select only empty cells, returning either a list of coordinates or a mask.
-
-    Mask Usage:
-        Several methods in this class accept a mask as an input, which is a NumPy ndarray of boolean values. This mask
-        specifies the cells to be considered (True) or ignored (False) in operations. Users can create custom masks,
-        including neighborhood masks, to apply specific conditions or constraints. Additionally, methods that deal with
-        cell selection or agent movement can return either a list of cell coordinates or a mask, based on the 'return_list'
-        parameter. This flexibility allows for more nuanced control and customization of grid operations, catering to a wide
-        range of modeling requirements and scenarios.
-
-    Note:
+
+    Several methods in this class accept a mask as an input, which is a NumPy ndarray of boolean values. This mask
+    specifies the cells to be considered (True) or ignored (False) in operations. Users can create custom masks,
+    including neighborhood masks, to apply specific conditions or constraints. Additionally, methods that deal with
+    cell selection or agent movement can return either a list of cell coordinates or a mask, based on the 'return_list'
+    parameter. This flexibility allows for more nuanced control and customization of grid operations, catering to a wide
+    range of modeling requirements and scenarios.
+
+    Notes:
         This class is not intended for direct use in user models but is currently used by the SingleGrid and MultiGrid.
     """
 
@@ -809,8 +812,7 @@ class _PropertyGrid(_Grid):
         torus: bool,
         property_layers: None | PropertyLayer | list[PropertyLayer] = None,
     ):
-        """
-        Initializes a new _PropertyGrid instance with specified dimensions and optional property layers.
+        """Initializes a new _PropertyGrid instance with specified dimensions and optional property layers.
 
         Args:
             width (int): The width of the grid (number of columns).
@@ -839,15 +841,12 @@ class _PropertyGrid(_Grid):
 
     @property
     def empty_mask(self) -> np.ndarray:
-        """
-        Returns a boolean mask indicating empty cells on the grid.
-        """
+        """Returns a boolean mask indicating empty cells on the grid."""
         return self._empty_mask
 
     # Add and remove properties to the grid
     def add_property_layer(self, property_layer: PropertyLayer):
-        """
-        Adds a new property layer to the grid.
+        """Adds a new property layer to the grid.
 
         Args:
             property_layer (PropertyLayer): The PropertyLayer instance to be added to the grid.
@@ -865,8 +864,7 @@ class _PropertyGrid(_Grid):
         self.properties[property_layer.name] = property_layer
 
     def remove_property_layer(self, property_name: str):
-        """
-        Removes a property layer from the grid by its name.
+        """Removes a property layer from the grid by its name.
 
         Args:
             property_name (str): The name of the property layer to be removed.
@@ -881,8 +879,8 @@ class _PropertyGrid(_Grid):
     def get_neighborhood_mask(
         self, pos: Coordinate, moore: bool, include_center: bool, radius: int
     ) -> np.ndarray:
-        """
-        Generate a boolean mask representing the neighborhood.
+        """Generate a boolean mask representing the neighborhood.
+
         Helper method for select_cells_multi_properties() and move_agent_to_random_cell()
 
         Args:
@@ -910,8 +908,7 @@ class _PropertyGrid(_Grid):
         only_empty: bool = False,
         return_list: bool = True,
     ) -> list[Coordinate] | np.ndarray:
-        """
-        Select cells based on property conditions, extreme values, and/or masks, with an option to only select empty cells.
+        """Select cells based on property conditions, extreme values, and/or masks, with an option to only select empty cells.
 
         Args:
             conditions (dict): A dictionary where keys are property names and values are callables that return a boolean when applied.
@@ -1064,7 +1061,7 @@ class MultiGrid(_PropertyGrid):
             self._empty_mask[agent.pos] = False
         agent.pos = None
 
-    def iter_neighbors(
+    def iter_neighbors(  # noqa: D102
         self,
         pos: Coordinate,
         moore: bool,
@@ -1079,8 +1076,9 @@ class MultiGrid(_PropertyGrid):
     def iter_cell_list_contents(
         self, cell_list: Iterable[Coordinate]
     ) -> Iterator[Agent]:
-        """Returns an iterator of the agents contained in the cells identified
-        in `cell_list`; cells with empty content are excluded.
+        """Returns an iterator of the agents contained in the cells identified in `cell_list`.
+
+        Cells with empty content are excluded.
 
         Args:
             cell_list: Array-like of (x, y) tuples, or single tuple.
@@ -1118,9 +1116,9 @@ class _HexGrid:
     def get_neighborhood(
         self, pos: Coordinate, include_center: bool = False, radius: int = 1
     ) -> list[Coordinate]:
-        """Return a list of coordinates that are in the
-        neighborhood of a certain point. To calculate the neighborhood
-        for a HexGrid the parity of the x coordinate of the point is
+        """Return a list of coordinates that are in the neighborhood of a certain point.
+
+        To calculate the neighborhood for a HexGrid the parity of the x coordinate of the point is
         important, the neighborhood can be sketched as:
 
             Always: (0,-), (0,+)
@@ -1206,8 +1204,7 @@ class _HexGrid:
     def iter_neighborhood(
         self, pos: Coordinate, include_center: bool = False, radius: int = 1
     ) -> Iterator[Coordinate]:
-        """Return an iterator over cell coordinates that are in the
-        neighborhood of a certain point.
+        """Return an iterator over cell coordinates that are in the neighborhood of a certain point.
 
         Args:
             pos: Coordinate tuple for the neighborhood to get.
@@ -1257,8 +1254,7 @@ class _HexGrid:
 
 
 class HexSingleGrid(_HexGrid, SingleGrid):
-    """Hexagonal SingleGrid: a SingleGrid where neighbors are computed
-    according to a hexagonal tiling of the grid.
+    """Hexagonal SingleGrid: a SingleGrid where neighbors are computed according to a hexagonal tiling of the grid.
 
     Functions according to odd-q rules.
     See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
@@ -1274,8 +1270,7 @@ class HexSingleGrid(_HexGrid, SingleGrid):
 
 
 class HexMultiGrid(_HexGrid, MultiGrid):
-    """Hexagonal MultiGrid: a MultiGrid where neighbors are computed
-    according to a hexagonal tiling of the grid.
+    """Hexagonal MultiGrid: a MultiGrid where neighbors are computed according to a hexagonal tiling of the grid.
 
     Functions according to odd-q rules.
     See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
@@ -1292,30 +1287,6 @@ class HexMultiGrid(_HexGrid, MultiGrid):
     """
 
 
-class HexGrid(HexSingleGrid):
-    """Hexagonal Grid: a Grid where neighbors are computed
-    according to a hexagonal tiling of the grid.
-
-    Functions according to odd-q rules.
-    See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
-
-    Properties:
-        width, height: The grid's width and height.
-        torus: Boolean which determines whether to treat the grid as a torus.
-    """
-
-    def __init__(self, width: int, height: int, torus: bool) -> None:
-        super().__init__(width, height, torus)
-        warn(
-            (
-                "HexGrid is being deprecated; use instead HexSingleGrid or HexMultiGrid "
-                "depending on your use case."
-            ),
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
 class ContinuousSpace:
     """Continuous space where each agent can have an arbitrary position.
 
@@ -1341,11 +1312,13 @@ class ContinuousSpace:
         """Create a new continuous space.
 
         Args:
-            x_max, y_max: Maximum x and y coordinates for the space.
+            x_max: the maximum x-coordinate
+            y_max: the maximum y-coordinate.
             torus: Boolean for whether the edges loop around.
-            x_min, y_min: (default 0) If provided, set the minimum x and y
-                          coordinates for the space. Below them, values loop to
-                          the other edge (if torus=True) or raise an exception.
+            x_min: (default 0) If provided, set the minimum x -coordinate for the space. Below them, values loop to
+                  the other edge (if torus=True) or raise an exception.
+            y_min: (default 0) If provided, set the minimum y -coordinate for the space. Below them, values loop to
+                  the other edge (if torus=True) or raise an exception.
         """
         self.x_min = x_min
         self.x_max = x_max
@@ -1361,6 +1334,19 @@ class ContinuousSpace:
         self._index_to_agent: dict[int, Agent] = {}
         self._agent_to_index: dict[Agent, int | None] = {}
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = list(self._agent_to_index)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     def _build_agent_cache(self):
         """Cache agents positions to speed up neighbors calculations."""
         self._index_to_agent = {}
@@ -1448,11 +1434,13 @@ class ContinuousSpace:
         self, pos_1: FloatCoordinate, pos_2: FloatCoordinate
     ) -> FloatCoordinate:
         """Get the heading vector between two points, accounting for toroidal space.
+
         It is possible to calculate the heading angle by applying the atan2 function to the
         result.
 
         Args:
-            pos_1, pos_2: Coordinate tuples for both points.
+            pos_1: Coordinate tuples for both points.
+            pos_2: Coordinate tuples for both points.
         """
         one = np.array(pos_1)
         two = np.array(pos_2)
@@ -1478,7 +1466,8 @@ class ContinuousSpace:
         """Get the distance between two point, accounting for toroidal space.
 
         Args:
-            pos_1, pos_2: Coordinate tuples for both points.
+            pos_1: Coordinate tuples for point1.
+            pos_2: Coordinate tuples for point2.
         """
         x1, y1 = pos_1
         x2, y2 = pos_2
@@ -1525,12 +1514,33 @@ class NetworkGrid:
         """Create a new network.
 
         Args:
-            G: a NetworkX graph instance.
+            g: a NetworkX graph instance.
         """
         self.G = g
         for node_id in self.G.nodes:
             g.nodes[node_id]["agent"] = self.default_val()
 
+    @property
+    def agents(self) -> AgentSet:
+        """Return an AgentSet with the agents in the space."""
+        agents = []
+        for node_id in self.G.nodes:
+            entry = self.G.nodes[node_id]["agent"]
+            if not entry:
+                continue
+            if not isinstance(entry, list):
+                entry = [entry]
+            for agent in entry:
+                agents.append(agent)
+
+        # getting the rng is a bit hacky because old style spaces don't have the rng
+        try:
+            rng = agents[0].random
+        except IndexError:
+            # there are no agents in the space
+            rng = None
+        return AgentSet(agents, random=rng)
+
     @staticmethod
     def default_val() -> list:
         """Default value for a new node."""
@@ -1545,7 +1555,16 @@ class NetworkGrid:
     def get_neighborhood(
         self, node_id: int, include_center: bool = False, radius: int = 1
     ) -> list[int]:
-        """Get all adjacent nodes within a certain radius"""
+        """Get all adjacent nodes within a certain radius.
+
+        Args:
+            node_id: node id for which to get neighborhood
+            include_center: boolean to include node itself or not
+            radius: size of neighborhood
+
+        Returns:
+            a list
+        """
         if radius == 1:
             neighborhood = list(self.G.neighbors(node_id))
             if include_center:
@@ -1562,28 +1581,61 @@ class NetworkGrid:
     def get_neighbors(
         self, node_id: int, include_center: bool = False, radius: int = 1
     ) -> list[Agent]:
-        """Get all agents in adjacent nodes (within a certain radius)."""
+        """Get all agents in adjacent nodes (within a certain radius).
+
+        Args:
+            node_id: node id for which to get neighbors
+            include_center: whether to include node itself or not
+            radius: size of neighborhood in which to find neighbors
+
+        Returns:
+            list of agents in neighborhood.
+        """
         neighborhood = self.get_neighborhood(node_id, include_center, radius)
         return self.get_cell_list_contents(neighborhood)
 
     def move_agent(self, agent: Agent, node_id: int) -> None:
-        """Move an agent from its current node to a new node."""
+        """Move an agent from its current node to a new node.
+
+        Args:
+            agent: agent instance
+            node_id: id of node
+
+        """
         self.remove_agent(agent)
         self.place_agent(agent, node_id)
 
     def remove_agent(self, agent: Agent) -> None:
-        """Remove the agent from the network and set its pos attribute to None."""
+        """Remove the agent from the network and set its pos attribute to None.
+
+        Args:
+            agent: agent instance
+
+        """
         node_id = agent.pos
         self.G.nodes[node_id]["agent"].remove(agent)
         agent.pos = None
 
     def is_cell_empty(self, node_id: int) -> bool:
-        """Returns a bool of the contents of a cell."""
+        """Returns a bool of the contents of a cell.
+
+        Args:
+            node_id: id of node
+
+        """
         return self.G.nodes[node_id]["agent"] == self.default_val()
 
     def get_cell_list_contents(self, cell_list: list[int]) -> list[Agent]:
-        """Returns a list of the agents contained in the nodes identified
-        in `cell_list`; nodes with empty content are excluded.
+        """Returns a list of the agents contained in the nodes identified in `cell_list`.
+
+        Nodes with empty content are excluded.
+
+        Args:
+            cell_list: list of cell ids.
+
+        Returns:
+            list of the agents contained in the nodes identified in `cell_list`.
+
         """
         return list(self.iter_cell_list_contents(cell_list))
 
@@ -1592,8 +1644,16 @@ class NetworkGrid:
         return self.get_cell_list_contents(self.G)
 
     def iter_cell_list_contents(self, cell_list: list[int]) -> Iterator[Agent]:
-        """Returns an iterator of the agents contained in the nodes identified
-        in `cell_list`; nodes with empty content are excluded.
+        """Returns an iterator of the agents contained in the nodes identified in `cell_list`.
+
+        Nodes with empty content are excluded.
+
+        Args:
+            cell_list: list of cell ids.
+
+        Returns:
+            iterator of the agents contained in the nodes identified in `cell_list`.
+
         """
         return itertools.chain.from_iterable(
             self.G.nodes[node_id]["agent"]