SHOC host-interface audit: EAM (shoc_intr.F90) vs EAMxx (eamxx_shoc_process_interface)

New companion page: SHOC call-flow map — the Fortran flow as one annotated diagram, with the C++ home of each piece identified alongside.

Systematic, formula-by-formula comparison of the two SHOC host interfaces, on branch maint-3.0-scm-mchinita-shoc_in_and_out_cpp. Method: one full extraction pass over both sources, followed by an independent adversarial verification pass that re-checked every claim against the code (two claims were corrected by it; noted below). Line-number shorthand: :NNN = components/eam/src/physics/cam/shoc_intr.F90 (EAM); cpp:NNN / hpp:NNN = components/eamxx/src/physics/shoc/eamxx_shoc_process_interface.cpp / .hpp (EAMxx; the .hpp header holds the SHOCPreprocess/SHOCPostprocess structs where most input/output formulas live — see the file map below). Full paths: components/eam/src/physics/cam/shoc_intr.F90 (EAM) and components/eamxx/src/physics/shoc/eamxx_shoc_process_interface.cpp/.hpp (EAMxx). Companion pages: C++ vs Fortran shoc_main validation, exp1 vs exp2 equivalence. 2026-07-07, Maria Chinita + Claude Fable 5.

0. File map: where each layer lives

The two codes split the same two layers (host interface / SHOC physics) across files differently. In EAM each layer is one Fortran file. In EAMxx the interface is one module split across a header (.hpp, which holds the SHOCPreprocess/SHOCPostprocess structs with the input/output formulas — C++ template/Kokkos code must live in headers) and an implementation file (.cpp: initialize/run orchestration, TMS, checks); the physics is spread over shoc_functions.hpp plus 54 files in impl/, one per Fortran subroutine (e.g. the nadv loop is impl/shoc_main_impl.hpp). The interface pair contains no physics; the impl/ headers contain no interface code.

1. Identical between the two interfaces

All shared point-wise formulas are identical or trivially equivalent: inv_exner (EAM :879 / hpp:92), θ (:897 / hpp:112), θ_l (:898 / hpp:113), thv = θ(1+z_virq_v−q_c) (:899 / hpp:114), q_w=q_v+q_c (:891-893 / hpp:108), wm_zt=−ω/(ρg) (:926 / hpp:120), rrho (:925 / hpp:119), rrho_i interpolation (:938 / hpp:149), surface-flux conversions (Exner factor on the heat flux only, surface-interface density, no sign flips; :943-951 / hpp:152-158; field map shf↔surf_sens_flux, cflx(:,1)↔surf_evap, wsx/wsy↔surf_mom_flux(:,0/1)), TKE floor at 0.0004 m²/s² (:901 / hpp:97), q_v=q_w−q_c recovery (:1119 / hpp:287), cldfrac clamp to 1 (:1092 / hpp:289), relvar ↔ inv_qc_relvar (same q_c²/q_c²̄ with [0.001,10] clamp; :1220 / hpp:293-300), dx from the same WGS84 ellipsoid formula (:1415-1430 / cpp:452-467).

All shared tunings have identical defaults (namelist_defaults_eam.xml:831-844 vs namelist_defaults_scream.xml:223-234): thl2/qw2/qwthl2/w2tune=1.0, length_fac=0.5, c_diag_3rd_mom=7.0, lambda_low/high/slope/thresh= 0.001/0.04/2.65/0.02, Ckh=Ckm=0.1. The stable-regime Ckh_s/Ckm_s are namelist parameters in EAM (0.1) and hardcoded to the same 0.1 in the C++ kernel (shoc_eddy_diffusivities_impl.hpp:39-40) — numerically identical, only non-configurable in EAMxx.

Non-issue confirmed by the verification pass: there is no wet/dry mixing-ratio mismatch. EAM's Q is specific humidity (wet) used without conversion; P3's condensates are registered with the default mixtype='wet' (constituents.F90:157); EAMxx uses wet kg/kg throughout.

2. Structural differences (the ones that matter)

Subcycling side by side (row 4 illustrated)

Both models run SHOC at a few-minute effective timestep; they just nest the loops differently. EAM: physics step → macmic loop (turbulence↔microphysics alternation) → optional SHOC-internal nadv. EAMxx: atmosphere step → driver-level subcycling of the whole mac_aero_mic group, nadv pinned to 1. The in-and-out runs exploit EAM's innermost lever (macmic=1, shoc_timestep=60 → nadv=360), which the standalone C++ driver replicates by looping shoc_main itself.

3. Only in EAMxx (locations)

• TMS hook: apply_turbulent_mountain_stress() cpp:560-577, gated by apply_tms (default false, cpp:67; toggle at cpp:488): subtracts drag·u_bot/ρ_i,bot from upwp/vpwp_sfc before shoc_main. In EAM, TMS is applied in the vertical_diffusion/CLUBB paths, never in the SHOC branch (compute_tms imported at :590 but unused).
• check_flux_state_consistency: cpp:580-627 (default false, cpp:222,492). If negative surf_evap would exhaust bottom-level vapor, removes the mass column-proportionally and zeroes surf_evap — i.e. it mutates an input flux (which is why surf_evap is registered Updated, cpp:62). No EAM analog.
• Postcondition property checks: cpp:411-422. Bounds on T_mid[100,500], qc[0,0.1], winds[±400], pblh≥0, cldfrac[0,1], tke≥0, and qv[0,0.2] with repair=true (clips negatives).
• cldfrac_liq_prev (hpp:89, cpp:90) and column-conservation flux fields (cpp:117-122, hpp:312-317).
• Initial-run seeding: tke=4e-4, tk=0, sgs_buoy_flux=0, cldfrac_liq=0 (cpp:310-316).

