Appendix to Meshes, dimensions and fields: three typed designs and how they layer. The inputs the three proposals are built from: what each note of this knowledge base contributes, the ICON / ICON4Py constraints those notes record, how three Python libraries (xarray, coordax, uxarray) and three conventions (UGRID, SGRID, CF) model dimensions, meshes and fields, and where the idea that “a field should know its mesh” comes from. Library claims were checked against source and, where marked (ran), by the probe scripts vendored next to this note.

1. Method and versions

  • Knowledge base: every note touching dimensions, meshes, domains or fields was read in full (list in §2).

  • Libraries, read at source and probed:

    • xarray 23c9dd1 (installed as 2026.9.0);
    • coordax 765bb88 (0.2.8);
    • uxarray c05cb5a (installed as 2026.9.1).

    ICON4Py details were cross-checked at e9060a1898823d38028b5cbf7f506e460fc451d7; today’s GTIR kernel/host-plan distinction at gt4py f3b3ab28ecfc4de6ef914d6e7bed17a5447fd43f. The library observations below are version-specific, not normative loader or typing contracts.

    Probes: xarray_probe.py, coordax_probe.py, uxarray_probe.py. Each has its run command and expected output in its docstring.

  • Conventions:

    • UGRID 1.0;
    • SGRID 0.3;
    • CF-1.13 (17 Dec 2025), cited by section;
    • the CF data model paper, Hassell et al. 2017, GMD 10:4619–4646.

2. Knowledge-base inputs

NoteWhat it contributesConstraints and stances it records
Connectivities as typesNominal dimension classes, identified by qualified name. NeighborConnectivity[Domain, Codomain] declarations with a nested Local. A table bound per call and checked at the boundary. Staggered[D] on a declared Cartesian axis.Four strings that had to agree (tag, variable, local dimension, provider key). Counts and skip-value presence are mesh- and configuration-dependent, so they are taken from the bound table.
Dependent-typing appendixThe theoretical base: Fin, Π, Σ, refinements, evidence, enumeration, parameter vs index, validating at the boundary.gt4py takes the “middle road”: brands, validated constructors, checks at the boundary.
Dependent local dimensionsChained connectivities. Path (LIFO) vs forest (leaf rule); forest slots require Local[C, P] ancestry and reparenting.Reduction order matters operationally (streaming, gathered masks). At most one live local dimension today.
Generic dimensions and staggeringDimension TypeVar/TypeVarTuple; per-rank and per-position overloads for replacing a dimension wherever it occurs; Dual[X] via decorator overloads.4 generic vs 14 concrete operators on the shallow-water C-grid kernel: staggering without dimension genericity is a regression.
Mesh with first-class halosA V/E/C vocabulary. Multi-hop relations as compositions that are kept materialized. Halo depth as a symbolic relation closure. Ownership triple plus execution classes. Exchange placement as forward dataflow.Three causes of skip values: pentagons, LAM boundary, halo edge of reach. Neighbor order is load-bearing. “Keep the vertical out of the mesh”.
Field data protocolA field is a function over absolute, possibly infinite coordinates. The origin is private to the buffer. Support ⊇ domain.One layer owns all domain arithmetic.
Boundary-condition syntaxDomains as conditions (concat_where); region literals K[0], K[1:nlev]; restriction as decomposition.ICON4Py horizontal conditions use named index symbols that mix boundary and halo bounds. Domain.__bool__ must raise.
Scan redesignAnchored vertical ranges (KDim.start/KDim.stop). Forward-anchored vertical domain inference. Static vertical windows as compile-time connectivities.The vertical is never distributed. Half levels (n+1) are staggering. Bare negative indices are not allowed.
Dtype-generic fieldsDeclare statically, bind at call time, monomorphize at FOAST (two-level type theory).Strict: exact match or error, no promotion.
Discretization-independent FD syntaxGather–weight–reduce normal form, a declared placement/operator family, and distinct EDGE_N, EDGE_T, EDGE quantities. Main C connects this facade to an explicit side/degree cochain core.C/D guarantees require compatible representations, conversions and boundaries. Its §6.4–6.5 primal naming differs from the stored-mesh convention; see main C and conflicts. The vertical and limiters need escape hatches.
Working principlesDeep modules, DRY, making implicit concepts explicit, bounded contexts and anticorruption layers.Red flags: information leakage, buried rules, unexamined constraints.

Two source distinctions require care: the staggering appendix §1 conflates directional edge families with physical N/T components; FD-syntax §3.3 links the families indirectly, whereas §7.1 defines N/T explicitly. The main note separates direction, quantity, side/degree and sampling. Its core Primal[Literal[0]] / Dual[Literal[1]] families use concrete literal degrees; point, mean and integrated representations still require explicit conversions.

