Mesa 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

mesa/space.py

@@ -4,10 +4,13 @@ Mesa Space Module
 
 Objects used to add a spatial component to a model.
 
-Grid: base grid, a simple list-of-lists.
-SingleGrid: grid which strictly enforces one object per cell.
-MultiGrid: extension to Grid where each cell is a set of objects.
-
+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.
 """
 # Instruction for PyLint to suppress variable name errors, since we have a
 # good reason to use one-character variable names for x and y.
@@ -17,18 +20,16 @@ MultiGrid: extension to Grid where each cell is a set of objects.
 # Remove this __future__ import once the oldest supported Python is 3.10
 from __future__ import annotations
 
+import collections
 import itertools
 import math
-from warnings import warn
-
-import numpy as np
-
+from numbers import Real
 from typing import (
     Any,
     Callable,
-    List,
     Iterable,
     Iterator,
+    List,
     Sequence,
     Tuple,
     TypeVar,
@@ -36,11 +37,17 @@ from typing import (
     cast,
     overload,
 )
+from warnings import warn
+
+import networkx as nx
+import numpy as np
+import numpy.typing as npt
 
 # For Mypy
 from .agent import Agent
-from numbers import Real
-import numpy.typing as npt
+
+# 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
@@ -55,41 +62,35 @@ MultiGridContent = List[Agent]
 F = TypeVar("F", bound=Callable[..., Any])
 
 
-def clamp(x: float, lowest: float, highest: float) -> float:
-    # much faster than np.clip for a scalar x.
-    return lowest if x <= lowest else (highest if x >= highest else x)
-
-
 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."""
 
-    def wrapper(*args: Any) -> Any:
-        if isinstance(args[1], tuple) and len(args[1]) == 2:
-            return wrapped_function(args[0], [args[1]])
+    def wrapper(grid_instance, positions) -> Any:
+        if isinstance(positions, tuple) and len(positions) == 2:
+            return wrapped_function(grid_instance, [positions])
         else:
-            return wrapped_function(*args)
+            return wrapped_function(grid_instance, positions)
 
     return cast(F, wrapper)
 
 
 def is_integer(x: Real) -> bool:
     # Check if x is either a CPython integer or Numpy integer.
-    return isinstance(x, (int, np.integer))
+    return isinstance(x, _types_integer)
 
 
-class Grid:
-    """Base class for a square grid.
+class _Grid:
+    """Base class for a rectangular grid.
 
-    Grid cells are indexed by [x][y], where [0][0] is assumed to be the
-    bottom-left and [width-1][height-1] is the top-right. If a grid is
+    Grid cells are indexed by [x, y], where [0, 0] is assumed to be the
+    bottom-left and [width-1, height-1] is the top-right. If a grid is
     toroidal, the top and bottom, and left and right, edges wrap to each other
 
     Properties:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
