Add the tmx package, its configuration and static states

[havogt]

The tmx port (#1359, @jcanton) is ~16k lines across 155 files. This is the first of a series carving it into independently reviewable pieces: the package plus everything that needs no operators. Each later PR adds one subcomponent with its own datatest (diagnostics, scalar and momentum diffusion, energy update). Prescribed surface fluxes, including their configuration options, are in #1458, stacked on this one.

What is here

• The package: pyproject.toml, README, workspace member, tach module (depends on common only), nox session, CI matrix entry.
• TmxConfig and its enums, in tmx/config.py, so that reading the configuration does not import every stencil package the granule does.
• Static states: TmxMetricState and TmxInterpolationState.
• Metrics factory additions the states need: wgtfacq1_c/e, the inverse layer thicknesses (cells on half levels, edges on full levels), geopotential and height above ground — each with a savepoint test in test_metrics_factory.py.
• Quadratic extrapolation weights in gt4py: wgtfacq_c/e and the new wgtfacq1_c/e replace the numpy implementations.
• One savepoint (tmx_init) and the test-data version bump.
• unnamed_index in the common config options (positional derived-type namelists), with its tests in common.
• ISO-8601 duration parsing moved to common/utils/time_utils.py; the driver had its own copy.
• get_grid_geometry keys its cache on the number of levels as well, since two experiments share the R02B04 grid file.

Not here

The states that flow between subcomponents (TmxInputState, TmxDiagnosticState, …) and everything with its first consumer in a later PR arrive with that PR.

Differences from #1359

• Half-level fields are typed on KHalfDim (Port tmx turbulence #1359 predates Use gt4py staggered dimensions for KHalfDim #1429); the port's re-tagging helper is gone.
• edge_cell_length comes from EdgeParams (refactor(common): EdgeParams as a dataclass with explicit optional members #1462) rather than the metric state.

Testing

gtfn_cpu, -n0. The embedded backend is not evidence here: several of these tests are xfail on it.

suite	result
test_metrics_factory.py	85 passed
height above ground + geopotential, after the reference change	2 passed
weight factors, common math, common utils	45 passed
tmx, driver unit tests	42 passed
pre-commit	pass

🤖 Generated with Claude Code

https://claude.ai/code/session_01QVSWPQauF9gNjADtuSTjxF

[OngChia]

I am still thinking about the bunch of tests of tmx config. No clue yet. Could @DropD have a look at those config things?

[OngChia]

I did not know this.
So, just to confirm, we will create CellKField fields such as the quadratic extrapolation coefficients wgtfacq_c or wgtfacq1_c with only three levels in the vertical coordinate.

[havogt]

Was extracted into #1463

[OngChia]

This workaround of cyclic permutation of vertical levels to compute simple quadratic extrapolation weights seems not very ideal and hard to swallow. I guess this is because of gt4py limitations.

[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.

Multiple values can be given to each option with : used as the separator (; separates options and , separates pipelines).

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.

[yiluchen1066]

Thanks for the PR! I did not find something need to be changed urgently. Mostly minor things. We can merge this one pretty soon!

[yiluchen1066]

Suggested change

Note: Called ``solver_type`` in ``mo_turb_vdiff_config.f90``.

No need to keep this, also for the rest of the codes.

[yiluchen1066]

shall we rename this to TmxSolverType?

[yiluchen1066]

Suggested change

	"""
	Construct the configuration from the echoed ICON namelist.
	``aes_vdf_nml`` is a derived-type namelist (``t_vdiff_config``), which
	ICON echoes as an anonymous positional array of the member values in
	declaration order, so the options are located by ``unnamed_index``
	(pinned to mo_turb_vdiff_config.f90) instead of by name. Only the
	first domain is read. The guards below make a change of the Fortran
	type fail loudly instead of silently mis-assigning values.
	"""
	"""
	Build the configuration from the echoed ICON namelist.
	ICON writes ```aes_vdf_config``` values in Fortran member order, without names.
	We read the first domain using each options's ```unnamed_index```. The checks below
	help detect changes to the expected Fortran layout
	"""

let's simplify the doc string a bit.

[yiluchen1066]

Suggested change

	# number of members of the Fortran t_vdiff_config derived type
	# (mo_turb_vdiff_config.f90); the echoed aes_vdf_nml namelist holds this
	# many values per domain, in declaration order. Must be kept in sync with
	# the 'unnamed_index' positions of the options above.
	num_members = 42
	# position of 'use_tmx' in t_vdiff_config, used as an order canary
	use_tmx_index = 22
	# Layout of t_vdiff_config in mo_turb_vdiff_config.f90
	# Keep these values and the options' unnamed_index positions in sync
	num_members = 42
	use_tmx_index = 22

[yiluchen1066]

I was testing GPT-6 Astra, and it caught this here:

Suggested change

	values = dict(iter_pairs_from_icon(config_cls, icon_config))
	values.update(overrides)
	return config_cls(**values)

Both dictionaries can contain km_const which caused the error

[yiluchen1066]

Suggested change

	def test_compute_wgtfacq_c(
	@pytest.mark.datatest
	@pytest.mark.uses_concat_where
	def test_compute_wgtfacq_c(

[yiluchen1066]

Suggested change

	def wgtfacq1_c(self):
	# Top-extrapolation coefficients: unlike `wgtfacq_c` (bottom extrapolation, stored
	# surface-first, i.e. reversed w.r.t. increasing k, hence flipped in its accessor),
	# `wgtfacq1_c(jc,k,jb)` with k=1..3 multiplies the full level k counted from the model
	# top (mo_vertical_grid.f90 ll. 955-968), which already matches icon4py's top-down KDim
	# orientation. No flip needed.
	return self._get_field("wgtfacq1_c", dims.CellDim, dims.KDim)
	def wgtfacq1_e(self):
	# No flip, see `wgtfacq1_c`. Usage in mo_vdf_atmo.f90 (interpolate_normal_velocity_
	# edge_interface, ll. 1247-1250): vn_ie(je,1,jb) = sum_k wgtfacq1_e(je,k,jb)*vn(je,k,jb).
	return self._get_field("wgtfacq1_e", dims.EdgeDim, dims.KDim)
	def wgtfacq1_c(self):
	return self._get_field("wgtfacq1_c", dims.CellDim, dims.KDim)
	def wgtfacq1_e(self):
	return self._get_field("wgtfacq1_e", dims.EdgeDim, dims.KDim)

let's remove the docs here

[yiluchen1066]

shall we move this to model/testing/datatest_utils since it uses the helper function get_path_for_experiment and potentially other components would also need this helper