Related work still in open PRs at the time of writing:

  • GridTools/gt4py_knowledge#31: a default domain per program statement plus per-output restrictions. Its examples bound outputs with ICON4Py zone symbols such as start_edge_nudging_level_2 and end_edge_local.
  • GridTools/gt4py_knowledge#25: JAX support for connectivities. It proposes a small, eagerly computed bounds descriptor per table, which is compile-time information about a runtime table.

3. ICON / ICON4Py constraints

From the ICON4Py surveys appended to the mesh and boundary-condition notes:

  • Closed set of horizontal offsets:
    • 14 offsets, up to 4 hops (C2E2C2E2C, 9 neighbours).
    • 8 tables are read from the grid file (1-based, converted to 0-based); the multi-hop ones are derived.
    • Neighbour order is semantic: icon_edge_order exists because compute_e_flx_avg depends on it.
  • Zones and layout:
    • At the pinned ICON4Py revision, cells/vertices use END, INTERIOR, LOCAL, HALO, HALO_LEVEL_2, LATERAL_BOUNDARY (level 1) through LEVEL_4, and NUDGING. Edges additionally use HALO_LEVEL_3, boundary levels 5–8 and NUDGING_LEVEL_2. These port ICON’s rl_start/rl_end and refin_ctrl (horizontal.py).
    • The local memory layout is |lateral-boundary|nudging|interior|halo1|halo2|.
    • LAM halos are not contiguous.
    • One vocabulary covers both semantic boundary zones and decomposition zones.
  • Halo lines:
    • cells 2, vertices 2, edges 3; the third edge line exists only to make C2E complete;
    • multi-hop tables are incomplete in the outer halo;
    • granules compute into the halo by hand (end_index(HALO_LEVEL_2));
    • exchanges (GHEX) are placed by hand.
    • The second cell halo closes vertex hexagons, not the exact four-hop cell neighbourhood; imported support must be checked against each program’s required footprint (halo.py).
  • Boundary/feedback labels: ICON v2.6.4 counts edge levels differently from cell/vertex levels; negative refin_ctrl values mark parent-child overlap. These are semantic masks, not automatically closed subcomplexes or a common distance filtration (nesting paper, Appendix A1).
  • Skip values:
    • from pentagons (intrinsic arity), the LAM lateral boundary (semantic), and the edge of the halo (an artifact);
    • keep_skip_values=False rewrites tables to hide the artifact and cannot tell the three apart.
  • Vertical:
    • full and half levels: KHalfDim is a separate dimension today;
    • n+1 interface quantities;
    • the vertical is never decomposed.
  • Outside V/E/C: LsqUnkDim (a local axis with no table), RBFDimension, sparse coefficient fields read from the grid file, and dynamic vertical indirection.
  • Fortran granule path: nproma-padded buffers, 1-based tables, start and end indices supplied by ICON, halo_levels=None.

4. Libraries

4.1 xarray

  • Dimension identity: any hashable (_Dim = Hashable, xarray/namedarray/_typing.py:72). In practice it is a str, which netCDF requires. Classes work in memory (ran).
  • Coordinates and indexes are separate from the dimension name (the Index API, xarray/core/indexes.py:39). Arithmetic matches by name with a configurable join. The default inner join of two fields whose coordinate labels differ yields an empty result; arithmetic_join="exact" raises AlignmentError (ran).
  • Connectivity is plain data. edge_field.isel(edge=v2e) gathers, and the result takes the table’s dimensions ('vertex', 'v2e_local'), so the local dimension’s name belongs to the table value (ran).
  • No skip values: -1 wraps around to the last element; masking is manual (ran).
  • No mesh, no staggering: a cell field and a face field broadcast silently into an outer product (ran).
  • No index-space origin: positional indexing is always 0-based; RangeIndex is a label range.

4.2 coordax

  • Dimension identity: str only. A class raises TypeError (ran).
  • Coordinate objects:
    • frozen, hashable, registered as static JAX pytree nodes, so they are part of the trace and compilation cache key (coordax/coordinate_systems.py:79);
    • SizedAxis checks the size, LabeledAxis checks tick content via ArrayKey (hash of the bytes);
    • custom subclasses can model grids, and a CartesianProduct combines axes.
  • Exact alignment: cmap rejects two fields that use one name with unequal coordinates (coordax/fields.py, _cmap_with_doc). Offset ticks on the same name therefore raise (ran), but differently named dimensions broadcast silently (ran).
  • Connectivity: untag the gathered axis and cmap a take. The result takes the table field’s dimensions (ran). There are no skip values and no ragged rows.
  • The mesh as an index: a table stored in a Coordinate would be static, so it would brand fields by content and compile once per mesh. This is §7’s “index” option, the opposite of gt4py’s table-as-parameter.