-        grid: Internal list-of-lists which holds the grid cells themselves.
     """
 
     def __init__(self, width: int, height: int, torus: bool) -> None:
@@ -102,26 +103,42 @@ class Grid:
         self.height = height
         self.width = width
         self.torus = torus
+        self.num_cells = height * width
 
-        self.grid: list[list[GridContent]] = []
-
-        for x in range(self.width):
-            col: list[GridContent] = []
-            for y in range(self.height):
-                col.append(self.default_val())
-            self.grid.append(col)
+        # Internal list-of-lists which holds the grid cells themselves
+        self._grid: list[list[GridContent]]
+        self._grid = [
+            [self.default_val() for _ in range(self.height)] for _ in range(self.width)
+        ]
 
-        # Add all cells to the empties list.
-        self.empties = set(itertools.product(*(range(self.width), range(self.height))))
+        # Flag to check if the empties set has been created. Better than initializing
+        # _empties as set() because in this case it would become impossible to discern
+        # if the set hasn't still being built or if it has become empty after creation.
+        self._empties_built = False
 
         # Neighborhood Cache
-        self._neighborhood_cache: dict[Any, list[Coordinate]] = dict()
+        self._neighborhood_cache: dict[Any, list[Coordinate]] = {}
 
     @staticmethod
     def default_val() -> None:
         """Default value for new cell elements."""
         return None
 
+    @property
+    def empties(self) -> set:
+        if not self._empties_built:
+            self.build_empties()
+        return self._empties
+
+    def build_empties(self) -> None:
+        self._empties = set(
+            filter(
+                self.is_cell_empty,
+                itertools.product(range(self.width), range(self.height)),
+            )
+        )
+        self._empties_built = True
+
     @overload
     def __getitem__(self, index: int) -> list[GridContent]:
         ...
@@ -144,55 +161,45 @@ class Grid:
 
         if isinstance(index, int):
             # grid[x]
-            return self.grid[index]
+            return self._grid[index]
         elif isinstance(index[0], tuple):
-            # grid[(x1, y1), (x2, y2)]
+            # grid[(x1, y1), (x2, y2), ...]
             index = cast(Sequence[Coordinate], index)
-
-            cells = []
-            for pos in index:
-                x1, y1 = self.torus_adj(pos)
-                cells.append(self.grid[x1][y1])
-            return cells
+            return [self._grid[x][y] for x, y in map(self.torus_adj, index)]
 
         x, y = index
+        x_int, y_int = is_integer(x), is_integer(y)
 
-        if is_integer(x) and is_integer(y):
+        if x_int and y_int:
             # grid[x, y]
             index = cast(Coordinate, index)
             x, y = self.torus_adj(index)
-            return self.grid[x][y]
-
-        if is_integer(x):
+            return self._grid[x][y]
+        elif x_int:
             # grid[x, :]
             x, _ = self.torus_adj((x, 0))
-            x = slice(x, x + 1)
-
-        if is_integer(y):
+            y = cast(slice, y)
+            return self._grid[x][y]
+        elif y_int:
             # grid[:, y]
             _, y = self.torus_adj((0, y))
-            y = slice(y, y + 1)
-
-        # grid[:, :]
-        x, y = (cast(slice, x), cast(slice, y))
-        cells = []
-        for rows in self.grid[x]:
-            for cell in rows[y]:
-                cells.append(cell)
-        return cells
-
-        raise IndexError
+            x = cast(slice, x)
+            return [rows[y] for rows in self._grid[x]]
+        else:
+            # grid[:, :]
+            x, y = (cast(slice, x), cast(slice, y))
+            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:"""
-        return itertools.chain(*self.grid)
+        return itertools.chain(*self._grid)
 
     def coord_iter(self) -> Iterator[tuple[GridContent, int, int]]:
         """An iterator that returns coordinates as well as cell contents."""
         for row in range(self.width):
             for col in range(self.height):
-                yield self.grid[row][col], row, col  # agent, x, y
+                yield self._grid[row][col], row, col  # agent, x, y
 
     def neighbor_iter(self, pos: Coordinate, moore: bool = True) -> Iterator[Agent]:
         """Iterate over position neighbors.
@@ -230,7 +237,7 @@ class Grid:
             radius: radius, in cells, of neighborhood to get.
 
         Returns:
-            A list of coordinate tuples representing the neighborhood. For
+            An iterator of coordinate tuples representing the neighborhood. For
             example with radius 1, it will return list with number of elements
             equals at most 9 (8) if Moore, 5 (4) if Von Neumann (if not
             including the center).
@@ -265,30 +272,54 @@ class Grid:
         cache_key = (pos, moore, include_center, radius)
         neighborhood = self._neighborhood_cache.get(cache_key, None)
 
-        if neighborhood is None:
-            coordinates: set[Coordinate] = set()
+        if neighborhood is not None:
+            return neighborhood
 
-            x, y = pos
-            for dy in range(-radius, radius + 1):
-                for dx in range(-radius, radius + 1):
-                    if dx == 0 and dy == 0 and not include_center:
-                        continue
-                    # Skip coordinates that are outside manhattan distance
+        # We use a list instead of a dict for the neighborhood because it would
+        # be easier to port the code to Cython or Numba (for performance
+        # purpose), with minimal changes. To better understand how the
+        # algorithm was conceived, look at
+        # https://github.com/projectmesa/mesa/pull/1476#issuecomment-1306220403
+        # and the discussion in that PR in general.
+        neighborhood = []
+
+        x, y = pos
+        if self.torus:
+            x_max_radius, y_max_radius = self.width // 2, self.height // 2
+            x_radius, y_radius = min(radius, x_max_radius), min(radius, y_max_radius)
+
+            # For each dimension, in the edge case where the radius is as big as
+            # possible and the dimension is even, we need to shrink by one the range
+            # of values, to avoid duplicates in neighborhood. For example, if
+            # the width is 4, while x, x_radius, and x_max_radius are 2, then
+            # (x + dx) has a value from 0 to 4 (inclusive), but this means that
+            # the 0 position is repeated since 0 % 4 and 4 % 4 are both 0.
+            xdim_even, ydim_even = (self.width + 1) % 2, (self.height + 1) % 2
+            kx = int(x_radius == x_max_radius and xdim_even)
+            ky = int(y_radius == y_max_radius and ydim_even)
+
+            for dx in range(-x_radius, x_radius + 1 - kx):
+                for dy in range(-y_radius, y_radius + 1 - ky):
                     if not moore and abs(dx) + abs(dy) > radius:
                         continue
 
-                    coord = (x + dx, y + dy)
+                    nx, ny = (x + dx) % self.width, (y + dy) % self.height
+                    neighborhood.append((nx, ny))
+        else:
+            x_range = range(max(0, x - radius), min(self.width, x + radius + 1))
+            y_range = range(max(0, y - radius), min(self.height, y + radius + 1))
+
+            for nx in x_range:
+                for ny in y_range:
+                    if not moore and abs(nx - x) + abs(ny - y) > radius:
+                        continue
 
-                    if self.out_of_bounds(coord):
-                        # Skip if not a torus and new coords out of bounds.
-                        if not self.torus:
-                            continue
-                        coord = self.torus_adj(coord)
+                    neighborhood.append((nx, ny))
 
-                    coordinates.add(coord)
+        if not include_center and neighborhood:
+            neighborhood.remove(pos)
 
-            neighborhood = sorted(coordinates)
-            self._neighborhood_cache[cache_key] = neighborhood
+        self._neighborhood_cache[cache_key] = neighborhood
 
         return neighborhood
 
@@ -366,34 +397,40 @@ class Grid:
     def iter_cell_list_contents(
         self, cell_list: Iterable[Coordinate]
     ) -> Iterator[Agent]:
-        """Returns an iterator of the contents of the cells
-        identified in cell_list.
+        """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.
 
         Returns:
-            An iterator of the contents of the cells identified in cell_list
+            An iterator of the agents contained in the cells identified in `cell_list`.
         """
