Migrate to the class-based Dimension API (GridTools/gt4py#2844)

[havogt]

Not for merge. This branch pins an unmerged, still-rebasing gt4py PR. It exists to answer
"does GridTools/gt4py#2844 require changes in icon4py, and is the new design good?" and to feed
that answer back to #2844's author.

What #2844 does

A concrete dimension becomes a class and an index along it an instance of that class — the shape
enum.Enum uses. gtx.Dimension is no longer a class but an alias for type[DimensionIndex],
common.NamedIndex is deleted, and a dimension's name moves from .value to .tag (.value
now means an index position).

Does icon4py need changes? Yes

Without them the tree does not import: class KDim(gtx.Dimension, kind=...) fails, because
gtx.Dimension is an alias.

class X(gtx.Dimension, …) → gtx.DimensionIndex	21
value = "Cell" → tag = "Cell"	20
type[gtx.Dimension] → gtx.Dimension (the alias is already type[…])	217
gtx.Dimension(<str>) → gtx.dimension(<str>)	3
dim.value → dim.tag	12

isinstance(…, DimensionMeta) predicates are unchanged and still correct.

Verification

• mypy — no issues across 444 source files, on both 2.1.0 and 2.3.1.
• pytest -n0 --datatest-skip over model/common/tests/common/{grid,states,decomposition,interpolation},
  model/driver/tests/driver/unit_tests, bindings/tests, tools/tests, and two dycore stencil
  tests covering sparse E2C access and a scan_operator — 602 passed, 129 skipped, 3 xfailed.
• Every pre-commit hook passes.

Not run: datatests, MPI tests, GPU/dace/gtfn backends, the full stencil suite.

Feedback for #2844

The redesign is a clear improvement. It dissolves rather than patches the two worst problems
of the previous revision: an overloaded __new__ returning a foreign type, which made the
codebase check differently on mypy 2.1.0 vs 2.2.0 and produced a diagnostic naming a type as
incompatible with itself. Both are gone because IDim(0) is ordinary instantiation. The
migration is mechanical and the checker confirms it in one pass.

Four things worth the author's attention, in order:

1. .value → .tag is invisible to the type checker. DimensionIndex declares
   value: int as an instance attribute, so reading it on the class type-checks fine; only
   the metaclass property catches it, at run time, once per executed path. The full mypy gate
   here was green with all twelve reads still wrong — the test suite found them, and six were in
   MPI paths that a non-MPI run would never have reached. The AttributeError itself is
   excellent (it names .tag and the class/instance distinction); the problem is that nothing
   finds the call sites for you.
2. FieldOffset.value and Dimension.tag now diverge, where both used to be .value. Code
   holding either must now know which it has. In this repo a list literally named
   relevant_dimension holds FieldOffsets — the split turned a latent naming bug into a
   crash.
3. The class-declaration error got worse at ab5e8d5a0. class KDim(gtx.Dimension, kind=…)
   — the single most likely downstream edit — was TypeError: KDim.__init_subclass__() takes no keyword arguments and is now TypeError: typealias() takes at most 3 arguments (4 given),
   which names a callable that appears nowhere in user code and no longer names the class.
   Neither points at DimensionIndex.
4. DimensionMeta is still not exported from gt4py.next. isinstance(x, gtx.Dimension)
   raises, so DimensionMeta is the only way to ask "is this a dimension", and it is reachable
   only through gt4py.next.common. One __all__ entry.

Already fixed upstream after earlier rounds of this feedback: Dimension("X") used to return
<class 'str'> silently (a plain alias forwards a call to __origin__); the PEP 695 form at
ab5e8d5a0 makes it a TypeError.

Before this can merge

• Revert the [tool.uv.sources] gt4py pin (first commit) once #2844 lands in a release.
• Re-verify against the merged revision. The pin here is fefb8e213; #2844 has rebased three
  times in three days and is currently DIRTY, so the head has moved on.

🤖 Generated with Claude Code

[github-actions]

When developing, you can test your changes on CSCS CI before merge with the default pipeline: cscs-ci run default. This will run a default subset of tests.

You can pass options to override pipeline variables, for example:

• cscs-ci run default;BACKENDS=gtfn_cpu;LEVELS=unit
• cscs-ci run default;MODEL_SUBPACKAGES=common:driver;SESSIONS=model
  Avoid running the pipeline for all tests when you are developing.

Available options are:

• SESSIONS: model, model_mpi, or tools (correspond to nox sessions)
• MODEL_SUBSETS: datatest, basic, or stencils (correspond to nox session selections)
• MODEL_SUBPACKAGES: subpackages for non-MPI tests (last component, e.g. diffusion, driver)
• MODEL_MPI_SUBPACKAGES: subpackages for MPI tests (as above)
• BACKENDS: backends
• GRIDS: grids for stencil tests (simple, icon_regional, or icon_global)
• LEVELS: testing level for non-stencil tests (unit or integration)

For each option, all can be used as a shorthand for all possible values of that variable, e.g. LEVELS=all.

See scripts/python/generate_ci_pipeline.py and noxfile.py for available values for each option.

The all pipeline can be run with cscs-ci run all. This will run all icon4py tests in CSCS CI which can be expensive. This pipeline runs on a schedule on main, and can be run when extensive validation is needed (e.g. before releases).

Merging

Once your PR is approved and ready for merging, add it to the merge queue. The merge CSCS CI pipeline will run automatically on the merge-queue branch and must pass before the PR is merged. A dummy merge check will be triggered on the PR itself since it's required to add a PR to the merge queue.

Optional Tests

To run benchmarks you can use:

• cscs-ci run benchmark-bencher

For more detailed information please look at CI in the EXCLAIM universe.