feat[next]: staggered fields

[tehrengruber]

A staggered dimension is a dimension sitting at the half-integer positions of a base dimension. For example in a cell centered 2d cartesian grid with cells located at I, J the edges are located at I - ½, J and I, J - ½. Differentiating between staggered and non-staggered dimensions avoids accidental errors when fields defined on different entities are combined and improves readability for users by staying close to the mathematical formulations.

Let i_field for simplicity be a 1d field of cell values defined on I and IHalf the corresponding staggered dimension of edges between those cells then

• i_field(IHalf + 0.5) → maps edges to the cell value above (i−½)+½ = i
• i_field(IHalf − 0.5) → maps edges to the cell value below (i−½)−½ = i−1

           ┊      ●      ┊       ●      ┊      ●      ┊
 I               -1              0             1
 IHalf    -1½           -½             +½            +1½

Similary, let ihalf_field be defined on I - ½ then

• ihalf_field(I + 0.5) → maps cells to the edge above i+½
• ihalf_field(I − 0.5) → maps cells to the edge below i−½

Storage

ihalf_field.ndarray[idx] holds the value for logical index i = domain.start + idx, which is interpreted as sitting at i − ½. In the example above, IHalf(0) therefore sits at 0 − ½ = −½, i.e. it is the index of the edge just below the cell I(0). The memory layout is identical to any normal field; the "half" is purely how the index is interpreted geometrically.

Replaces #2339

[havogt]

GLM 5.2: Review of the staggered-fields feature, run against the current head (df11778e2). Most of the earlier round (mixing restriction, _collect_dimensions_from_params block sizes, extract_connectivity_args device guard, field(Off[idx]) removal) is resolved in the rebased tree — thanks.

One item that was reported earlier and marked resolved (connectivity_for_cartesian_shift's bare assert half == 0.5, tehrengruber-ai "Done (c7ad10812)") does not appear at this head, so the fix looks to have been lost during the rebase. Details in the inline comment at common.py:1468.

Remaining items are mostly ADR completeness, error-message formatting, and a few test gaps for the new code paths. No other correctness issues found — the half-integer offset arithmetic is correct for all sign/direction combinations I checked, and the dace/gtfn/embedded backends handle relocation consistently.

[havogt]

GLM 5.2: The "round-trips through all representations for free" claim isn't quite accurate — backends actively handle the prefix:

• gtfn (itir_to_gtfn_ir.py:_add_staggered_aliases, ~line 200) turns every staggered tag into a C++ alias of its base dimension's TagDefinition, and visit_AxisLiteral (~line 401) emits node.type.dim.value instead of node.value.
• nanobind (nanobind.py:212) uses common.as_non_staggered(dim).value so the generated binding references the base dimension name.

A contributor adding a new backend needs to know the prefix must be handled at code-generation boundaries. Suggest adding a short "Backend handling" subsection.

[tehrengruber]

@tehrengruber-ai Let's remove the common.as_non_staggered(dim) in the bindings unless there is a reason this is needed.

[tehrengruber-ai]

Addressed in 544232d: softened the 'round-trips for free' wording and added a 'gtfn backend' section describing the alias handling.

[havogt]

Please check my questions. No need to do anything if you think current state makes sense.

[havogt]

Index 24 and 25 is taken in the meantime.

[havogt]

Suggested change

	- [0024 - Staggered Dimensions](0024-Staggered_Dimensions.md)
	- [0026 - Staggered Dimensions](0026-Staggered_Dimensions.md)

[havogt]

LocatedNode makes sense?

[havogt]

Should is_staggered and as_non_staggered be part of the public API? Do you have a use-case?