-        # Note: filter(None, iterator) filters away an element of iterator that
-        # is falsy. Hence, iter_cell_list_contents returns only non-empty
-        # contents.
-        return filter(None, (self.grid[x][y] for x, y in cell_list))
+        # iter_cell_list_contents returns only non-empty contents.
+        return (
+            self._grid[x][y]
+            for x, y in itertools.filterfalse(self.is_cell_empty, cell_list)
+        )
 
     @accept_tuple_argument
     def get_cell_list_contents(self, cell_list: Iterable[Coordinate]) -> list[Agent]:
-        """Returns a list of the contents of the cells
-        identified in cell_list.
-        Note: this method returns a list of `Agent`'s; `None` contents 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.
 
         Returns:
-            A list of the contents of the cells identified in cell_list
+            A list of the agents contained in the cells identified in `cell_list`.
         """
         return list(self.iter_cell_list_contents(cell_list))
 
+    def place_agent(self, agent: Agent, pos: Coordinate) -> None:
+        ...
+
+    def remove_agent(self, agent: Agent) -> None:
+        ...
+
     def move_agent(self, agent: Agent, pos: Coordinate) -> None:
         """Move an agent from its current position to a new position.
 
@@ -404,63 +441,55 @@ class Grid:
         """
         pos = self.torus_adj(pos)
         self.remove_agent(agent)
-        self._place_agent(agent, pos)
-        agent.pos = pos
+        self.place_agent(agent, pos)
 
-    def place_agent(self, agent: Agent, pos: Coordinate) -> None:
-        """Position an agent on the grid, and set its pos variable."""
-        self._place_agent(agent, pos)
-        agent.pos = pos
+    def swap_pos(self, agent_a: Agent, agent_b: Agent) -> None:
+        """Swap agents positions"""
+        agents_no_pos = []
+        if (pos_a := agent_a.pos) is None:
+            agents_no_pos.append(agent_a)
+        if (pos_b := agent_b.pos) is None:
+            agents_no_pos.append(agent_b)
+        if agents_no_pos:
+            agents_no_pos = [f"<Agent id: {a.unique_id}>" for a in agents_no_pos]
+            raise Exception(f"{', '.join(agents_no_pos)} - not on the grid")
 
-    def _place_agent(self, agent: Agent, pos: Coordinate) -> None:
-        """Place the agent at the correct location."""
-        x, y = pos
-        self.grid[x][y] = agent
-        self.empties.discard(pos)
+        if pos_a == pos_b:
+            return
 
