Clarify ContinuousSpace.get_neighbors behavior with multiple agents at same position

[quaquel]

This PR clarifies the behavior of ContinuousSpace.get_neighbors when multiple agents occupy the same position.

Changes:

1. Add detailed documentation to get_neighbors explaining how include_center=False affects agents at the same position
2. Update the Boids example to demonstrate the recommended pattern of using include_center=True and filtering out self

Context:
When multiple agents occupy the same position and include_center=False is used, all agents at that position are excluded from the results - not just the center agent. This is the expected behavior, but was not clearly documented. Rather than making a breaking change to the API, this PR:

1. Documents the behavior explicitly
2. Shows the recommended pattern of using include_center=True and filtering unwanted agents

Example usage:

# Before (potentially misses "neighbors" at same position):
neighbors = space.get_neighbors(self.pos, radius, include_center=False)

# Workaround:
neighbors = space.get_neighbors(self.pos, radius, include_center=True)
neighbors = [n for n in neighbors if n is not self]

Closes #2592.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -0.1% [-2.0%, +1.9%]	🔵 +0.5% [+0.4%, +0.6%]
BoltzmannWealth	large	🔵 -0.4% [-0.6%, -0.1%]	🔵 -1.2% [-2.0%, -0.4%]
Schelling	small	🔵 +0.2% [-0.2%, +0.5%]	🔵 +0.3% [+0.2%, +0.4%]
Schelling	large	🔵 -0.1% [-2.0%, +1.2%]	🔵 +0.6% [-0.2%, +1.6%]
WolfSheep	small	🔵 +0.8% [+0.2%, +1.4%]	🔵 +1.8% [-3.6%, +7.1%]
WolfSheep	large	🔵 +0.8% [-0.1%, +1.7%]	🔵 +1.5% [+0.5%, +2.4%]
BoidFlockers	small	🔵 -1.1% [-1.7%, -0.4%]	🔵 +0.0% [-0.8%, +0.8%]
BoidFlockers	large	🔵 -1.6% [-2.4%, -0.8%]	🔵 -0.8% [-1.4%, -0.1%]

[EwoutH]

Sounds like it’s working like intended, right? All agents with the same location are not considered neighbors.

Specifically for flocking, since agents are on continuous coordinates, isn’t the chance extremely small a neighbor has the exact same location (fp32 precision?) as another agent?

[quaquel]

Sounds like it’s working like intended, right? All agents with the same location are not considered neighbors.

I beg to differ. To me, if a given agent X asks for its neighbors, I expect to get all neighbors even if there happens to be an agent Y on the exact same location this agent Y is still a neighbor of agent X.

Specifically for flocking, since agents are on continuous coordinates, isn’t the chance extremely small a neighbor has the exact same location (fp32 precision?) as another agent?

Yes, this is very much an edge-case kind of issue, which is why the documentation solution is fine as far as I am concerned.

[EwoutH]

Looks good, thanks!

[EwoutH]

I updated the PR title and body to reflect the final changes. Feel free to adjust further or let me know if you don't like it.