E2S-02: Earth2Studio Grid Protocol¶
Purpose¶
Provide one lightweight contract for describing spatial grids without coupling grid geometry to field data or regridding engines. This protocol describes grids only; it does not select interpolation methods, construct weights, or transform field data.
Contract¶
Interface¶
GridDefinition is a runtime-checkable structural protocol. Implementations satisfy
the interface directly; inheritance is not required.
@runtime_checkable
class GridDefinition(Protocol):
@property
def dims(self) -> tuple[str, ...]: ...
@property
def shape(self) -> tuple[int, ...]: ...
@property
def topology(self) -> GridTopology: ...
@property
def crs(self) -> pyproj.CRS | None: ...
def coords(self, indexes=None, *, only_index=False) -> xr.Coordinates: ...
def subset_indexers(
self,
coordinates,
*,
bounds=None,
bounds_crs=None,
) -> dict[str, object]: ...
def cell_bounds(self, indexes) -> xr.Coordinates | None: ...
@property
def attrs(self) -> dict[str, object]: ...
def fingerprint(self) -> str: ...
dimsdefines authoritative spatial dimension ordershapesizes each dimension in the same ordertopologyidentifies the geometry familycrsdescribes native coordinates when PyProj can represent themcoords()returns complete Xarray coordinates, or dimension indexes withonly_index=Truesubset_indexers()translates supported selections into Xarray indexerscell_bounds()returns optional geographic cell geometryattrsreturns a JSON-serializable description for Xarray and agentsfingerprint()returns stable geometry identity for validation and caching
Package¶
Grid definitions live in earth2studio.grids, with one implementation per file. The
package initializer exports definitions and owns the process-local registry.
| Definition | Dimensions | Topology | Native CRS |
|---|---|---|---|
LatLonGrid |
lat, lon |
Rectilinear | Geographic |
ProjectedGrid |
y, x |
Projected | Required |
CurvilinearGrid |
y, x |
Curvilinear | None |
PointGrid |
x |
Points | None |
HEALPixGrid |
hpx or face, height, width |
HEALPix | None |
Users may implement the protocol directly for other grid families.
Populating Xarray Coordinates¶
A definition provides complete coordinates in one call:
Dimension coordinates preserve definition.dims. Projected, curvilinear, point, and
HEALPix definitions add latitude and longitude as auxiliary coordinates. Use
only_index=True when only inexpensive dimension indexes are needed:
Selected index values avoid generating geographic coordinates for the full grid:
Allocation-free model signatures¶
earth2studio.utils.coord_array consumes the same definitions without allocating
field values. It supplies grid sizes, index coordinates, serializable grid attrs,
and earth2studio_crs from definition.crs. Curvilinear and point grids also
supply geographic coordinates. A registered string adds earth2studio_grid_id.
signature = coord_array(
("batch", "variable", "lat", "lon"),
{"variable": ["t2m"]},
dynamic=("batch",),
grid="latlon-0.25deg-south-pole-excluded",
)
Models using projected grids use the standard y, x dimensions, preserving
native coordinate values in the CRS's units. The grid supplies these axes and
geographic coordinates; infer_grid() can recover the geometry without renaming.
Optional grid_dims maps standard grid axes to a model's
dimension names, including grid-coordinate dimensions and the dims metadata.
Explicit coordinates use the mapped names. This mapping does not rename the grid
definition itself: rename model axes back before passing such an array to
infer_grid() or grid selection methods.
A crop has different axes and shape from its full parent grid. Construct a new
definition with the selected native axes and the same CRS, then pass that definition
to coord_array. For example, for a projected parent grid:
crop = ProjectedGrid(parent.y[10:20], parent.x[30:50], parent.crs)
signature = coord_array(("y", "x"), grid=crop)
This produces the cropped axes and their geographic coordinates without attaching
the full parent's registered ID. Using grid="hrrr", for example, requests the
entire registered HRRR geometry, not a crop; attaching that ID to cropped data
would incorrectly claim that its geometry matches the full registered grid.
Coordinate handshakes compare fixed axes and auxiliary coordinates and require
matching declared grid ID and CRS metadata. coord_array_like() creates output
signatures from validated inputs without recreating or reprojecting their grid.
Model coordinates to target grid¶
The grid contract must support the round trip
GridDefinition -> coord_array -> infer_grid -> GridDefinition. Coordinate arrays
store spatial coordinates and serializable grid metadata, not live grid objects.
Non-spatial model dimensions, including empty dynamic dimensions, must not affect
reconstruction.
The reconstructed target grid owns its geometry, extent, and CRS at construction.
Consumers such as fetch_data can obtain spatial requirements from that object
without asking callers for separate bounds or CRS arguments. Extent computation
belongs to the grid implementation and must respect topology and longitude wrap;
a bounding rectangle alone is not a complete grid description.
Reconstruction must preserve actual coordinate values, crops, axis order, and CRS. A registered grid ID must not cause changed coordinates to be replaced by the parent geometry merely because their shapes match. Renamed model axes must be recoverable from coordinate metadata without caller-side renaming.
Standard-layout reconstruction exists today. Metadata-driven reconstruction of renamed axes, validation of registered geometry against coordinate values, and an explicit grid-owned extent interface are required follow-up work. The manual renaming guidance above describes the current implementation until that support lands. Fetch-side regridding onto a target grid is specified in E2S-05_FETCH_DATA_SPEC.md.
Until that validation lands, a registered earth2studio_grid_id is trusted:
infer_grid() and handshake_dataarray() compare only dimension names and sizes
for labelled data. Data whose latitude was reversed, whose longitude was rolled or
converted to -180..180, or which was otherwise reordered after it was labelled is
still accepted as the registered grid and read in the wrong order. Drop the label
(array.attrs.pop("earth2studio_grid_id")) after reordering spatial axes so the
actual coordinates are used.
HEALPix Representations¶
HEALPix ordering and storage layout are explicit. nested and ring use a flat
hpx dimension. xy supports flat hpx storage or an expanded
(face, height, width) layout. XY also records its face origin and winding so layouts
such as Earth2Grid's HEALPIX_PAD_XY are unambiguous:
dlesym = grids.HEALPixGrid(
level=6,
ordering="xy",
layout="face",
xy_origin="north",
xy_clockwise=True,
)
Registry¶
The process-local registry maps stable names and aliases to complete definitions:
grids.register_grid("regional-lcc", definition, aliases=("regional",))
definition = grids.resolve_grid("regional")
names = grids.list_grids()
Registration validates protocol conformance, dimensions, shape, index coordinates, serializable metadata, and a nonempty fingerprint. Re-registering an identical definition is a no-op; conflicting names and aliases raise an error. Names recognized as CRS input by PyProj are reserved.
Inferring Grid Type¶
infer_grid() follows an explicit-to-general chain:
- Resolve and validate
earth2studio_grid_id - Infer a projected grid from
y,x, andearth2studio_crs - Infer rectilinear, point, or curvilinear layouts from latitude and longitude
- Raise when no supported layout is unambiguous
PointGrid is the fallback for arbitrary samples represented as lat(x) and
lon(x). Generic lat(hpx) and lon(hpx) are not enough to distinguish HEALPix
ordering, layout, or level, so HEALPix requires a registered grid identifier.
Selection¶
Selection returns positional Xarray indexers and never receives field data. Every
definition supports geographic bounds and optional bounds_crs. HEALPix also
supports face selection when its ordering identifies faces.
indexers = definition.subset_indexers(
coordinates,
bounds=(-125, 25, -65, 50),
bounds_crs="EPSG:4326",
)
subset = array.isel(indexers)
Bounds (min_x, min_y, max_x, max_y) are inclusive limits on cell centres. In a
geographic bounds_crs (the default), longitude bounds are independent of the
grid's longitude convention: a cell is selected when its longitude lies at most
max_x - min_x degrees east of min_x, modulo 360. So (0, 180) includes the
180° meridian on both 0..360 and -180..180 grids; (-190, -170), (170, 190) and
(170, -170) select the same 20° box across the dateline; and min_x > max_x
wraps eastward through the dateline, as Region.box does. Unlike Region.box,
which rejects a 360° span in favour of Region.band, a span of 360° or more selects
every longitude. Projected bounds are compared without wrapping.