Spatial indexing of GeoAgents

[wang-boyu]

What's the problem this feature will solve?

Mesa-Geo uses RTree for spatial indexing of GeoAgents. When such indexing is not necessary (e.g., no neighborhood queries are needed), it could be a performance bottleneck, especially if there's a huge number of GeoAgents. See wang-boyu/agents-and-networks-in-python#2.

On the other hand, when indexing is actually needed, it happens only when adding agents:

mesa-geo/mesa_geo/geospace.py

Lines 292 to 308 in a12f735

	def add_agents(self, agents):
	"""Add a list of GeoAgents to the layer without checking their crs.
	GeoAgents must have the same crs to avoid incorrect spatial indexing results.
	To change the crs of a GeoAgent, use `GeoAgent.to_crs()` method. Refer to
	`GeoSpace._check_agent()` as an example.
	This function may also be called with a single GeoAgent.
	Args:
	agents: List of GeoAgents, or a single GeoAgent, to be added into the layer.
	"""
	if isinstance(agents, GeoAgent):
	agent = agents
	self.idx.insert(id(agent), agent.geometry.bounds, None)
	self.idx.agents[id(agent)] = agent
	else:
	self._recreate_rtree(agents)

Whenever agents move and need re-index, users need to manually call GeoSpace._recreate_rtree(). For example:

mesa-geo/examples/geo_sir/model.py

Line 109 in a12f735

self.space._recreate_rtree() # Recalculate spatial tree, because agents are moving

Describe the solution you'd like

• Do not perform spatial indexing when it is not needed.
• When spatial indexing is needed, automatically keep track of agents' movements and re-index accordingly.

[mrceresa]

Thanks for opening he issue here!

Maybe we could add an additional layer in GeoSpace specifically for fast moving objects?

As of know there is the AgentLayer which index everything with rtree and then the StaticLayers with rasters, images and geodataframes

mesa-geo/mesa_geo/geospace.py

Line 84 in a3f01ad

def layers(self) -> List[ImageLayer | RasterLayer | gpd.GeoDataFrame]:

Maybe I could add the fast agents as a vector layer and keep track of the movements there

I could try to create a small PR with this change if you think it is interesting

[wang-boyu]

Sounds good! A PR would be great - appreciate your time and effort on this!

Just a note on visualization that might be related - MapVisualization.py renders layers and agents separately in different ways:

mesa-geo/mesa_geo/visualization/modules/MapVisualization.py

Lines 76 to 80 in a3f01ad

	def render(self, model):
	return {
	"layers": self._render_layers(model),
	"agents": self._render_agents(model),
	}

If you have any questions regarding creating a PR, please feel free to ask. We also have a contributors guide for your reference.

[mrceresa]

Sure! and thanks for the heads-up on the layer rendering, this is indeed important to consider.

I'll look at the contrib guide and post something here as soon as possible

[wang-boyu]

Implemented in #179. Closing.