-    def remove_agent(self, agent: Agent) -> None:
-        """Remove the agent from the grid and set its pos attribute to None."""
-        pos = agent.pos
-        x, y = pos
-        self.grid[x][y] = self.default_val()
-        self.empties.add(pos)
-        agent.pos = None
+        self.remove_agent(agent_a)
+        self.remove_agent(agent_b)
+
+        self.place_agent(agent_a, pos_b)
+        self.place_agent(agent_b, pos_a)
 
     def is_cell_empty(self, pos: Coordinate) -> bool:
         """Returns a bool of the contents of a cell."""
         x, y = pos
-        return self.grid[x][y] == self.default_val()
+        return self._grid[x][y] == self.default_val()
 
     def move_to_empty(
         self, agent: Agent, cutoff: float = 0.998, num_agents: int | None = None
     ) -> None:
         """Moves agent to a random empty cell, vacating agent's old cell."""
-        if len(self.empties) == 0:
+        if num_agents is not None:
+            warn(
+                (
+                    "`num_agents` is being deprecated since it's no longer used "
+                    "inside `move_to_empty`. It shouldn't be passed as a parameter."
+                ),
+                DeprecationWarning,
+            )
+        num_empty_cells = len(self.empties)
+        if num_empty_cells == 0:
             raise Exception("ERROR: No empty cells")
