Summary

Fixes a crash in Grid.select_random_empty_cell() when the grid is completely full by wrapping random.choice() in a try-catch block and raising a clear ValueError instead of a cryptic IndexError.

Bug / Issue

Fixes #3014

When a user's agent-based model fills a grid to 100% capacity and calls select_random_empty_cell(), the method crashes with an unhelpful error:

IndexError: Cannot choose from an empty sequence

This happens because the heuristic tries 50 random cell selections (all fail on a full grid), then falls back to np.argwhere(self.property_layers["empty"]) which returns an empty array. When random.choice() is called on an empty array, it raises IndexError, leaving users confused about what went wrong.

Implementation

Wrapped self.random.choice(empty_coords) in a try-except block in Grid.select_random_empty_cell() (mesa/discrete_space/grid.py) to catch IndexError and raise a clear ValueError with proper exception chaining.

Code change:

empty_coords = np.argwhere(self.property_layers["empty"])
try:
    random_coord = self.random.choice(empty_coords)
except IndexError as e:
    raise ValueError(
        "Grid is completely full. No empty cells available. "
        "Cannot select a random empty cell."
    ) from e
return self._cells[tuple(random_coord)]

This approach follows the EAFP (Easier to Ask for Forgiveness than Permission) principle, is more Pythonic, and provides better exception chaining for debugging.

Testing

Added unit test test_infinite_loop_on_full_grid() in test_discrete_space.py that fills a 2×2 grid completely and asserts that the new ValueError with the descriptive message is raised.

Verified test passes with the implementation.

Additional Notes

This change creates a better Developer Experience (DX) by "failing fast" with an explicit, actionable error message rather than crashing deep in the code with a cryptic exception. Users immediately understand that their grid is full and can adjust their model parameters accordingly (more cells, faster agent movement, etc.).

No breaking API changes — only the error type changed, which improves clarity without reducing functionality.