Frozen-Soil
- NoahFrozenSoil
model
land_surface
noah
The frozen-soil phase-change sink of WRF's unified Noah land-surface model, as instantaneous tendencies: SUBROUTINES TBND, TMPAVG, FRH2O and SNKSRC of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2), which HRT calls for every soil layer that holds ice or lies below freezing. Four pieces. (1) TBND interpolates the temperature to each layer's LOWER boundary, linearly between the layer's own centre and the next one down, with the deepest layer reaching towards tbot at the mirrored depth 2 z_deep - ze[NLEV+1]. (2) TMPAVG forms the layer-average temperature from the boundary triple (tup, tm, tdn) with the profile CLIPPED AT THE FREEZING POINT: it is a piecewise average over the eight orderings of the three temperatures about t0, and the clipping is what pins a partly frozen layer on the melting plateau instead of letting a linear average carry it through. (3) FRH2O gives the liquid water that can coexist with ice at that temperature -- the freezing-point depression relation (psisat g/hlice)(1 + ck swl)^2 (smcmax/(smc - swl))^bx = -(tavg - t0)/tavg, solved for the frozen fraction swl, with free = smc - swl. (4) SNKSRC converts the layer's energy imbalance into the water that actually changes phase and the latent heat that absorbs. TWO THINGS HERE ARE NOT WHAT THEY LOOK LIKE. FIRST, FRH2O IS NOT A ROOT-FIND AND MUST NOT BE ITERATED TO CONVERGENCE (FORTRAN_BUGS N95). Its loop exits as soon as ONE Newton increment falls below 0.005, seeded from swl = smc - sh2o, so the answer is an early-exit iterate that leaves a residual of up to 2e-3 in the scheme's own relation -- about 3e-4 relative in liquid water, three orders above the reference precision. A converged solver would therefore NOT reproduce WRF. Measured over the 332 layer-calls of the cold-season reference set, the loop exits after ONE iteration in 257 calls and TWO in the remaining 75, and never more; this component therefore writes the two Newton steps out in closed form and selects between them with WRF's own convergence test, which reproduces WRF exactly (4e-12 over all 332 calls) and needs no recurrence. The observed `third_iteration_needed` fires if a state ever demands more, and is zero throughout the reference set -- that branch is UNTESTED, not merely unused, as is FRH2O's Flerchinger fallback, which never runs because Newton converges in at most 2 of its 10 allowed iterations. SECOND, THE SINK HAS A CLEAN dt -> 0 LIMIT THAT THE FORTRAN HIDES. SNKSRC forms xh2o = sh2o + qtot dt/(rho_w hlice dz) and returns tsnsr = -rho_w hlice dz (xh2o - sh2o)/dt, so when nothing clamps, tsnsr = -qtot EXACTLY and at any dt: the phase change absorbs the entire energy imbalance and the layer's temperature tendency is exactly ZERO. That is the freezing plateau, and it is the whole point of the routine. The clamps confine xh2o to the closed interval between sh2o and free, so the change is admitted only while it moves the liquid water TOWARDS its equilibrium value; as dt -> 0 that reduces to a switch on the sign of qtot against the sign of free - sh2o, which is what this component writes. The liquid-water tendency the phase change contributes is then qtot/(rho_w hlice dz), which equals minus the layer's flux-driven temperature tendency times hcpct/(rho_w hlice). HRT EVALUATES NONE OF THIS on a layer that holds no ice and lies, with both its boundaries, at or above t0; the observed `sink_evaluated` reproduces that guard, and where it is zero the tavg and free reported here are values WRF never forms. NOT TRANSCRIBED: FRH2O's Flerchinger fallback (see above) and the ITAVG = .false. path of HRT, which uses stc in place of tavg and which WRF hard-wires to .true. WHAT IS AND IS NOT TESTED HERE. tbnd, tavg, free and the evaluation guard reference cleanly against the cold-season replay and are pinned to 4e-12 or exact. The SINK ITSELF -- tsnsr, dsh2o_dt_phase and the corrected dstc_dt -- is AUTHORED BUT UNPINNED, because SNKSRC gives no reference step at which it can be measured: the value is recovered from a difference that cancellation destroys below about 1e-3 s, while above about 1e-2 s the interval clamp binds and the answer becomes a finite-dt artefact (FORTRAN_BUGS N97, which records what instrumentation would fix it). Those three observeds are UNTESTED, not merely unused. This component consumes the flux-driven part of the soil-heat tendency and returns the corrected one, so a consumer mounts it AFTER soil_heat.esm and integrates dstc_dt from here, not from there. Consumer-supplied column fields are rewrite-target ops `input_<name>` lowered by the consumer, in the inline tests through per-test expression_template_imports libraries generated by tools/fill_tests.py.