Fix draw_network: Handle multiple agents per node correctly (#2691)

[aarav-shukla07]

Summary

The draw_network() function previously failed when there were more agents than nodes in a network visualization. This PR fixes the issue by properly handling multiple agents at the same node, ensuring they are displayed correctly without overlapping.

Bug / Issue

Linked Issue: #2691
Problem:

• The draw_network() function assumed a 1:1 mapping of agents to nodes, causing errors when multiple agents occupied a single node.
• Indexing errors (IndexError) occurred due to incorrect NumPy array handling, leading to crashes in _scatter().
• The function overlapped agents at the same node, making visualization unreadable.

Expected Behavior:

• The function should allow multiple agents per node and display them without overlap.
• The visualization should not crash when draw_network() is called on a network with more agents than nodes.

Actual Behavior (Before Fix):

• ❌ IndexError due to NumPy array misalignment.
• ❌ Agents stacked on top of each other, making visualization unusable.
• ❌ _scatter() failed when no agents were present.

Implementation

The fix introduces the following changes:
(1) Grouped agents per node manually

• Instead of using missing methods (get_all_cell_contents()), we now directly track agents using space.agents.

(2) Adjusted agent positions to prevent overlap

• Used a circular spread algorithm (cos & sin functions) to position agents around their node.

(3) Fixed IndexError by ensuring arguments["loc"] is always a 2D NumPy array

• Used .reshape(-1, 2) to maintain (N,2) format, avoiding NumPy misalignment errors.

(4) Prevented _scatter() from failing on empty agent lists

• Checked if arguments["loc"].shape[0] > 0 before calling _scatter().

Code Changes:

• Modified mpl_space_drawing.py to correctly handle agent visualization for network models.
• Ensured agents are evenly distributed around their node rather than overlapping.

Testing

(1) Ran all tests in test_components_matplotlib.py

• Result: 7 passed, 1167 warnings (Warnings unrelated to this PR).

(2) Manually tested visualization with network models containing more agents than nodes

• Before Fix: ❌ Overlapping agents, crashes when no agents.
• After Fix: ✅ Agents spread properly, no crashes.

Additional Notes

• This fix is backward-compatible and does not affect any other functionality in Mesa.
• No new dependencies were added.
• The fix ensures that future changes to draw_network() will properly support multiple agents per node.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🟢 -45.0% [-45.7%, -44.4%]	🔴 +21.1% [+20.9%, +21.3%]
BoltzmannWealth	large	🟢 -53.6% [-60.0%, -50.4%]	🔴 +12.2% [+8.9%, +15.2%]
Schelling	small	🟢 -60.7% [-60.9%, -60.5%]	🔵 -2.8% [-3.0%, -2.6%]
Schelling	large	🟢 -56.6% [-56.7%, -56.5%]	🔵 +3.3% [+2.8%, +3.8%]
WolfSheep	small	🔵 -3.0% [-3.3%, -2.6%]	🟢 -5.3% [-5.6%, -5.1%]
WolfSheep	large	🔵 -3.1% [-3.7%, -2.4%]	🟢 -7.1% [-8.0%, -6.3%]
BoidFlockers	small	🔵 +1.1% [+0.5%, +1.8%]	🔵 -0.2% [-0.4%, +0.1%]
BoidFlockers	large	🔵 +1.0% [+0.4%, +1.5%]	🔵 -0.3% [-0.5%, -0.0%]

[quaquel]

This does not work for mesa.discrete_space.Network

[aarav-shukla07]

hi @quaquel
Thanks for your review!
I have updated the code to ensure compatibility with mesa.discrete_space.Network by properly handling agent positions and preventing KeyError: None. Now, all 7 tests are passing. Let me know if further improvements are needed!

[EwoutH]

@quaquel are you able to further review this PR?