Integrate tmx into phys driver

task-46ea60 · in Plug in turbulence - TMX

Status: Thinking — at the foot of the hill Shaping — halfway up the hill Ready — at the top of the hill In progress — halfway down the hill Done — at the bottom, over the hill Shelved — off the hill Somebody is building this in the cycle it was bet into — an overrun is re-bet, not extended.
Priority: Medium
Appetite: 4.0 person-weeks A budget in person-weeks, not an estimate: what this is worth, not how long it takes.
Tags: —
Owner: yiluchen1066
Assignees: yiluchen1066
Reviewers: OngChia, jcanton, msimberg
Review waived: —
Parent: Plug in turbulence - TMX
Blocked by: Physics Driver refactor
PRs: C2SM/icon4py#1360
Cycle: — A bet is for one cycle. Work that overruns is re-bet, not extended by default.
Start date: 13.07.2026
End date: —
Scheduled: 2026-07-13 → 2026-08-07
Blocks: —
Progress: 1/2 items

Problem

The tmx granule is ported (#1359) but ships standalone, with its own state objects and savepoint tests. It is not wired into anything that runs. The PhysicsDriver already runs muphys as a Component; tmx needs the same treatment.

Solution

Wrap the granule as a second Component behind the existing driver protocol, using the adapter shape muphys uses, so that re-merges of the still-moving #1359 stay clean. The data flow mirrors muphys: collect_inputs binds the frozen EntryState and derives air_mass and cv_air and runs the surface-flux provider, the component call wraps tmx.run() which returns tendencies, and the tendencies are accumulated and applied once.

Verified by running a full APE_aes with muphys and tmx against exclaim_ape_aesPhys_v08.

Progress

#1360 opened, the tmx ComponentState adapter on top of the two-layer state design; v08 datatest passes in assert mode with measured tolerances
Merge, which waits on #1359 (its base branch) and on #1436

#1360 is based on port_turbulence rather than on main, so it lands only after the tmx port itself does. The two-layer physics state it builds on is #1436, which is cycle 38's own bet.

## Problem

The tmx granule is ported (#1359) but ships standalone, with its own state
objects and savepoint tests. It is not wired into anything that runs. The
PhysicsDriver already runs muphys as a Component; tmx needs the same treatment.

## Solution

Wrap the granule as a second Component behind the existing driver protocol, using
the adapter shape muphys uses, so that re-merges of the still-moving #1359 stay
clean. The data flow mirrors muphys: collect_inputs binds the frozen EntryState
and derives air_mass and cv_air and runs the surface-flux provider, the component
call wraps tmx.run() which returns tendencies, and the tendencies are accumulated
and applied once.

Verified by running a full APE_aes with muphys and tmx against
exclaim_ape_aesPhys_v08.

## Progress

- [x] #1360 opened, the tmx ComponentState adapter on top of the two-layer state
      design; v08 datatest passes in assert mode with measured tolerances
- [ ] Merge, which waits on #1359 (its base branch) and on #1436

#1360 is based on `port_turbulence` rather than on main, so it lands only after
the tmx port itself does. The two-layer physics state it builds on is #1436,
which is cycle 38's own bet.