4. Only in EAM (locations)

• Cloud-fraction macrophysics: alst/aist/ast/qlst/qist (:1237-1310), deep-convective fraction via dp1·log(1+500(cmfmc−cmfmc_sh)) (:1265), concld (:1276), liqcf_fix/alst_o (:1232-1250). EAMxx delegates all of this to the separate cldFraction process.
• Deep-convection detrainment + host energy accounting: det_s/det_ice with a 268.15/238.15 K liquid/ice ramp (:1158-1213); feeds check_energy_chng in physpkg (physpkg.F90:2900-2916).
• pbuf interface interpolations of tk→kvm, tkh→kvh, tke→tke_zi (:1106-1111) for downstream aerosol activation/microphysics; EAMxx keeps eddy diffusivities on mid-levels.
• relvar + accre_enhan to pbuf (:1214-1222; accre_enhan has no C++ analog).
• macmic context (macmic_it, cld_macmic_num_steps args :565,607-608) and the l_turb_standalone in-and-out harness (:982-1077) — the latter is what our standalone C++ driver replicates on the EAMxx side.
• History flux outputs converted to W/m² (×ρc_p or ×ρL_v, :1345-1357); EAMxx exposes raw kinematic moments.

The EAM side at a glance: everything around SHOC that is not SHOC itself

One vertical pass through shoc_tend_e3sm (called once per macmic iteration), with the raw SHOC physics collapsed into a single box (step 6). Colors: teal = interface operations (shoc_intr.F90); purple = shoc.F90 operations outside the nadv loop (shown bit-for-bit neutral for SHOC's prognostics on the exp1 vs exp2 page); amber = in-and-out mode only; gray = state handling / raw SHOC. Steps 11-13 are the EAM-only machinery that EAMxx delegates to separate processes (section 4).

Where each step lives (EAM diagram above):

The EAMxx side at a glance: the same map for run_impl

The twin diagram for EAMxx, same visual grammar (raw SHOC collapsed, same colors). Structural contrasts with the EAM diagram above: no state copy (step 1 — single field-manager copy, which is why the state/state1 class of inconsistency cannot exist here), the amber extras EAM does not have (TMS hook, flux check, property checks), in-place updates instead of ptend (step 13), and the final gray box lists what moved out of SHOC entirely.

Where each step lives (EAMxx diagram above; cpp/hpp = eamxx_shoc_process_interface, impl = impl/shoc_main_impl.hpp; line numbers for this branch):

5. Flags and minor findings

• Fork-specific change: this branch deliberately passes state1%pmid/pint (updated state) to shoc_main where upstream passed state%pmid/pint (original line kept commented, :1039-1041). Worth confirming with the team that this is intended and documented.
• EAMxx micro-bug: hdtime is declared Int (hpp:499) but assigned a double dt (cpp:499). Harmless today (nadv is always 1) but lossy if the internal-subcycling TODO (cpp:496-498) is ever implemented. Candidate upstream fix.
• Mixed wet/dry constituent types can coexist inside the diffused tracer bundle (aerosols are dry-type); both models diffuse them without conversion, so this is symmetric — not an EAM-vs-EAMxx difference.

6. Implications for the ERF integration (stage 2)

For coupled single-column comparisons (E3SM-SCM vs ERF with other parameterizations off), the interface-level divergence sources reduce to rows 1 and 2 of the table (source of heights/dz and of dse — ERF will supply its own grid heights, as EAMxx does) plus the dt≤300 s per-call cap. Row 3 is inert for DYCOMS (no active tracers), TMS stays off, property checks rarely trigger, and ptend-vs-in-place is mathematically equivalent. The EAM-only cloud-fraction/detrainment machinery (section 4) is inert when microphysics and convection are off.

Appendix: why the C++ code is organized this way (a primer)

For readers coming from Fortran. Two file types exist: a .cpp is like a .F90 (compiled once, cheap to change); a .hpp with code in it is like an .inc (text pasted into every file that includes it — recompiled everywhere, and changing it recompiles all includers). C++ templates ("code with blanks") let one source text serve several concrete variants — double vs single precision, vector pack 16 vs 1, different consumers (the model, the BFB tests, the standalone driver, ERF) — and the compiler must see the full definition wherever it creates a new filled-in variant. That leaves two options: keep templated code in headers (so any consumer can instantiate any variant — the impl/*.hpp choice, right when the set of variants is open-ended), or pre-instantiate a fixed list of variants in a .cpp (exactly what eti/ does for the standard variant, as a compile-time optimization). Templates are also contagious: everything shoc_main calls inherits its blanks, so the whole physics call tree lives in impl/*.hpp. Everything concrete (run_impl, the TMS hook, the checks) goes to .cpp — and still runs on GPU, since CPU-vs-GPU is decided per build for all files; that was never what the blanks are for. The governing rule is economic: .cpp whenever possible (fast builds), .hpp only when required (templates).

Directory map of components/eamxx/src/physics/shoc/: top level = the interface (eamxx_shoc_process_interface.*), the physics declarations (shoc_functions.hpp), the Fortran↔C++ bridges (shoc_iso_c/f.f90, shoc_functions_f90.*) and the test harness (shoc_main_wrap.*, shoc_f90.*, shoc_ic_cases.*); impl/ = the physics itself, one templated header per shoc.F90 subroutine (54); eti/ = explicit template instantiations of the standard variant, a compile-time optimization (42); disp/ = per-subroutine kernel launchers for the optional SCREAM_SHOC_SMALL_KERNELS build mode (15); tests/ = per-subroutine BFB unit tests, the shoc_run_and_cmp regression test, and the standalone shoc_in_and_out driver with its README (73).