GSoC 2026: RasterLayer Refactor: Architecture Design

[Tejasv-Singh]

Opening this discussion to document architecture decisions for the GSoC 2026 RasterLayer refactor. Mentors please flag anything
that needs correcting. @wang-boyu @jackiekazil

Context: RasterLayer currently suffers from per-cell object overhead and does not scale to realistic raster sizes. Prior work (mesa-geo #310 ) showed that a NumPy-backed design improves performance significantly. This discussion proposes an updated architecture aligned with Mesa core's shift away from PropertyLayer and toward raw NumPy-based storage (mesa #3340 ).

1. Storage Backend

Each raster band stored as a raw NumPy array in a plain dict:

self._property_layers: dict[str, np.ndarray] = {}

Following the pattern introduced in mesa #3340. No wrapper class.

2. Cell Proxy: Full Dynamic Band Access

Cell no longer inherits from mesa.Agent and stores no data itself, it is purely a proxy view that dynamically exposes all bands in _property_layers
via __getattr__ and __setattr__:

def __getattr__(self, name):
    if name in self._layer._property_layers:
        row, col = self.rowcol
        return self._layer._property_layers[name][row, col]
    raise AttributeError(f"No band '{name}' on this layer")

def __setattr__(self, name, value):
    if name in self._layer._property_layers:
        row, col = self.rowcol
        self._layer._property_layers[name][row, col] = value
        return
    super().__setattr__(name, value)

So cell.elevation, cell.slope, cell.is_urban all work automatically, whatever bands the layer has, without any manual registration.

Cell identity cache uses a plain dict with strong references (not
WeakValueDictionary), following the reasoning in mesa#3128 and mesa#3210.
Cells have a fixed lifecycle managed by the layer, no ghost-cell problem.

3. Both Cell-Level and Band-Level Access Are First-Class

Cell-level access is the foundation. Vectorized band-level operations are an optional fast path on top. Urban Growth proves cell-level cannot be demoted, neighbourhood-dependent CA rules are not easily expressible as vectorized NumPy operations, and in academic modelling correctness and clarity come before speed.

4. Order of Work

Backend + Cell proxy → Cell-level execution → Vectorization → Collection API → SolaraViz

Open Questions

• Are there operations in Rainfall, GeoSchelling, or Population that add Cell proxy requirements not covered above?
• Any concerns with the strong-ref cache approach before I proceed?
• Does the proposed dual interface (cell-level for correctness, vectorized for performance) align with the long-term Mesa-Geo API direction?