-        if num_agents is None:
-            try:
-                num_agents = agent.model.schedule.get_agent_count()
-            except AttributeError:
-                raise Exception(
-                    "Your agent is not attached to a model, and so Mesa is unable\n"
-                    "to figure out the total number of agents you have created.\n"
-                    "This number is required in order to calculate the threshold\n"
-                    "for using a much faster algorithm to find an empty cell.\n"
-                    "In this case, you must specify `num_agents`."
-                )
-        new_pos = (0, 0)  # Initialize it with a starting value.
-        # This method is based on Agents.jl's random_empty() implementation.
-        # See https://github.com/JuliaDynamics/Agents.jl/pull/541.
-        # For the discussion, see
-        # https://github.com/projectmesa/mesa/issues/1052.
-        # This switch assumes the worst case (for this algorithm) of one
-        # agent per position, which is not true in general but is appropriate
-        # here.
-        if clamp(num_agents / (self.width * self.height), 0.0, 1.0) < cutoff:
-            # The default cutoff value provided is the break-even comparison
-            # with the time taken in the else branching point.
-            # The number is measured to be 0.998 in Agents.jl, but since Mesa
-            # run under different environment, the number is different here.
+
+        # This method is based on Agents.jl's random_empty() implementation. See
+        # https://github.com/JuliaDynamics/Agents.jl/pull/541. For the discussion, see
+        # https://github.com/projectmesa/mesa/issues/1052. The default cutoff value
+        # provided is the break-even comparison with the time taken in the else
+        # branching point.
+        if 1 - num_empty_cells / self.num_cells < cutoff:
             while True:
                 new_pos = (
                     agent.random.randrange(self.width),
@@ -471,8 +500,7 @@ class Grid:
         else:
             new_pos = agent.random.choice(sorted(self.empties))
         self.remove_agent(agent)
-        self._place_agent(agent, new_pos)
-        agent.pos = new_pos
+        self.place_agent(agent, new_pos)
 
     def find_empty(self) -> Coordinate | None:
         """Pick a random empty cell."""
@@ -499,56 +527,86 @@ class Grid:
         return len(self.empties) > 0
 
 
-class SingleGrid(Grid):
-    """Grid where each cell contains exactly at most one object."""
+class SingleGrid(_Grid):
+    """Rectangular grid where each cell contains exactly at most one agent.
 
-    empties: set[Coordinate] = set()
+    Grid cells are indexed by [x, y], where [0, 0] is assumed to be the
+    bottom-left and [width-1, height-1] is the top-right. If a grid is
+    toroidal, the top and bottom, and left and right, edges wrap to each other.
+
+    Properties:
+        width, height: The grid's width and height.
+        torus: Boolean which determines whether to treat the grid as a torus.
+    """
 
     def position_agent(
         self, agent: Agent, x: int | str = "random", y: int | str = "random"
     ) -> None:
         """Position an agent on the grid.
-        This is used when first placing agents! Use 'move_to_empty()'
-        when you want agents to jump to an empty cell.
+        This is used when first placing agents! Setting either x or y to "random"
+        gives the same behavior as 'move_to_empty()' to get a random position.
+        If x or y are positive, they are used.
         Use 'swap_pos()' to swap agents positions.
-        If x or y are positive, they are used, but if "random",
-        we get a random position.
-        Ensure this random position is not occupied (in Grid).
         """
+        warn(
+            (
+                "`position_agent` is being deprecated; use instead "
+                "`place_agent` to place an agent at a specified "
+                "location or `move_to_empty` to place an agent "
+                "at a random empty cell."
+            ),
+            DeprecationWarning,
+        )
+
+        if not (isinstance(x, int) or x == "random"):
+            raise Exception(
+                "x must be an integer or a string 'random'."
+                f" Actual type: {type(x)}. Actual value: {x}."
+            )
+        if not (isinstance(y, int) or y == "random"):
+            raise Exception(
+                "y must be an integer or a string 'random'."
+                f" Actual type: {type(y)}. Actual value: {y}."
+            )
+
         if x == "random" or y == "random":
-            if len(self.empties) == 0:
-                raise Exception("ERROR: Grid full")
-            coords = agent.random.choice(sorted(self.empties))
+            self.move_to_empty(agent)
         else:
             coords = (x, y)
-        agent.pos = coords
-        self._place_agent(agent, coords)
+            self.place_agent(agent, coords)
 
-    def _place_agent(self, agent: Agent, pos: Coordinate) -> None:
+    def place_agent(self, agent: Agent, pos: Coordinate) -> None:
+        """Place the agent at the specified location, and set its pos variable."""
         if self.is_cell_empty(pos):
-            super()._place_agent(agent, pos)
+            x, y = pos
+            self._grid[x][y] = agent
+            if self._empties_built:
+                self._empties.discard(pos)
+            agent.pos = pos
         else:
             raise Exception("Cell not empty")
 
+    def remove_agent(self, agent: Agent) -> None:
+        """Remove the agent from the grid and set its pos attribute to None."""
+        if (pos := agent.pos) is None:
+            return
+        x, y = pos
+        self._grid[x][y] = self.default_val()
+        if self._empties_built:
+            self._empties.add(pos)
+        agent.pos = None
 
-class MultiGrid(Grid):
-    """Grid where each cell can contain more than one object.
 
-    Grid cells are indexed by [x][y], where [0][0] is assumed to be at
-    bottom-left and [width-1][height-1] is the top-right. If a grid is
-    toroidal, the top and bottom, and left and right, edges wrap to each other.
+class MultiGrid(_Grid):
+    """Rectangular grid where each cell can contain more than one agent.
 
-    Each grid cell holds a set object.
+    Grid cells are indexed by [x, y], where [0, 0] is assumed to be at
+    bottom-left and [width-1, height-1] is the top-right. If a grid is
+    toroidal, the top and bottom, and left and right, edges wrap to each other.
 
     Properties:
         width, height: The grid's width and height.
-
         torus: Boolean which determines whether to treat the grid as a torus.
-
-        grid: Internal list-of-lists which holds the grid cells themselves.
-
-    Methods:
-        get_neighbors: Returns the objects surrounding a given cell.
     """
 
     grid: list[list[MultiGridContent]]
@@ -558,43 +616,45 @@ class MultiGrid(Grid):
         """Default value for new cell elements."""
         return []
 
-    def _place_agent(self, agent: Agent, pos: Coordinate) -> None:
-        """Place the agent at the correct location."""
+    def place_agent(self, agent: Agent, pos: Coordinate) -> None:
+        """Place the agent at the specified location, and set its pos variable."""
         x, y = pos
-        if agent not in self.grid[x][y]:
-            self.grid[x][y].append(agent)
-        self.empties.discard(pos)
+        if agent.pos is None or agent not in self._grid[x][y]:
+            self._grid[x][y].append(agent)
+            agent.pos = pos
+            if self._empties_built:
+                self._empties.discard(pos)
 
     def remove_agent(self, agent: Agent) -> None:
         """Remove the agent from the given location and set its pos attribute to None."""
         pos = agent.pos
         x, y = pos
-        self.grid[x][y].remove(agent)
-        if self.is_cell_empty(pos):
-            self.empties.add(pos)
+        self._grid[x][y].remove(agent)
+        if self._empties_built and self.is_cell_empty(pos):
+            self._empties.add(pos)
         agent.pos = None
 
     @accept_tuple_argument
     def iter_cell_list_contents(
         self, cell_list: Iterable[Coordinate]
-    ) -> Iterator[MultiGridContent]:
-        """Returns an iterator of the contents of the
-        cells identified in cell_list.
+    ) -> Iterator[Agent]:
+        """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.
 
         Returns:
-            A iterator of the contents of the cells identified in cell_list
-
+            An iterator of the agents contained in the cells identified in `cell_list`.
         """
         return itertools.chain.from_iterable(
-            self[x][y] for x, y in cell_list if not self.is_cell_empty((x, y))
+            self._grid[x][y]
+            for x, y in itertools.filterfalse(self.is_cell_empty, cell_list)
         )
 
 