4.3 uxarray

  • The mesh is Grid (uxarray/grid/grid.py:116). It wraps a UGRID-encoded xr.Dataset with lazily derived connectivities (9 properties named by entity pair), geometry, and subsetting with inverse_indices. Readers exist for UGRID, MPAS, ICON, ESMF, Exodus, SCRIP, FESOM2 and HEALPix.

  • A fixed vocabulary removes the string-agreement problem (uxarray/conventions/ugrid.py, DIM_NAMES):

    • entities are n_node/n_edge/n_face;
    • every connectivity owns its local dimension name, except two, which edge_node_connectivity and edge_face_connectivity share. That conflates two different slot spaces.
    • A field’s location is inferred from its dimension name (data_mapping).
  • Loader normalization is conditional, not a safe normalization contract. At c05cb5a, uxarray/io/_ugrid.py:214–252, fill/dtype conversion uses INT_FILL_VALUE (minimum of intp), and rebasing is nested under that conversion branch. Through public Grid.from_dataset in 2026.9.1 (ran):

    • INT_DTYPE + INT_FILL_VALUE + start_index=1 leaves row [1,2,3] unchanged, although normalized output should be [0,1,2];
    • int32 input with omitted start_index and an unreferenced node 0 rebases row [1,2,3] to [0,1,2], although UGRID defaults to zero origin and the indices should remain unchanged.

    The extended pinned probe records both regressions. The proposed loader in main decision 7 normalizes independently of dtype/fill, honours explicit origin and the zero default, and checks bounds. Grid.validate() is opt-in, not called internally.

  • Ragged degree: topological aggregations partition faces by their true node count (uxarray/core/aggregation.py, get_face_node_partitions). They pick the connectivity from the pair of locations: topological_mean(destination="face") (ran).

  • Fields know their mesh: UxDataArray.uxgrid (uxarray/core/dataarray.py:62-187), propagated by _copy/_replace. However:

    • grid equality is checked only by curl, divergence, scalardotgradient and concat (dataarray.py:1688, 1799, 1907; uxarray/core/api.py:651);
    • plain a + b across two meshes silently keeps a’s grid (ran);
    • a 5-element n_face array attaches to a 2-face grid without complaint (ran).
  • Grid identity: is, otherwise content equality of the node coordinates and face_node_connectivity (Grid.__eq__, grid.py:791). The test is written not (lon.equals or lat.equals), so a latitude-only change compares equal (ran).

  • Dual mesh (use_dual, uxarray/grid/dual.py) in the full primal/dual sense, i.e. the Hodge-dual meaning of “dual”.

4.4 Summary

xarraycoordaxuxarraygt4py (connectivities as types)
Dimension identityhashable (usually str)strfixed UGRID namesnominal class, qualified name
Connectivitydata; the result takes the table’s dimensionsdata, via cmap9 entity-pair properties (node/edge/face squared)declaration class plus a table bound per call
Local dimension owned bythe table valuethe table valuethe connectivity (fixed name), except twothe declaration (V2E.Local)
Skip valuesnonenoneone fill sentinel; true ragged degree in aggregationsskip_value, max_neighbors/min_neighbors
Mesh objectnonenone (a Coordinate could act as one)Gridnone (the provider dict)
A field knows its meshnoper-axis coordinates.uxgrid, rarely checkedno
Static checkingnonenone (trace time)nonemypy and pyright
Staggeringnoneoffset ticksprimal/dual meshesStaggered[D]

5. Conventions

5.1 UGRID and SGRID

  • UGRID describes a mesh as a placeholder variable (cf_role = "mesh_topology") whose attributes name connectivity arrays by entity pair (face_node_connectivity, …):
    • ragged rows are padded with _FillValue;
    • start_index ∈ {0, 1}, default zero when omitted; minimum referenced index does not determine origin;
    • a data variable carries mesh and location, or location_index_set for data on a subset;
    • face nodes should be anticlockwise.
  • SGRID: structured topology with node_dimensions, face_dimensions and padding ∈ {none, low, high, both}. A data variable carries grid and location (node, edge1, edge2, face).
  • Locations: UGRID names entity placement (node/edge/face), which can correspond to primal degrees; SGRID names product staggering via per-axis bit vectors. Neither alone determines cochain side, quantity or point/integrated representation (see the conventions appendix and main C).

