GeoSpace.layers is a plain list with no named lookup, making multi-layer models ergonomically painful

[Tejasv-Singh]

Summary

GeoSpace.layers is typed as a plain list, with no way to retrieve a specific
layer by name. In multi-layer models (e.g., flood zones, road networks, elevation
rasters), every agent step() that needs to interact with a specific layer requires
a manual for loop or next() workaround.

Environment

• mesa: 3.0.x
• mesa-geo: 0.9.x

Reproduction

# Attempting dict-style access raises TypeError
flood_layer = model.space.layers["flood_zone"]
# TypeError: list indices must be integers or slices, not str

# Current workaround required in every step() that needs a specific layer
flood_layer = next(
    (l for l in self.model.space.layers if getattr(l, "name", None) == "flood_zone"),
    None
)

Expected Behavior

A named lookup method on GeoSpace:

# Option A: explicit method
flood_layer = model.space.get_layer("flood_zone")

# Option B: dict-style access via __getitem__ override
flood_layer = model.space.layers["flood_zone"]

Either would eliminate the boilerplate that currently appears in every multi-layer
model's step() logic.

Proposed Implementation Notes

• Would require enforcing or strongly encouraging a .name attribute on all layer
  types (ImageLayer, RasterLayer, GeoDataFrame-backed layers).
• get_layer(name) could raise KeyError if not found, consistent with dict behavior.
• Backward compatible, layers as a list can remain accessible alongside the new method.

Context

This came up while building a flood evacuation simulation with separate layers for
road networks, flood extents, and elevation data. Targeting specific layers during
agent decision logic requires the same workaround in multiple places, which is a
friction point for any non-trivial geospatial model.

[wang-boyu]

Thanks for writing this up. This seems like a reasonable API improvement.

One possible direction is to make layers collection-like, which would let us support both space.get_layer("flood_zone") and space.layers["flood_zone"], while also leaving room for collection-style behaviors later, for example self.space.layers.do("step"). We have also talked about a similar idea for raster cells at the layer level, e.g. self.space.get_layer("elevation").cells.do("step").

The related Mesa discussion is here: mesa/mesa#2585 (comment). Mesa does not seem to have a generic reusable CollectionBase today, so if mesa-geo goes in this direction it would likely need its own small internal collection abstraction. There is some follow-up discussion here as well: mesa/mesa#3209 (comment).

One thing I would avoid is requiring every layer object to expose .name. In particular, a vector layer may be a GeoDataFrame, and it may already have a name column, so it seems safer for the name to live in the collection / registration step instead, e.g. space.add_layer(gdf, name="some_vector_data").

[Tejasv-Singh]

Thanks for the direction on this,, agreed that keeping the name out of the layer object is the right call. Attaching it at registration avoids the GeoDataFrame.name collision entirely, and it feels cleaner conceptually too: the name is a property of how the model uses the layer, not of the layer itself.

The LayerCollection idea is interesting to me. I was thinking about it and there seem to be a few directions it could go curious where your head is at:

• Should it behave like a list with named access bolted on, or more like an OrderedDict that also supports integer indexing? The distinction matters when you think about things like slicing or iteration order.
• For the do(method) pattern, is the intent that all layers would need to expose a common interface, or would it silently skip layers that don't implement the method?
• Is there appetite for making this reusable across mesa-geo, or would it live as a small internal utility for now?

I also thought about a few alternatives: a proxy/view object that sits on top of the existing list without touching storage, or just making layers a plain dict from the start. The dict approach is the simplest but probably too breaking. The proxy approach is the most conservative. Wondering if you had already ruled either of those out.

On duplicate names, my instinct is to raise ValueError rather than silently overwrite, since a collision in a simulation model is almost always a mistake. But curious if there's a convention elsewhere in mesa-geo I should follow.

Happy to dig into any of this further before anything gets written 🙌
Would love if you could give me some more stuff to refer or to study (not mentioned here) before going further. Got a lot of new learning while going through this issue 🙌