Noah
- NoahCanopyResistance
model
land_surface
noah
Canopy (bulk stomatal) resistance of WRF's unified Noah land-surface model, SUBROUTINE CANRES of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2), and the plant coefficient pc it is converted into. Jarvis (1976) multiplicative stress form as implemented by Chen et al. (1996): rc = rsmin / (xlai rcs rct rcq rcsoil), with four independent stress factors, each floored -- rcs from incoming solar radiation, rct from air temperature about the optimum topt, rcq from the vapour-pressure deficit at the lowest model level, and rcsoil from root-zone soil moisture. The soil-moisture factor is written here as what the Fortran loop computes: rcsoil = (1/z_root) integral of the layer stress gx over the root zone, gx = clamp((sh2o - smcwlt)/(smcref - smcwlt), 0, 1), i.e. a THICKNESS-WEIGHTED MEAN of the layer stress over the root depth (the Fortran's PART(k) = (zsoil(k)-zsoil(k-1))/zsoil(nroot) gx(k) is dz[k]/z_root gx[k] because WRF's zsoil is negative downward). The integral runs over the whole soil column with the sub-root layers masked out by zc < z_root; a layer centre never coincides with z_root, which is by construction a layer interface, so the mask selects exactly the Fortran's layers 1..nroot. The plant coefficient pc converts rc into the factor that multiplies the LINEARISED Penman potential evaporation to give Penman-Monteith actual transpiration: pc = (rr + delta)/(rr (1 + rc ch) + delta), where rr is the radiative-plus-aerodynamic resistance ratio and delta = (slv/cp) dqsdt2 the saturation-humidity slope in the same units. Frozen-ground extension: WRF passes UNFROZEN soil water sh2o, not total smc, into this routine -- the `SMC` dummy argument of CANRES is bound to SH2O at the call site -- so the component's column input is named sh2o. GATING. SFLX calls CANRES only 'IF ((SHDFAC > 0.) .AND. (XLAI > 0.))' (module_sf_noahlsm.F:749) and otherwise sets rc = 0; this component reproduces that through `canres_called` and its new `shdfac` input, so a bare cell (shdfac = 0, e.g. the BARE category REDPRM zeroes) gives rc = 0 and finite zeros elsewhere instead of the NaN that xlai = 0 or z_root = 0 would put into rcs, rcsoil and rc. The denominators inside the active branch are guarded as well (xlai, and z_root for a vegetation type with no root layers), because an ifelse evaluates both branches. The `rr` here is CANRES's own, built from cp = 1004.5 (module_model_constants) and Noah's rd = 287.04 and sigma = 5.67e-8; it is NOT the `rr` of SUBROUTINE PENMAN, which is a different expression built from PENMAN's own cp = 1004.6 (FORTRAN_BUGS N88). Consumer-supplied column fields (ze, sh2o) 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.
- NoahEvapotranspiration
model
land_surface
noah
Partition of Noah's potential evaporation into its three actual components -- direct soil evaporation, canopy transpiration and evaporation of intercepted canopy water -- SUBROUTINES EVAPO, DEVAP and TRANSP of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2), as called by NOPAC for snow-free ground. Direct soil evaporation edir = fx (1 - shdfac) etp, with the bare-soil efficiency fx = clamp(((smc[1] - smcdry)/(smcmax - smcdry))^fxexp, 0, 1) evaluated on TOTAL top-layer soil moisture. Canopy evaporation ec = shdfac (cmc/cmcmax)^cfactr etp drains intercepted water at the potential rate weighted by the canopy wetness fraction. Transpiration takes what is left of the canopy's share, etp1a = shdfac pc etp (1 - (cmc/cmcmax)^cfactr), and distributes it over the root zone by the Noah root-weighting rule: each root layer's share is gx max(rtdis + gx - sgx, 0), normalised to sum to one, where gx is the layer's moisture stress on UNFROZEN water, rtdis = dz/z_root its thickness fraction of the root zone and sgx the UNWEIGHTED ARITHMETIC MEAN of gx over the root layers. That mean is a per-layer count, not a depth average, and it is what makes the rule redistribute water towards layers that are wetter than the root-zone average; it is written here as the column integral of gx/dz over the masked root zone divided by nroot, which is identically the Fortran's sum over layers 1..nroot. Two quantities are evaluated on DIFFERENT moisture variables and the difference is deliberate in WRF: DEVAP reads total soil moisture smc, TRANSP reads unfrozen soil water sh2o. The canopy-drain limiter ec <= cmc/dt_canopy is a finite-sub-step clip on an otherwise continuous rate, so dt_canopy is A PARAMETER OF THE TENDENCY and not the integrator's step; it is inactive at every state of the reference set (cmc/dt is 2e4 W/m^2 against an ec of at most 121 W/m^2 there), so the tests pin the unclipped branch only and the clipped branch is untested. GATING. EVAPO calls TRANSP only 'IF (SHDFAC > 0.0)' (module_sf_noahlsm.F:1392), and a vegetation type with no root layers (nroot = 0) gives TRANSP empty loops; both must come out as ett = 0, not as the 0 x NaN an ungated 1/nroot or dz/z_root would produce. etp1a and ec are already zero for shdfac = 0, so it is enough that sgx divides by max(nroot, 1) and rtdis is zero for z_root = 0: every gxs is then zero, denom falls back to 1, and et = ett = 0 exactly. When etp <= 0 the whole routine is skipped and WRF reports dew instead: eta = etp, beta = 1 for etp < 0 and beta = 0 for etp = 0, which this component reproduces so that the dew branch is not a silent hole. Consumer-supplied column fields (ze, smc, sh2o) 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.
- 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.
- NoahParameters
model
land_surface
noah
Scheme constants of WRF's unified Noah land-surface model, transcribed from the module- and subroutine-level PARAMETER statements and the GENPARM.TBL scalars of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2). Mounted by every Noah component as subsystem `par` so that no tuning constant is written inline in the physics. Two groups: (a) the thermodynamic constants Noah redefines for itself, which do NOT agree with lib/wrf_constants.esm and must not be taken from there -- Noah's rd = 287.04 against the dynamics' 287.0, Noah's sigma = 5.67e-8 against the dynamics' 5.67051e-8, and, inside SUBROUTINE PENMAN alone, cp = 1004.6 against the cp = 1004.5 that module_model_constants supplies to the rest of the module (FORTRAN_BUGS N88); and (b) the GENPARM.TBL scalars that REDPRM copies into the scheme, whose values are those WRF loaded for the reference runs and are carried in the `*_data` fields of the `noah` dump. Volumetric heat capacities (cair_vol, cice_vol, ch2o_vol) are the SUBROUTINE HRT literals, not the mass-specific cph2o/cpice of the module header; both appear in the scheme and they are different quantities. Group (a) carries the nominal decimal values of the Fortran PARAMETER statements: a real64 kernel build evaluates those literals in double precision, so the nominal value is what a reference replay uses. Group (b) is DIFFERENT -- those numbers reach the scheme through a real32 table array, so the value the scheme uses, and that a real64 replay reproduces, is the SINGLE-PRECISION representation of the table's decimal text. Five of them are not exactly representable and their defaults are therefore the widened singles (cmcmax, salp, refdk, frzk, czil); using the decimal instead puts a 4.7e-8 relative error into cmcmax, which a canopy-wetness ratio near one amplifies into a 1.5e-5 error in the transpiration.
- NoahPotentialEvaporation
model
land_surface
noah
Linearised Penman potential evaporation of WRF's unified Noah land-surface model, SUBROUTINE PENMAN of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2), together with the partial sums rch, rr, t24 and epsca that PENMAN passes back for the rest of SFLX to reuse. Penman (1948) combination form, linearised about the air temperature: epsca = (a rr + rad delta)/(delta + rr), where a = elcp1 (q2sat - q2) is the vapour-pressure deficit expressed as a temperature, rad = fnet/rch + th2 - sfctmp the available-energy term likewise, delta = elcp1 dqsdt2 the saturation slope and rr the radiative-plus-aerodynamic resistance ratio; etp = epsca rch / lvs. Snow blends two latent heats through the snow-cover fraction sncovr: elcp1 and lvs both interpolate between the liquid (lsubc) and the ice (lsubs) value, so that over full snow cover the potential flux is a sublimation. Falling precipitation adds its own sensible-heat capacity to rr -- cph2o for rain, cpice for snow -- and freezing rain adds the latent heat of fusion released on impact as flx2 = -lsubf prcp, which is subtracted from the net radiation. THREE things a consumer must know. (1) The `ssoil` this routine subtracts from the net radiation is NOT the ground heat flux SHFLX returns at the end of the step; it is the flux diagnosed from the INCOMING skin temperature, ssoil = df1 (t1 - stc[1])/(0.5 |zsoil[1]|), which SFLX computes just before the call. (2) PENMAN declares its OWN cp = 1004.6, which disagrees with the cp = 1004.5 that module_model_constants supplies to every other routine in the same module (FORTRAN_BUGS N88); it enters only through rho -> rch. (3) The radiative term of rr is the hard-coded literal 6.48e-8 standing for 4 sigma rd / cp, whose exact value with Noah's own sigma and rd is 6.48048e-8 -- a 7.4e-5 relative difference that this component reproduces by keeping the literal, because the object here is WRF's answer and not the exact one (FORTRAN_BUGS N89). The UA_PHYS canopy-shading branch (flx4, etpn) is not transcribed: it is off in both reference runs and is a separate parameterization. The component is algebraic in the consumer's state and owns nothing.
- NoahSnowCompaction
model
land_surface
noah
Snow-pack compaction in WRF's unified Noah land-surface model, SUBROUTINE SNOWPACK of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2): the densification of an existing pack under its own weight, and the melt water it retains once its surface reaches freezing. THE PHYSICS. Anderson's compaction equation (NOAA Technical Report NWS 19, eq. 3.29) makes the density at a point in the pack grow exponentially in the water equivalent lying above it, at a rate that rises with temperature and falls with the density already reached: d(rho)/dt = rho c1 exp(ctemp tavgc - c2 rho) w. Koren's 1995 approximate solution integrates that over the DEPTH of the pack rather than over time, so the pack-mean density after a step of dtsec is sndens (exp(x) - 1)/x with x = bfac esdcx, and bfac carries the whole of the step length. WRF evaluates (exp(x) - 1)/x through its Taylor series to four terms, because the closed form is 0/0 at x = 0 -- its own comment says so at length. Once the snow surface reaches freezing a second process runs: 13 % of the pack's pore space per day fills with melt water, which relaxes the density towards that of water. The depth is not integrated at all; it is the quotient esd/sndens at the end. HOW IT JOINS AN ODE DOCUMENT. SNOWPACK is an in-place sub-step, not a rate -- Koren's solution is a closed form in the step length and there is no dt-free rate inside it -- so this component takes dtsec as a PARAMETER OF THE SCHEME and exposes `dsndens_dt` = increment/dtsec as the observed a consumer integrating the pack adds, which is the same shape WSM6's operator-split stages use. A mounting document must prescribe dtsec and couple it in; it is not the integrator's step, and the result differs from the dtsec -> 0 limit by xarg/3 + O(xarg^2), measured at 2.2e-6 relative at WRF's own 60 s step. WHY THE INCREMENT IS NEVER FORMED AS A DIFFERENCE. The compaction moves the density by a factor 1 + O(dtsec): 9.4e-5 of it at WRF's 60 s step on the wettest reference column, 4.5e-9 on the thinnest pack, and 7.5e-17 at a 1e-6 s step. Writing the increment as sndens_out - sndens_in therefore returns round-off at any step small enough to be a dt -> 0 reference, and writing it as sndens (pexp - 1) is no better because pexp is stored as 1 + O(1e-13). Both the component and its reference form it instead as sndens_in pexp_m1 + dw (1 - dsx), an exact rearrangement in which nothing cancels, and the reference is taken from a publisher that emits the series sum BEFORE WRF adds one to it (FORTRAN_BUGS N99, the same move N97 and N98 forced for the frozen-soil sink and the melt rate one routine over). REFERENCE STEP. Because nothing is differenced there is no cancellation floor pushing the reference step down, and the usual 'shrink dt until the increment is the derivative' recipe is actively WRONG here: the compaction increment is proportional to dtsec, so a SMALLER step puts LESS of an assertion's budget on the physics. The primary regime is therefore WRF's own 60 s step, where a rel 1e-9 assertion on sndens_out tests the compaction to between 1e-5 and 2e-1 of itself, and a second regime at 1e-6 s pins the tendency in the dt -> 0 limit, where the naive form would be 100 % noise. NOT TRANSCRIBED: the whole UA_PHYS branch (the snomlt-limited retention fraction), which is off in every reference run; SNOW_NEW, which sets the density of freshly fallen snow and is a separate routine; and the caller's own esd > 0 guard, which belongs to SNOPAC and is reported here as the indicator `pack_present`. MEASURED AGREEMENT: every one of the 1659 assertions passes at rel 3e-15, a few ulps of binary64, over all 134 tests of both regimes; the published bound is the 1e-9 the project sets for a double-precision kernel reference, and the six orders between them are headroom, not accuracy that was needed.
- NoahSnowCover
model
land_surface
noah
The snow-cover diagnostics of WRF's unified Noah land-surface model: SUBROUTINE SNFRAC (the fraction of the cell the pack covers), SUBROUTINE ALCALC (the albedo and emissivity that cover implies, including the ageing of fresh snow) and SUBROUTINE CSNOW (the thermal conductivity of the pack), all of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2). These are the algebraic quantities that turn a snow water equivalent into what the radiation and the soil actually see. SNFRAC is the Anderson/Koren depletion curve sncovr = 1 - (exp(-salp rsnow) - rsnow exp(-salp)) with rsnow = sneqv/snup, saturating at 1 once the pack exceeds the vegetation type's snup; SFLX then CAPS the result at 0.98, so a fully buried cell still reports 2 % bare ground and sncovr = 1 is unreachable in practice -- which matters, because the 0.98 value is what selects the pure-snow conductivity branch at module_sf_noahlsm.F:627. ALBEDO ageing: fresh snow starts at snoalb1 = snoalb + lvcoef (0.85 - snoalb) and decays as snoalb1 snacca^((snotime1/86400)^snaccb), floored at the snow-free albedo; snotime1 is the time since the last snowfall, an accumulator that WRF resets to zero whenever it is snowing, so this component exposes its rate dsnotime1_dt rather than owning it. The cell albedo is then the cover-weighted blend alb + sncovr (snoalb2 - alb), clipped so it can never exceed the aged snow albedo itself. Emissivity blends the background against a fixed snow value the same way. CSNOW is Yen's exponential fit sncond = 2 unit 0.328 10^(2.25 dsnow), where dsnow is the pack DENSITY in g/cm^3 and unit = 0.11631 converts Yen's units. NOT TRANSCRIBED: the whole UA_PHYS canopy-burial branch of SNFRAC (fvb, gama, fbur, fgsn, and the leaf-area reduction it applies), which is off in every reference run and is a separate parameterization; and the snow-conductivity BLEND that SFLX applies around this routine, which belongs to the snow-pack energy balance rather than to the cover diagnostics. THE NO-PACK CUTOFF. SFLX treats any pack of sneqv <= 1e-7 m as no pack at all (module_sf_noahlsm.F:503-507): it zeroes sneqv and snowh, sets sndens = 0 and sncond = 1.0 instead of calling CSNOW, and then, finding sneqv == 0, skips SNFRAC and ALCALC and reports sncovr = 0, albedo = alb, emissi = embrd. This component applies the same cutoff to its sneqv input, so a snow-free cell gives finite, WRF-equal diagnostics rather than 0/0. One ordering detail cannot be represented by an input-state component and is stated rather than hidden: SFLX applies the cutoff to the pack ENTERING the step and only then adds the step's new snowfall, so a step that snows onto a <= 1e-7 m pack diagnoses the cover of the new snow alone; in the dt -> 0 limit this component computes, that increment vanishes and the two coincide. The component is algebraic in the consumer's state and owns nothing.
- NoahSnowEnergy
model
land_surface
noah
The snow-pack surface energy balance of WRF's unified Noah land-surface model, SUBROUTINE SNOPAC of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2): the linearised snow-surface temperature t12, the branch it selects, the skin temperature and ground heat flux that follow, and the melt rate. THE CLOSURE. SNOPAC solves the surface balance over a slab of thickness dtot = snowh + half the top soil layer, treating the snow and that half-layer as one conductive path of conductivity df1. Writing the balance about the air temperature gives t12 = (sfctmp + t12a + t12b)/denom, where t12a carries the radiative and turbulent forcing per unit rch and per unit rr, t12b the conduction from the top soil layer, and denom = 1 + df1/(dtot rr rch) the strength of that conduction relative to the atmospheric coupling. t12 is the temperature the snow surface WOULD reach with no melting. THE BRANCH. If t12 is at or below freezing the pack simply cools: the skin temperature is t12 itself, nothing melts, and the pack loses only what sublimates. If t12 is above freezing the surface is pinned near freezing instead -- t1 is a cover-weighted blend of the freezing point and t12, with the weight max(0.01, sncovr^2), so a thin pack lets the surface run warm while a full one holds it at 273.15 K -- and the energy the balance cannot dispose of becomes melt. THE MELT RATE IS REFERENCED BEFORE ITS LIMITER, not after, and that distinction is the same one FORTRAN_BUGS N97 forced for the frozen-soil sink. flx3 is the residual of the balance evaluated at the blended skin temperature, floored at zero, and the melt rate is ex = flx3/(rho_w lsubf). That rate is a rate: it needs no differencing and has no dt dependence. WRF then applies TWO projections on top of it, both explicitly finite-dt, and this component reports each as an indicator rather than folding it into the rate. `pack_exhausted` is WRF's `esd - esnow2 <= esdmin` test, which zeroes the whole melt block when a step's sublimation would finish the pack; esnow2 is a sublimation AMOUNT, esnow1 dt, so the test is dt-dependent and in the dt -> 0 limit reduces to esd <= esdmin. `melt_limited` is WRF's `esd - snomlt < esdmin` test, which rewrites ex as esd/dt when a step's melt would overshoot the remaining pack -- a rate manufactured from an amount, and the clearest finite-dt artefact in the routine. A consumer integrating ex must apply both as projections of the state after its step, exactly as it would the supersaturation redistribution in soil_moisture.esm; neither belongs in a tendency. NOT TRANSCRIBED: the whole UA_PHYS branch (flx4, etpn and the canopy-shading adjustment to the melt energy), which is off in every reference run; SNOWPACK's compaction of the pack, which is a separate routine and a separate component; and EVAPO itself, whose snow-free evapotranspiration enters as the input eta_nosnow (evapotranspiration.esm's eta_kinematic). THE EVAPORATION SPLIT (module_sf_noahlsm.F:3136-3203) is transcribed: where PENMAN's etp is downward (etp <= 0) SNOPAC first rescales it over a stable surface -- ribb >= 0.1 and fdown > 150 W/m^2 -- to (min(etp (1 - ribb), 0) sncovr/0.98 + etp (0.98 - sncovr))/0.98, then books the whole of it as frost, dew = -0.001 etp_adj, and charges the balance etanrg = etp_adj ((1 - sncovr) lsubc + sncovr lsubs); where it is upward the snow-covered fraction sublimates at esnow = etp sncovr, the bare fraction evaporates at etns = (1 - sncovr) eta_nosnow, and etanrg = esnow lsubs + etns lsubc. The pack projections read esnow2_rate, which is ESNOW1 on the upward branch and the (negative) frost rate on the downward one, as SNOPAC's ESNOW2 is. 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.
- NoahSnowNew
model
land_surface
noah
The density and depth of freshly fallen snow in WRF's unified Noah land-surface model, SUBROUTINE SNOW_NEW of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2): how much depth a step's snowfall occupies, and what it does to the density of the pack it lands on. THE PHYSICS, IN TWO PARTS. First, how dense the falling snow is: Gottlib's (1980) fit makes it a floor plus a 3/2 power of how far the air is above -15 C, so warm snow falls denser (0.077 at -8.7 C, 0.122 at -2.9 C over this reference set) and cold snow is capped at the floor. Second, how it combines with what is already there: the water equivalent newsn expands into a physical depth hnewc = newsn/dsnew, that depth is ADDED to the pack, and the new density is the DEPTH-WEIGHTED average of old and new -- the only combination that conserves depth times density, i.e. water. Because fresh snow is always lighter than a settled pack, a snowfall step always lowers the mean density, and SNOWPACK's compaction then works against that. The two routines are the pack's density budget between them, which is why this component is authored beside `snow_compaction.esm` and shares its constants. WHAT IT DOES NOT DO. It does not add the water equivalent -- SFLX does that (`SNEQV = SNEQV + SN_NEW`) before calling -- so this component conserves nothing on its own and is not a closed budget. Nor does it decide WHETHER it runs: SFLX calls it only when SNOWNG (frozen precipitation) or FRZGRA (freezing rain onto a sub-freezing surface), and the guard belongs to the caller. That guard is load-bearing here in a way it is not for most routines, because this component is the identity at newsn = 0 ONLY while the pack is thicker than par.snow_new_hmin; below that WRF's degenerate-average branch would RAISE the density to the fresh-snow value out of nothing. A consumer must therefore reproduce the guard rather than mount this unconditionally, and `thin_pack` reports when it would matter. THE REFERENCE STEP IS THE LARGEST AVAILABLE, for the reason FORTRAN_BUGS N99 states as a rule and this is the second Noah component to meet. Nothing here is recovered by differencing -- both outputs are published where they form, at full magnitude -- so there is no cancellation floor pushing the step down. Meanwhile newsn is proportional to the step, so the fresh layer's weight in the density average is too: 0.0010 to 0.13 at WRF's own 60 s step, and about 2e-11 of that at 1e-6 s. A smaller step would leave a rel 1e-9 assertion testing nothing at all. So the reference is the 60 s replay pass. NOT TRANSCRIBED: nothing. SNOW_NEW has no UA_PHYS branch and no options; the whole routine is here.
- NoahSnowRoughness
model
land_surface
noah
Surface roughness over a snow pack in WRF's unified Noah land-surface model, SUBROUTINE SNOWZ0 of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2): how burying the vegetation under snow smooths the surface the atmosphere sees. THE PHYSICS. Roughness elements are treated as seven roughness lengths tall, so the height still standing proud of the snow is 7 z0brd - snowh. While any of it shows, the snow-covered fraction's roughness is that exposed height divided back by seven -- a linear collapse from z0brd towards zero as the pack deepens -- and once it falls below snow_z0_burial_min the surface is taken as bare snow at snow_z0 = 1 mm. The total is the cover-weighted average of the snow-free background and that value. Note that it averages LENGTHS, not their logarithms, which is not what a flux-matching argument would give; WRF's own commented-out alternative one line above makes the same arithmetic average with the bare snow roughness in place of the interpolated one, so the choice is between two arithmetic averages rather than between an arithmetic and a geometric one. IT NEEDED NO INSTRUMENTATION. Its output is the Registry variable Z0, which the kernel driver already dumps as `z0_out`, and it is computed before SNOPAC so nothing later moves it. Supplied the three arguments the routine actually reads, the component reproduces `z0_out` BITWISE at all 84 steps of the cold-season set -- the 67 with snow cover and the 17 without. TWO OF THOSE THREE ARGUMENTS ARE NOT THE OBVIOUS ONES, and both were settled by measurement rather than by reading. `z0brd` must be REDPRM's greenness-selected value and not the argument a caller passes to SFLX (FORTRAN_BUGS N96, whose list of affected quantities this extends to a fourth): the dumped argument takes 0.05 at some steps while the value the routine uses is 0.150000006 at every one. And `snowh` is the CURRENT depth, after SNOW_NEW, despite SFLX's comment above the call claiming the previous time step's -- feeding the previous depth reproduces WRF to only 7.1e-12 relative against bitwise agreement with the current one. That the discrepancy is small here is an accident of this surface: z0brd = 0.15 m puts the burial height at 1.05 m against a pack never deeper than 0.31 m, so the snow depth barely moves z0eff. On a smoother surface it would not be small. REFERENCE STEP. Unlike `snow_new.esm` and `snow_compaction.esm` next door, this routine has NO step dependence of its own -- it is four lines of algebra on the current state, with no dt in it and nothing differenced -- so the choice of replay pass cannot change its accuracy, only which state it is asked about. The 1e-6 s pass is used because it is the one where the snow-cover input is unambiguous: at the 60 s pass, case D step 553's pack disappears DURING the step and SNOPAC zeroes `sncovr` afterwards, so the dumped cover is no longer the one SNFRAC handed SNOWZ0 earlier in the same call. It is also the pass `snow_cover.esm`, which supplies that input in an assembly, is referenced against. NOT TRANSCRIBED: the entire UA_PHYS branch, which replaces the whole calculation with a logarithmic blend over buried canopy, ground and snow roughnesses; it is off in every reference run.
- NoahSoilHeat
model
land_surface
noah
Soil heat diffusion and the surface energy balance that closes it, in WRF's unified Noah land-surface model: SUBROUTINE TDFCND (soil thermal conductivity), the heat-capacity and flux-divergence parts of SUBROUTINE HRT, the yy/zz1 closure NOPAC forms before calling SHFLX, and the skin temperature and ground heat flux SHFLX returns (phys/module_sf_noahlsm.F, WRF 4.8, sf_surface_physics = 2), written as instantaneous tendencies. THE PDE: hcpct dT/dt = d/dz( df dT/dz ) on a column of NLEV soil layers, written as the flux-form operator D(K_soil D(T_soil) - F_soil) and lowered by the EarthSciDiscretizations column_nonuniform_1d rule varcoeff_face_flux_laplacian_lev, exactly as the slab scheme does. Orientation: `lev` is the soil layer index with layer 1 at the surface and `ze` the interface DEPTH below ground (positive downward, ze[1] = 0, increasing with the index), so ze is the negative of WRF's ZSOIL prefixed by zero. TWO boundary fluxes close the column and both are prescribed, which is why the diffusive part at the two domain faces is dropped: the surface interface carries F_soil[1] = df1 (yy - stc[1])/(0.5 ze[2] zz1), which is (the negative of) the Fortran's SSOIL and is the linearised surface energy balance rather than a temperature gradient; and the bottom interface carries the conduction to the prescribed deep-soil temperature, F_soil[NLEV+1] = df[NLEV] (stc[NLEV] - tbot)/(z_deep - zc[NLEV]). THE CONDUCTIVITY IS NOT FACE-AVERAGED. WRF evaluates TDFCND at the layer centre and then uses that one value for the flux through the layer's LOWER face, so the coefficient at interface kn is the conductivity of the layer ABOVE it, K_soil[kn] = df[kn-1]; a centred average would be the textbook choice and is NOT what the Fortran does, so the component reproduces the Fortran (FORTRAN_BUGS N90). The top layer's conductivity additionally carries the canopy reduction df1 = df[1] exp(sbeta shdfac), which the Fortran applies in NOPAC but not inside HRT's loop, so it appears at interface 2 and in the surface flux and nowhere else. THE SURFACE CLOSURE: yy and zz1 are NOPAC's linearisation of the skin-temperature energy balance about the air temperature; the skin temperature is DIAGNOSTIC, t1 = (yy + (zz1 - 1) stc[1])/zz1, not a prognostic state, and the reported ground heat flux ssoil = df1 (stc[1] - t1)/(0.5 ze[2]) is WRF's sign convention (positive warms the surface) and therefore the NEGATIVE of F_soil[1]. The sensible heat flux is evaluated at that diagnostic skin temperature and uses cp = 1004.5 and rd = 287.04, unlike SUBROUTINE PENMAN's rch (FORTRAN_BUGS N88). NOT TRANSCRIBED, and a consumer must not mount this component where they matter: the soil-water phase change (SNKSRC/TMPAVG/TBND, which adds a latent sink to the tendency of any layer holding ice or lying below 273.15 K), the snow-pack branch (SNOPAC), the urban override (df = 3.24, csoil = 3e6) and the opt_thcnd = 2 McCumber conductivity for silt/clay loam. The reference set is entirely above freezing and snow-free, so the freezing branch is UNTESTED here, not merely unused. Consumer-supplied column fields (ze, stc, smc, sh2o) 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.
- NoahSoilMoisture
model
land_surface
noah
Soil water transport of WRF's unified Noah land-surface model as instantaneous tendencies: SUBROUTINES SMFLX, SRT and WDFCND of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2), together with the canopy-interception budget and the three runoff terms. THE PDE is Richards' equation in mixed diffusivity/conductivity form, d(theta)/dt = d/dz( D(theta) d(theta)/dz - K(theta) ) - S, with Clapp-Hornberger closures D = dwsat (theta/smcmax)^(bexp+2) and K = dksat (theta/smcmax)^(2 bexp+3). It is written as the flux-form operator D(K_w D(sh2o) - F_w) and lowered by the SAME EarthSciDiscretizations rule the soil heat equation uses, column_nonuniform_1d/rules/varcoeff_face_flux_laplacian_lev -- NO NEW ESD RULE WAS NEEDED. That works because WRF evaluates the gravity drainage K(theta) UPWIND, at the layer above each interface, so from the operator's point of view it is a PRESCRIBED interface flux and drops straight into the rule's F slot; a scheme that averaged K across the face would not fit and would have needed a new rule. The same upwinding applies to the diffusivity (FORTRAN_BUGS N90, as in the heat equation). Orientation and geometry follow soil_heat.esm: `lev` is the soil layer index with layer 1 at the surface and `ze` the interface DEPTH below ground, positive downward. BOUNDARY FLUXES. The surface interface carries the infiltration pddum, and the bottom interface the free drainage slope wcnd[NLEV], which IS the subsurface runoff; both are prescribed, so the diffusive part at the two domain faces is correctly dropped. SINKS are the bare-soil evaporation, which withdraws from layer 1 only, and the per-layer transpiration. THE INFILTRATION LIMITER has a clean dt -> 0 limit that is not obvious from the Fortran: WRF forms infmax = px (ddt/(px + ddt))/dt with px = pcpdrp dt and ddt = dd (1 - exp(-kdt dt/86400)), and BOTH numerator terms are proportional to dt, so the limit is the harmonic-style combination pcpdrp r/(pcpdrp + r) with r = dd kdt/86400 a rate. dd is the column-integrated storage deficit, written here as an integral. The limiter is then floored at the surface conductivity and capped at the supply, and whatever the soil cannot take becomes surface runoff. DEW IS ROUTED LIKE RAIN: where the potential evaporation is negative the surface gains water, and NOPAC adds that gain to the precipitation before the canopy/throughfall split, so a dew step has a small positive canopy tendency and a small positive infiltration even with no precipitation at all. THE CANOPY is a reservoir of capacity cmcmax fed by shdfac prcp and drained by ec; what it cannot hold becomes drip, which joins the throughfall. In the dt -> 0 limit WRF's drip = max(cmc + dt rhsct - cmcmax, 0) becomes a SWITCH: zero while the canopy has room, and the whole net input once it is full, at which point dcmc_dt is zero. The reference set contains a step with the canopy exactly full and raining, so that branch is exercised. NOT TRANSCRIBED, and a consumer must not mount this where they matter: (a) SSTEP's supersaturation redistribution, which cascades water upward out of any layer driven past smcmax and reports the leftover as runoff3 -- that is a PROJECTION of the state applied after an integration step, not a rate, exactly like the slab scheme's snow cap, so it is reported as the indicator supersaturation_active instead; (b) the SMFLX predictor-corrector, which runs SRT/SSTEP twice on a half-updated column when the rainfall is heavy or the soil near saturation -- it is a finite-dt integration device and both branches converge to the SAME right-hand side as dt -> 0, so it does not affect this component, but it also means the corrector path is untested; (c) the frozen-ground infiltration reduction fcr, which IS written here because it is a clean closed form, but which the reference set never exercises (no soil ice anywhere), so it is UNTESTED rather than merely unused, as is every appearance of sice; (d) the WRF_HYDRO surface-head coupling. Consumer-supplied column fields (ze, sh2o, smc, et) 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.
- NoahSoilVegParameters
model
land_surface
noah
SUBROUTINE REDPRM of phys/module_sf_noahlsm.F (WRF 4.8, sf_surface_physics = 2): the per-soil-type, per-vegetation-type and per-slope-type parameters Noah copies out of SOILPARM.TBL, VEGPARM.TBL and GENPARM.TBL for the grid cell it is about to run, plus the four quantities REDPRM derives from them (kdt, frzfact, frzx) and the four it selects by greenness (xlai, embrd, z0brd, alb). Each lookup is interp.linear on a constant table with a constant integer axis, the pattern anderson13_fuel_table.esm already uses: the category index lands exactly on an axis knot, so the interpolation returns the table entry unchanged, and a category outside the table clamps at the end rather than reading past it. TWO THINGS A CONSUMER MUST CHECK. (1) The vegetation table is the USGS 27-category one. WRF also ships a 20-category MODIS table (isurban = 13 instead of 1) with different rows, and the real-terrain reference run in data/eqwefic/gwdo_real uses THAT one, so this component must not be mounted for a MODIS run; the SOILPARM table is the same in both, which is why the soil half of this component is tested against seven soil types drawn from the real-terrain dumps and the vegetation half only against the idealized column. (2) The table values are the REAL32-WIDENED numbers WRF actually held, not the decimal text of the .TBL files: those tables are read into real32 arrays, so a real64 reference replay uses the widened single, and writing the decimal instead puts up to 2.3e-8 relative error into smcmax -- six times the 1e-9 tolerance these tests run at. THE BARE-SOIL OVERRIDE. REDPRM sets SHDFAC = 0 on the bare-soil category (VEGPARM.TBL's BARE, 19 for USGS, read here as par.bare like the other VEGPARM scalars) before SFLX selects xlai, embrd, z0brd and alb by greenness, so those four and every downstream user see shdfac_eff, not the driver's shdfac. The urban override REDPRM applies when vegtyp == isurban (smcmax 0.45, smcref 0.42, smcwlt 0.40, smcdry 0.40) is NOT transcribed, and neither is the fatal-error path for an out-of-range category; a consumer must not mount this on an urban cell.
- NoahSurfaceDriver
model
land_surface
noah
The per-point glue between the atmosphere, the surface layer and Noah's SFLX in WRF's Noah driver, SUBROUTINE lsm of phys/module_sf_noahdrv.F (WRF 4.8, sf_surface_physics = 2), together with the few lines of SUBROUTINE SFLX (module_sf_noahlsm.F) that select the surface properties and form the surface humidity: everything a Noah column needs besides its process components (soil_veg_parameters, potential_evaporation, canopy_resistance, evapotranspiration, soil_heat, soil_moisture). FORCING (the driver's preamble, lines 'PSFC = P8W3D(I,1,J)' to 'PRCP = RAINBL(I,J)/DT'): the pressure at the lowest model level is the mean of the two lowest interface pressures, sfcprs = (p_sfc + p_w2)/2; the humidities are converted from mixing ratios to SPECIFIC humidities, q2 = qv/(1 + qv) and q2sat = qgh/(1 + qgh), where qgh is the surface layer's saturation mixing ratio at the lowest level (sfclayrev's QGH, which is how the surface layer hands Noah its saturation humidity); the slope of the saturation humidity is Bolton's, dqsdt2 = q2sat a2 (a3 - a4)/(sfctmp - a4)^2 with the driver's A2 = 17.67, A3 = 273.15, A4 = 29.65 (= wrf.svp2, wrf.svpt0, wrf.svp3); the lowest-level potential temperature is referenced to the SURFACE pressure, th2 = sfctmp (p0/sfcprs)^kappa/(p0/p_sfc)^kappa with kappa = R_d/cp; the downward longwave is scaled by the emissivity ENTERING the step and the net shortwave by the albedo entering the step (WRF's EMISS and ALBEDO fields, i.e. the previous step's values), lwdn = glw emiss_in, solnet = swdown (1 - albedo_in); and the precipitation rate is the step's accumulated grid-scale rain over the step, prcp = rainbl/dt_rain. SURFACE PROPERTIES (SFLX, snow-free branch 'IF (SNEQV == 0.0)'): albedo = alb, emissi = embrd and z0 = z0brd, the greenness-selected background values of REDPRM (soil_veg_parameters). The SNOW branch (SNFRAC, ALCALC, SNOWZ0, CSNOW, SNOW_NEW and SNOPAC) is transcribed in the snow_* components but is NOT selected here: `snow_branch_active` reports whether WRF would have taken it (a pack, sneqv > 1e-7 m, or precipitation that SFLX classes as snowfall or freezing rain), and a consumer that mounts this component asserts it zero. SURFACE HUMIDITY (SFLX after NOPAC): q1 = q2 + eta_kinematic cp/rch, the specific humidity at the surface that sustains the evapotranspiration flux through the bulk transfer coefficient rch = rho cp_penman ch, with the module's cp = 1004.5 in the numerator (PENMAN's rch carries cp = 1004.6, FORTRAN_BUGS N88, so the two do not cancel exactly); the driver hands the surface layer its MIXING ratio, qsfc = q1/(1 - q1). The driver's remaining assignments are renames (TSK = T1, HFX = SHEAT, QFX = ETA_KINEMATIC, LH = ETA, GRDFLX = SSOIL, ZNT = Z0) and belong on a consumer's coupling edges, not here. NOT TRANSCRIBED: the urban (sf_urban_physics) and sea-ice paths, the MYJ surface-layer test on CHKLOWQ, FASDAS, and irrigation.