5.2 CF-1.13

  • Dimensions vs coordinates:
    • a netCDF dimension is an index space (§2.4);
    • a coordinate variable shares its dimension’s name;
    • auxiliary coordinates are attached through the coordinates attribute (§5).
  • The vertical is recognized by pressure units or a positive attribute (§4.3); axis="Z" is optional.
    • Parametric vertical coordinates use formula_terms.
    • CF has no full/half-level concept. The CF-native link between levels and interfaces is the bounds of the level coordinate (§7.1.4, Example 7.3). Equating the two is an inference, not CF text.
  • Cells:
    • bounds add a trailing vertex dimension (§7.1);
    • cell_measures (area/volume, §7.2);
    • cell_methods (§7.3) say whether a value is a point value (point) or a cell aggregate (area: mean); methods apply in order. This sampling/aggregation metadata is independent of mesh placement: both can be face-located.
  • Domain construct (§5.8, since CF-1.9): “A domain describes data locations and cell properties.” A domain variable describes a domain “in the absence of any data values”. In the data model (Appendix I), a field is a data array plus a domain, and the domain is “the only metadata construct that may also exist independently of a field construct”.
  • Meshes in CF (§1.6 and §5.9, since CF-1.11): UGRID 1.0 is incorporated by reference.
    • A data or domain variable binds to a mesh by reference, through mesh plus location (or location_index_set).
    • Otherwise, binding to a domain is structural: shared dimension names plus attributes.
    • Appendix I: whether two domains share a mesh “may be reliably determined by inspection”. Domain identity in CF is structural, not nominal.
  • Staggering: CF-1.13 never mentions SGRID or staggering. UGRID itself notes that CF offers no specific support for staggered data.
  • Ragged data:
    • compression by gathering (§8.2);
    • contiguous and indexed ragged arrays for discrete sampling geometries (§9.3).
    • UGRID connectivities nevertheless use padded dense arrays.

6. “Every field should know its mesh”

6.1 Where the idea appears

In this knowledge base:

  • Conventions appendix §5: stated outright, with UGRID/SGRID’s per-variable mesh=/grid= as the precedent.
  • Connectivities as types, Binding model (“one table per declaration per binding context”) and open question 2 (the multi-table case): the design choice that leaves a field without a mesh, and its consequence.
  • Dependent-typing appendix §7 (parameter or index, brands) and “Same type ⇒ same table” (mixing meshes is out of scope and would need a mesh-level brand).
  • Mesh proposal: “each field carries a per-entity valid-depth” and the open question about a “mesh-aware field”.

In the conventions and libraries:

  • UGRID mesh + location, SGRID grid, CF-1.11 §5.9;
  • uxarray .uxgrid;
  • coordax Field.axes, whose coordinates can carry a mesh;
  • xarray: no equivalent.

6.2 Why each system wants it

SystemRationale
UGRID / SGRID / CFInterpreting files: a file may hold several meshes, and an n_face index means nothing without its topology.
uxarrayConvenience: methods on a field (integration, gradients, aggregations, plotting, regridding) need geometry and topology without being passed them.
coordaxSafety: exact alignment is checked at trace time.
Conventions appendix §5Telling tables apart when there are several meshes or rewritten tables.
Mesh proposalPer-field halo-validity state for automatic exchange placement.
Dependent-typing appendixPreventing a field computed on mesh A from being consumed on mesh B.

6.3 What a mesh is in each system

SystemThe mesh isTwo meshes are the same whenA field is tied to it by
UGRIDa placeholder variable naming connectivity arrayssame variable namemesh="Mesh2"
CF data modela domain construct (plus a domain topology since CF-1.11)inspection (structural)structural binding, or mesh reference
coordaxa frozen, hashable Coordinatevalue equality (part of the cache key)Field.axes
uxarrayGrid: UGRID dataset plus derived connectivities and geometry, mutableis, else content equality.uxgrid (rarely checked)
gt4py todaythe offset_provider dict—nothing

6.4 Dependent-typing reading

“A field knows its mesh” moves g from a parameter of the call to an index carried with the field (appendix §7):

  • uxarray: a UxDataArray is literally a Σ pair (Grid g, data over Fin<g.n_face>). Neither half of the dependency is enforced (sizes, arithmetic).
  • coordax: makes the mesh a static index checked at trace time, at the cost of one compilation per mesh.
  • UGRID: makes it an index by name, the unbranded case.
  • gt4py today: keeps it a parameter. That is what lets one compiled program serve many meshes, and why mixing meshes goes undetected.

The proposals in the main note sit on this spectrum: A keeps a parameter plus a runtime brand; B and C carry the logical mesh with every field.

7. Precedents for global vs local semantics

  • Global semantics:
    • PSyclone/LFRic: the algorithm layer is written as if serial; the PSy layer generates loop bounds and halo exchanges.
    • Legion/Regent: partitions with set algebra.
    • Chapel’s global-view arrays: the halo is a cached “fluff” overlay.
    • The FD-syntax note’s surface (“halo exchange is never written by the user”).
  • Local semantics (SPMD):
    • MPI codes generally;
    • ICON (sync_patch_array);
    • Atlas (haloExchange on a partition’s function space);
    • PETSc (DMGlobalToLocal scatters a global vector into a ghosted local one);
    • FMS/NEMO compute vs data domains;
    • gt4py and ICON4Py today: gt4py programs see local connectivities, and ICON4Py places exchanges.