-class HexGrid(Grid):
-    """Hexagonal Grid: Extends Grid to handle hexagonal neighbors.
+class HexGrid(SingleGrid):
+    """Hexagonal Grid: Extends SingleGrid to handle hexagonal neighbors.
 
     Functions according to odd-q rules.
     See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
@@ -611,11 +671,20 @@ class HexGrid(Grid):
             in the neighborhood of a certain point.
     """
 
-    def iter_neighborhood(
+    def torus_adj_2d(self, pos: Coordinate) -> Coordinate:
+        return pos[0] % self.width, pos[1] % self.height
+
+    def get_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.
+    ) -> 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
+        important, the neighborhood can be sketched as:
+
+            Always: (0,-), (0,+)
+            When x is even: (-,+), (-,0), (+,+), (+,0)
+            When x is odd:  (-,0), (-,-), (+,0), (+,-)
 
         Args:
             pos: Coordinate tuple for the neighborhood to get.
@@ -629,49 +698,69 @@ class HexGrid(Grid):
             equals at most 9 (8) if Moore, 5 (4) if Von Neumann (if not
             including the center).
         """
+        cache_key = (pos, include_center, radius)
+        neighborhood = self._neighborhood_cache.get(cache_key, None)
 
-        def torus_adj_2d(pos: Coordinate) -> Coordinate:
-            return (pos[0] % self.width, pos[1] % self.height)
+        if neighborhood is not None:
+            return neighborhood
 
+        queue = collections.deque()
+        queue.append(pos)
         coordinates = set()
 
-        def find_neighbors(pos: Coordinate, radius: int) -> None:
-            x, y = pos
-
-            """
-            Both: (0,-), (0,+)
-
-            Even: (-,+), (-,0), (+,+), (+,0)
-            Odd:  (-,0), (-,-), (+,0), (+,-)
-            """
-            adjacent = [(x, y - 1), (x, y + 1)]
-
-            if include_center:
-                adjacent.append(pos)
-
-            if x % 2 == 0:
-                adjacent += [(x - 1, y + 1), (x - 1, y), (x + 1, y + 1), (x + 1, y)]
-            else:
-                adjacent += [(x - 1, y), (x - 1, y - 1), (x + 1, y), (x + 1, y - 1)]
-
-            if self.torus is False:
-                adjacent = list(
-                    filter(lambda coords: not self.out_of_bounds(coords), adjacent)
-                )
-            else:
-                adjacent = [torus_adj_2d(coord) for coord in adjacent]
+        while radius > 0:
+            level_size = len(queue)
+            radius -= 1
+
+            for _i in range(level_size):
+                x, y = queue.pop()
+
+                if x % 2 == 0:
+                    adjacent = [
+                        (x, y - 1),
+                        (x, y + 1),
+                        (x - 1, y + 1),
+                        (x - 1, y),
+                        (x + 1, y + 1),
+                        (x + 1, y),
+                    ]
+                else:
+                    adjacent = [
+                        (x, y - 1),
+                        (x, y + 1),
+                        (x - 1, y),
+                        (x - 1, y - 1),
+                        (x + 1, y),
+                        (x + 1, y - 1),
+                    ]
+
+                if self.torus:
+                    adjacent = [
+                        coord
+                        for coord in map(self.torus_adj_2d, adjacent)
+                        if coord not in coordinates
+                    ]
+                else:
+                    adjacent = [
+                        coord
+                        for coord in adjacent
+                        if not self.out_of_bounds(coord) and coord not in coordinates
+                    ]
+
+                coordinates.update(adjacent)
+
+                if radius > 0:
+                    queue.extendleft(adjacent)
 
-            coordinates.update(adjacent)
-
-            if radius > 1:
-                [find_neighbors(coords, radius - 1) for coords in adjacent]
-
-        find_neighbors(pos, radius)
+        if include_center:
+            coordinates.add(pos)
+        else:
+            coordinates.discard(pos)
 
