Summary

The tutorial "Adding Space" fails during execution because agents attempt to move into cells that have reached their capacity limit of 5 agents. The Cell.add_agent() method raises a generic Exception when capacity is exceeded, causing the model to crash.

Bug / Issue

When running the tutorial code from 1_adding_space.ipynb, the model crashes after a few steps with:

Exception: ERROR: Cell is full

This occurs in the MoneyAgent.move() method when self.cell.neighborhood.select_random_cell() returns a cell that is already at capacity (5 agents).

Error location: mesa/discrete_space/cell.py:113 in Cell.add_agent()

Expected Behavior

One of the following should happen:

1. The tutorial should use a capacity that prevents this issue (e.g., capacity=None for unlimited)
2. The select_random_cell() method should have an option to only select cells with available capacity
3. The Cell.add_agent() method should handle capacity gracefully (e.g., return False or skip silently)
4. The agent's move() method should check capacity before attempting to move

Steps to Reproduce

1. Run the tutorial code from 1_adding_space.ipynb
2. Create a MoneyModel(100, 10, 10) with 100 agents on a 10x10 grid with capacity=5
3. Call model.step() multiple times
4. Eventually agents will attempt to move into full cells, causing the crash

Additional Notes

• This is a breaking issue for the tutorial and Readthedocs