space: Document empties property

mesa/space.py

@@ -492,9 +492,18 @@ class SingleGrid(_Grid):
     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.
 
+    This class provides a property `empties` that returns a set of coordinates
+    for all empty cells in the grid. It is automatically updated whenever
+    agents are added or removed from the grid. The `empties` property should be
+    used for efficient access to current empty cells rather than manually
+    iterating over the grid to check for emptiness.
+
     Properties:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
+        empties: Returns a set of (x, y) tuples for all empty cells. This set is
+                 maintained internally and provides a performant way to query
+                 the grid for empty spaces.
     """
 
     def place_agent(self, agent: Agent, pos: Coordinate) -> None:
@@ -526,9 +535,14 @@ class MultiGrid(_Grid):
     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.
 
+    This class maintains an `empties` property, which is a set of coordinates
+    for all cells that currently contain no agents. This property is updated
+    automatically as agents are added to or removed from the grid.
+
     Properties:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
+        empties: Returns a set of (x, y) tuples for all empty cells.
     """
 
     grid: list[list[MultiGridContent]]
@@ -745,9 +759,13 @@ class HexSingleGrid(_HexGrid, SingleGrid):
     Functions according to odd-q rules.
     See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
 
+    This class also maintains an `empties` property, similar to SingleGrid,
+    which provides a set of coordinates for all empty hexagonal cells.
+
     Properties:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
+        empties: Returns a set of hexagonal coordinates for all empty cells.
     """
 
 
@@ -758,9 +776,15 @@ class HexMultiGrid(_HexGrid, MultiGrid):
     Functions according to odd-q rules.
     See http://www.redblobgames.com/grids/hexagons/#coordinates for more.
 
+    Similar to the standard MultiGrid, this class maintains an `empties` property,
+    which is a set of coordinates for all hexagonal cells that currently contain
+    no agents. This property is updated automatically as agents are added to or
+    removed from the grid.
+
     Properties:
         width, height: The grid's width and height.
         torus: Boolean which determines whether to treat the grid as a torus.
+        empties: Returns a set of hexagonal coordinates for all empty cells.
     """
 
 
@@ -797,6 +821,9 @@ class ContinuousSpace:
     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 updated if agents are added or removed.
+
+    The concept of 'empty cells' is not directly applicable in continuous space,
+    as positions are not discretized.
     """
 
     def __init__(