-        if not include_center and pos in coordinates:
-            coordinates.remove(pos)
+        neighborhood = sorted(coordinates)
+        self._neighborhood_cache[cache_key] = neighborhood
 
-        yield from coordinates
+        return neighborhood
 
     def neighbor_iter(self, pos: Coordinate) -> Iterator[Agent]:
         """Iterate over position neighbors.
@@ -686,11 +775,11 @@ class HexGrid(Grid):
         )
         return self.iter_neighbors(pos)
 
-    def get_neighborhood(
+    def iter_neighborhood(
         self, pos: Coordinate, include_center: bool = False, radius: int = 1
-    ) -> list[Coordinate]:
-        """Return a list of cells that are in the neighborhood of a
-        certain point.
+    ) -> Iterator[Coordinate]:
+        """Return an iterator over cell coordinates that are in the
+        neighborhood of a certain point.
 
         Args:
             pos: Coordinate tuple for the neighborhood to get.
@@ -699,10 +788,9 @@ class HexGrid(Grid):
             radius: radius, in cells, of neighborhood to get.
 
         Returns:
-            A list of coordinate tuples representing the neighborhood;
-            With radius 1
+            An iterator of coordinate tuples representing the neighborhood.
         """
-        return list(self.iter_neighborhood(pos, include_center, radius))
+        yield from self.get_neighborhood(pos, include_center, radius)
 
     def iter_neighbors(
         self, pos: Coordinate, include_center: bool = False, radius: int = 1
@@ -719,7 +807,7 @@ class HexGrid(Grid):
         Returns:
             An iterator of non-None objects in the given neighborhood
         """
-        neighborhood = self.iter_neighborhood(pos, include_center, radius)
+        neighborhood = self.get_neighborhood(pos, include_center, radius)
         return self.iter_cell_list_contents(neighborhood)
 
     def get_neighbors(
@@ -743,16 +831,14 @@ class HexGrid(Grid):
 class ContinuousSpace:
     """Continuous space where each agent can have an arbitrary position.
 
-    Assumes that all agents are point objects, and have a pos property storing
-    their position as an (x, y) tuple.
+    Assumes that all agents have a pos property storing their position as
+    an (x, y) tuple.
 
-    This class uses a numpy array internally to store agent objects, to speed
+    This class uses a numpy array internally to store agents in order to speed
     up neighborhood lookups. This array is calculated on the first neighborhood
-    lookup, and is reused (and updated) until agents are added or removed.
+    lookup, and is updated if agents are added or removed.
     """
 
-    _grid = None
-
     def __init__(
         self,
         x_max: float,
@@ -785,18 +871,16 @@ class ContinuousSpace:
         self._agent_to_index: dict[Agent, int | None] = {}
 
     def _build_agent_cache(self):
-        """Cache Agent positions to speed up neighbors calculations."""
+        """Cache agents positions to speed up neighbors calculations."""
         self._index_to_agent = {}
-        agents = self._agent_to_index.keys()
-        for idx, agent in enumerate(agents):
+        for idx, agent in enumerate(self._agent_to_index):
             self._agent_to_index[agent] = idx
             self._index_to_agent[idx] = agent
-        self._agent_points = np.array(
-            [self._index_to_agent[idx].pos for idx in range(len(agents))]
-        )
+        # Since dicts are ordered by insertion, we can iterate through agents keys
+        self._agent_points = np.array([agent.pos for agent in self._agent_to_index])
 
     def _invalidate_agent_cache(self):
-        """Clear cached data of Agents and positions in the space."""
+        """Clear cached data of agents and positions in the space."""
         self._agent_points = None
         self._index_to_agent = {}
 
@@ -826,18 +910,17 @@ class ContinuousSpace:
             # instead of invalidating the full cache,
             # apply the move to the cached values
             idx = self._agent_to_index[agent]
-            self._agent_points[idx, 0] = pos[0]
-            self._agent_points[idx, 1] = pos[1]
+            self._agent_points[idx] = pos
 
     def remove_agent(self, agent: Agent) -> None:
-        """Remove an agent from the simulation.
+        """Remove an agent from the space.
 
         Args:
             agent: The agent object to remove
         """
         if agent not in self._agent_to_index:
             raise Exception("Agent does not exist in the space")
-        self._agent_to_index.pop(agent)
+        del self._agent_to_index[agent]
 
         self._invalidate_agent_cache()
         agent.pos = None
@@ -845,7 +928,7 @@ class ContinuousSpace:
     def get_neighbors(
         self, pos: FloatCoordinate, radius: float, include_center: bool = True
     ) -> list[Agent]:
-        """Get all objects within a certain radius.
+        """Get all agents within a certain radius.
 
         Args:
             pos: (x,y) coordinate tuple to center the search at.
@@ -872,7 +955,9 @@ class ContinuousSpace:
     def get_heading(
         self, pos_1: FloatCoordinate, pos_2: FloatCoordinate
     ) -> FloatCoordinate:
-        """Get the heading angle between two points, accounting for toroidal space.
+        """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.
@@ -934,37 +1019,47 @@ class ContinuousSpace:
 class NetworkGrid:
     """Network Grid where each node contains zero or more agents."""
 
-    def __init__(self, G: Any) -> None:
-        self.G = G
+    def __init__(self, g: Any) -> None:
+        """Create a new network.
+
+        Args:
+            G: a NetworkX graph instance.
+        """
+        self.G = g
         for node_id in self.G.nodes:
-            G.nodes[node_id]["agent"] = list()
+            g.nodes[node_id]["agent"] = self.default_val()
 
-    def place_agent(self, agent: Agent, node_id: int) -> None:
-        """Place a agent in a node."""
+    @staticmethod
+    def default_val() -> list:
+        """Default value for a new node."""
+        return []
 
-        self._place_agent(agent, node_id)
+    def place_agent(self, agent: Agent, node_id: int) -> None:
+        """Place an agent in a node."""
+        self.G.nodes[node_id]["agent"].append(agent)
         agent.pos = node_id
 
-    def get_neighbors(self, node_id: int, include_center: bool = False) -> list[int]:
-        """Get all adjacent nodes"""
-
-        neighbors = list(self.G.neighbors(node_id))
-        if include_center:
-            neighbors.append(node_id)
-
+    def get_neighbors(
+        self, node_id: int, include_center: bool = False, radius: int = 1
+    ) -> list[int]:
+        """Get all adjacent nodes within a certain radius"""
+        if radius == 1:
+            neighbors = list(self.G.neighbors(node_id))
+            if include_center:
+                neighbors.append(node_id)
+        else:
+            neighbors_with_distance = nx.single_source_shortest_path_length(
+                self.G, node_id, radius
+            )
+            if not include_center:
+                del neighbors_with_distance[node_id]
+            neighbors = sorted(neighbors_with_distance.keys())
         return neighbors
 
     def move_agent(self, agent: Agent, node_id: int) -> None:
         """Move an agent from its current node to a new node."""
-
         self.remove_agent(agent)
-        self._place_agent(agent, node_id)
-        agent.pos = node_id
-
-    def _place_agent(self, agent: Agent, node_id: int) -> None:
-        """Place the agent at the correct node."""
-
-        self.G.nodes[node_id]["agent"].append(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."""
@@ -974,25 +1069,23 @@ class NetworkGrid:
 
     def is_cell_empty(self, node_id: int) -> bool:
         """Returns a bool of the contents of a cell."""
-        return not self.G.nodes[node_id]["agent"]
+        return self.G.nodes[node_id]["agent"] == self.default_val()
 
-    def get_cell_list_contents(self, cell_list: list[int]) -> list[GridContent]:
-        """Returns the contents of a list of cells ((x,y) tuples)
-        Note: this method returns a list of `Agent`'s; `None` contents are excluded.
+    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.
         """
         return list(self.iter_cell_list_contents(cell_list))
 
-    def get_all_cell_contents(self) -> list[GridContent]:
-        """Returns a list of the contents of the cells
-        identified in cell_list."""
-        return list(self.iter_cell_list_contents(self.G))
+    def get_all_cell_contents(self) -> list[Agent]:
+        """Returns a list of all the agents in the network."""
+        return self.get_cell_list_contents(self.G)
 
-    def iter_cell_list_contents(self, cell_list: list[int]) -> list[GridContent]:
-        """Returns an iterator of the contents of the cells
-        identified in cell_list."""
-        list_of_lists = [
+    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.
+        """
+        return itertools.chain.from_iterable(
             self.G.nodes[node_id]["agent"]
-            for node_id in cell_list
-            if not self.is_cell_empty(node_id)
-        ]
-        return [item for sublist in list_of_lists for item in sublist]
+            for node_id in itertools.filterfalse(self.is_cell_empty, cell_list)
+        )