Clm
- BareGroundFluxes
model
land_surface
clm
CLM bare-ground turbulent-flux component: the pointwise laws of BareGroundFluxes in src/biogeophys/BareGroundFluxesMod.F90 of CTSM ctsm5.4.063 (the CESM3.0 alpha-branch land model; F90 line numbers below refer to that tag) transcribed exactly, with the expression templates of ./clm_templates.esm imported by reference. The traced configuration (the lnd_in namelist of the I2000Clm60Sp reference case): z0param_method = 'Meier2022', use_z0m_snowmelt = .true. (so z0mg comes from the snowmelt-dependent branch of SetRoughnessLengthsAndForcHeightsNonLake, FrictionVelocityMod.F90:620-623), zetamaxstable = 2.0, soil_resis_method = 1 (the Swenson & Lawrence 2014 soil-resistance branch, inactive on the pinned rows because they are all dew rows with dqh > 0), do_soilevap_beta inactive, GSWP3 forcing heights 30 m, wind_min = 1.0 m/s and the Meier2022 constants of the ctsm60_params.c260518.nc parameter file. Structure, in the order of the Fortran: (a) the raw inputs (forc_t/forc_q/forc_u/forc_v/forc_pbot/forc_rho, thm, t_grnd, qg, the ground-layer temperatures t_soisno_top = t_soisno(c,snl+1)/t_soisno_soil = t_soisno(c,1)/t_h2osfc, the surface-humidity fields qg_snow/qg_soil/qg_h2osfc and dqgdT, thv, and the constants); (b) the derived inputs of F90:318-322 (ur = max(wind_min, |forc_u,forc_v|), dth, dqh, dthv, zldis = forc_hgt_u + z0mg) with forc_th = thv/(1 + 0.61*forc_q) recovered from the dumped virtual potential temperature (dthv = dth*(1 + 0.61*forc_q) + 0.61*forc_th*dqh of F90:328 then inverts to forc_th = thv/(1 + 0.61*forc_q)); (c) z0mg from the Meier2022 snowmelt template (the traced rows are all in the frac_sno_albedo > 0, snomelt_accum < 1e-5 branch, pinning z0mg = exp(-b1*pi/2 + b4)*1e-3 = 8.13402050576016129e-05; the bare-soil zlnd branch of the select case is included for completeness); (d) the MoninObukIni initialization of F90:331 (um_ini, rib, zeta_ini clamped to [0.01, 2.0], obu_ini = zldis/zeta_ini); (e) the stability iteration of F90:342-388. The esm has no loop construct, so the iteration is represented compositionally: the 17-equation update law is authored ONCE in the one-step model BareGroundStep of ./clm_bareground_step.esm (a single pass of the do-while: the FrictionVelocity profiles and friction velocity, the Meier2022 z0hg update, the stability-parameter clamp and the um/wc/obu update) and mounted three times by reference as top-level models step1..step3 (esm-spec section 4.7; top-level mounts are required because the Rust CLI silently drops couplings in the single-top-level-model build path, see README.md), with the chained inputs coupled by the 66 variable_map edges of the ./clm_bareground_steps_coupling.esm coupling library (imported by reference): um_ini/obu_ini/z0mg seed step1, each step's state feeds the next (um/obu/z0h), and the update-invariant pointwise fields (forc_hgt_u, forc_hgt_t, z0m = z0mg, ur, dth, dqh, forc_q, forc_th, thv, zii, beta, zetamaxstable and the constants vkc/grav/zetam/zetat/meier_param3/nu_param/beta_param) feed every step; the parent's zldis equals the step's own profile height zldis_u (z0mg is iteration-constant) and the Fortran's stale wc local is only read by the unstable um branch, so the zldis and wc couplings are dropped as dead. The parent keeps the external names of the Fortran locals: ustar/temp1/temp2/temp12m/temp22m/z0h/um = the step3 outputs (the exit state of the 3-iteration loop, which matches the traced run's niters = 3). The 2-m humidity profiles are the equality branches temp2 = temp1 and temp22m = temp12m (F90:997-998, 1051-1052) because forc_hgt_q_patch == forc_hgt_t_patch and z0qg == z0hg in the traced run. (f) the flux laws of F90:400-476: ram/rah/raw, raih = forc_rho*cpair/rah, the vapor pressure forc_e = max(forc_q*forc_pbot/(forc_q + 0.622), 0.01*forc_esat) with forc_esat from the QSat polynomial, the Magnus dewpoint forc_dewpoint of F90:548-578 (ice coefficients on all traced rows: t_grnd ~ 234-250 K < tfrz selects the ice branch), the raiw selection of F90:423-442 (the dqh > 0 dew branch with the t_grnd > forc_dewpoint no-dew gate, the sl14/beta branches of the dqh <= 0 side transcribed for completeness), ram1, cgrnds/cgrndl/cgrnd (cgrnd = cgrnds + htvp*cgrndl, F90:450, where htvp is the column latent heat chosen by BiogeophysPreFluxCalcsMod.F90:353-357: hsub = SHR_CONST_LATSUB = 2.8347e6 J/kg when the top layer snl+1 holds ice and no liquid, else hvap = 2.501e6 J/kg; every traced row has a dry snow top layer, so htvp = hsub), taux/tauy (the wind_stress_component law), the sensible heat partition eflx_sh_grnd/soil/snow/h2osfc and the evaporation qflx_evap_soi and qflx_ev_snow/soil/h2osfc (one law: the aerodynamic_surface_flux template, flux = -resistance*(atmosphere - surface); qg_h2osfc is not dumped, so qflx_ev_h2osfc is transcribed but unpinned), and the 2-m diagnostics t_ref2m/q_ref2m/rh_ref2m (the ref2m_profile law, with qsat_ref2m from the shared qsat_qs) and kbm1 = log(z0mg/z0h) (F90:478-495). The tests pin the reference dumps: a CESM3 / CTSM ctsm5.4.063 I2000Clm60Sp land-only run (GSWP3 forcing, dtime = 1800 s) instrumented with write statements at the BareGroundFluxes exit, recording the inputs and outputs of the first 16 bare, deep-snowpack patches over the first 12 steps in full double precision: five of the 192 dumped rows (one per step/column regime, see README.md), asserting every dumped output column plus z0mg and cgrnd (cgrnd from the ComputeGroundHeatFluxAndDeriv dump of the same run). Tested regime: every one of the 192 dumped rows is stable (dthv > 0; the iteration zeta clamped at zetamaxstable = 2.0, so the momentum/heat profiles take the zeta > 1 branch and the 2-m profiles the 0 < zeta <= 1 branch), in the dew branch (dqh > 0, raiw = forc_rho/raw), below freezing (ice dewpoint coefficients), fully snow covered (frac_sno_albedo = 1, snomelt_accum = 0) and has forc_u == forc_v. The unstable branches (zeta < 0 and zeta < -zetam/-zetat), the evaporating dqh <= 0 branches (sl14 soil resistance and soilbeta), the liquid dewpoint branch, the snowmelt/bare-soil z0mg branches and rh_ref2m/kbm1/qflx_ev_h2osfc are transcribed but NOT exercised by any test, because the reference run contains no such rows. Not transcribed (dead or undumped in this configuration): the human-stress indices, the www soil-wetness variable, the rssun/rssha photosynthesis resistances, the u10 diagnostics of FrictionVelocityMod, and the ZengWang2007 z0hg branch (the traced run is Meier2022). Reference: CTSM ctsm5.4.063, src/biogeophys/BareGroundFluxesMod.F90 and FrictionVelocityMod.F90.
- BareGroundStep
model
land_surface
clm
One-step update of the CLM bare-ground stability iteration: a single pass of the do-while of BareGroundFluxes in CTSM ctsm5.4.063 src/biogeophys/BareGroundFluxesMod.F90:342-388 (F90 line numbers below refer to that tag) (the FrictionVelocity call of :344-347 followed by the z0hg update, the stability-parameter update and the Obukhov-length update of :353-387), transcribed exactly and mounted three times by reference in clm_bareground.esm (top-level models.step1..step3, esm-spec section 4.7) so the 17-equation update law is authored once and the unrolled iteration is composed. Inputs are the update-invariant pointwise fields (the wind and temperature measurement heights forc_hgt_u/forc_hgt_t, the momentum roughness z0m = z0mg_patch which is constant across the iteration, the wind speed ur = max(wind_min, |forc_u,forc_v|), the temperature/humidity differences dth/dqh, the forcing specific/potential temperatures forc_q/forc_th, the virtual potential temperature thv, the convective velocity-scale inputs zii/beta, the zetamaxstable stability clamp and the physical constants vkc/grav/zetam/zetat/meier_param3/nu_param/beta_param) and the previous update's state (z0h_prev/obu_prev/um_prev). The iteration height is the step's own momentum profile height zldis_u = forc_hgt_u + z0m, which equals the parent's zldis = forc_hgt_u + z0mg (the redundant coupling is dropped), and the Fortran's stale wc local is computed unconditionally (only read by the unstable um branch; the dead wc threading is dropped). Outputs are the 17 update states (zldis_u = forc_hgt_u + z0m, zldis_t = forc_hgt_t + z0h_prev and zldis_2m = 2 + z0h_prev, the three profile heights of FrictionVelocityMod.F90:850-853, 946-949, 1022-1025; ustar from the four-branch momentum profile F90:857-871; temp1 from the four-branch scalar profile F90:956-970; temp2 = temp1 and temp22m = temp12m by the equality branch F90:997-998 and F90:1051-1052, which holds in the traced run because forc_hgt_q_patch == forc_hgt_t_patch and z0qg == z0hg; temp12m from the 2-m scalar profile F90:1022-1038; tstar = temp1*dth and qstar = temp2*dqh F90:354-355; z0h from the Meier2022 update F90:364; thvstar F90:375 (the virtual_potential_scale law shared with the parent's dthv); zeta_raw F90:376; the sign-preserving stability clamp zeta F90:378-386 (the clamp_zeta law shared with the MoninObukIni initialization); wc F90:383; obu = zldis/zeta F90:387). NaN safety: every branch of an ifelse may be evaluated eagerly by a backend, so the laws the Fortran evaluates only on one branch are written so their unselected branches stay finite - the wc base is clamped at zero (max(base, 0): on the unstable rows where wc is read the base is positive and the value is unchanged; on stable rows the Fortran never evaluates it), and the friction-velocity profile templates clamp the arguments of their unstable-branch logs, fractional powers and stability functions (clm_templates.esm). The expression templates of ./clm_templates.esm are imported by reference.
- SoilFluxes
model
land_surface
clm
CTSM/CLM ground energy and moisture flux update SoilFluxes, transcribed from src/biogeophys/SoilFluxesMod.F90 of CTSM ctsm5.4.063 (cesm3.0-alphabranch; line numbers refer to that tag): the previous-time-step ground temperature and T^4 blend t_grnd0/lw_grnd (SoilFluxesMod.F90:175-183, :344-346), the sensible/latent flux corrections to the present soil temperature (:192-204), the liquid/solid partition of the ground evaporation into liquid evaporation, sublimation, liquid dew and solid dew (:208-274), the snow-evaporation moisture limit of the top layer (:276-297), the ground heat flux from absorbed shortwave, canopy longwave and black-body emission (:341-371), the total vegetation+ground fluxes and the history-tape latent heat breakdown (:373-394), the outgoing/net longwave radiation with the temperature-increment term and the bare-ground skin temperature (:451-495). The equations are written as math over the patch index set (the traced reference-dump rows carry p == c, so the column-level quantities of the Fortran are replicated patch-wise); the shared laws are imported by reference from ./clm_templates.esm (ground_temperature_blend, stefan_boltzmann_emission, flux_temperature_correction, stefan_boltzmann_emission_dT). All fluxes are mass fluxes in kg/m^2/s (= mm/s of water): the esm unit system requires the mass-flux form for dimensional consistency with the latent-heat multiplications (qflx*htvp [J/kg] = W/m^2), see README.md. The tests pin the reference dumps: a CESM3 / CTSM ctsm5.4.063 I2000Clm60Sp land-only run (GSWP3 forcing, dtime = 1800 s) instrumented with write statements at the SoilFluxes, BareGroundFluxes, SoilTemperature, ComputeGroundHeatFluxAndDeriv, SurfaceRadiation and BiogeophysPreFluxCalcs exits, recording the first 16 bare, deep-snowpack columns over the first 12 steps in full double precision; forc_lwrad is the downscaled column longwave recorded at ComputeGroundHeatFluxAndDeriv. Tested regime: all 192 dumped rows are dew rows (qflx_ev_snow < 0) below freezing (t_grnd < tfrz, so the dew is solid) with an all-snow blend (snl = -9, frac_sno_fluxes = 1, frac_h2osfc = 0, frac_veg_nosno = 0); the evaporation branch of the partition, the firing snow-evaporation limit, liquid dew, mixed snow/soil blends and snow-free columns are transcribed but not exercised, because the reference run has no such rows. The assertions on quantities that are not dump columns (lw_grnd, qflx_ev_snow, qflx_ev_soil, evaporation_limit, qflx_soliddew_to_top_layer, lwrad_emission, lwrad_increment, eflx_lwrad_out, qflx_evap_tot) are labelled derived (not a dump column) and computed offline (double-precision evaluation of the transcribed equations at the pinned dump inputs), cross-checked against every dump column they touch on all 192 rows (max rel err 7.9e-15).
- SoilTemperature
model
land_surface
clm
CTSM/CLM snow/soil temperature, single-time-step form. SCOPE AND VALIDITY (read first): this model reproduces ONE CLM soil-temperature time step from a supplied entry state; it is not a free-running soil-temperature model and must not be integrated over multiple steps on its own. (a) The thermal properties thk, cv and K are computed from the parameter t_entry (the start-of-step temperatures, as SoilThermProp does once per CLM step), not from the evolving state T. (b) The top boundary flux kdudz_top = hs + dhsdT*(T[NLEV] - t_entry[NLEV]) is linearized about t_entry, with hs, dhsdT, sabg and eflx_bot supplied as parameters for that step. (c) The column structure is fixed: the snow-layer count by the metaparameter N_SNOW_MAX = 9 (snl = -9) and the bedrock index by nbedrock = 20; there is no phase change, no snow-layer combination/division and no change of layer water content. It is valid for evaluating the instantaneous tendency cv*dT/dt = F(T) and the Crank-Nicolson identity of a single dtime = 1800 s step (every test uses time_span {0, 0}); integrated past one step it does not reproduce CLM (the properties and surface linearization go stale, and CLM's top row is fully implicit, see README.md). A multi-step use requires recomputing t_entry, hs, dhsdT and sabg every step from a coupled surface energy balance, which is not provided here. The SoilTemperature model of src/biogeophys/SoilTemperatureMod.F90 (CTSM ctsm5.4.063, cesm3.0-alphabranch; line numbers refer to that tag), as the heat-conduction PDE cv*dT/dt = dz*D(K*D(T,lev),lev) + sabg on the column_nonuniform_1d grid, pinned against the reference dumps: a CESM3 / CTSM ctsm5.4.063 I2000Clm60Sp land-only run (GSWP3 forcing, dtime = 1800 s) instrumented with write statements before SoilThermProp and after the band-diagonal solve, recording every layer of the first 16 bare columns over the first 12 steps in full double precision (column 1, ctype 1 soil, snl = -9, 34 layers; the tests pin column 1 at step 1). The state T is the layer temperature; the SoilThermProp thermal-property laws (F90:604-903) consume the entry state t_entry, as in CLM (SoilThermProp runs at the start of the step): per layer, the snow bulk density bw (:744), the Sturm1997 snow thermal conductivity (:774-778; the traced run's snow_thermal_cond_method; the five coefficients lack _r8 in the Fortran and execute as float32-rounded values (a CTSM defect at SoilTemperatureMod.F90:775,777), reproduced here to rel 1.6e-16), the snow heat capacity with the thin-layer floor (:892-895), the Johansen (1975) soil thermal conductivity (:712-727; saturation water content :712-713, Kersten number :715-719, liquid fraction :720-721, saturated conductivity :722, bedrock override :727), the de Vries (1963) soil heat capacity (:852-854) with the bedrock override (:854), and the harmonic-mean interface conductivity tk with the zero bottom boundary (:825-828). The interface conductivity array K (lev_nodes) is the faq of clm_interface_conductivity over the face index set (K[1] = 0 bottom, K[NLEV+1] = 0 dummy above the top layer). The divergence D(K*D(T,lev),lev) is lowered by the local rule clm_soiltemp_discretization.esm (priority 11, a CLM-specific rule kept local to this component): interior rows (G[k+1]-G[k])/dz[k], bottom row (G[2]-kdudz_bot)/dz[1], and the top row (kdudz_top - G[NLEV])/M with the capr-weighted measure M = 0.5*(ze[NLEV+1]-zc[NLEV] + capr*(ze[NLEV+1]-zc[NLEV-1])) of F90:1895, kdudz_top = hs + dhsdT*(T[NLEV]-t_entry[NLEV]) the linearized surface flux (ComputeGroundHeatFluxAndDeriv :1545-1798) and kdudz_bot = eflx_bot. The layer index set is the ESD bottom-up column (lev = 26 - j: lev 1 = j = 25 deepest soil, lev 34 = j = -8 top snow; snow j = -8..0, soil j = 1..25). The model is pinned three ways: (1) at the entry state T = t_entry, K, cv, the entry-state interface flux fn_esd = -G (the dumped fn column is exactly -G(t_entry), verified to 1e-13) and the instantaneous dT/dt of the PDE; (2) at the exit state T = t_exit, the instantaneous dT/dt and kdudz_top; (3) the derived Crank-Nicolson identity 0.5*(F(t_entry)+F(t_exit)) = cv*dT/dt (F = dz*D(K*D(u,lev),lev) + sabg), which holds for the interior and bottom rows (lev 1..33) to solver round-off (max |resid| = 6.3e-10 W/m2, computed offline in double precision from the dump before pinning); the top row deviates by the fully-implicit dhsdT term of SetMatrix_Snow and is not pinned (see README.md). The dumped values are reproduced to the dump's full double precision (rel 1e-12). Coverage gaps of the traced dump, each with its reason: imelt = 0 on every row (no phase change in the 12 traced steps), so the Phasechange laws are not exercised; snow_thermal_cond_method = 'Sturm1997' only (the Jordan1991 template exists but is untested); frac_sno_fluxes = 1 exactly; excess_ice = 0 and h2osoi_liq = 0 in the snow layers (the excess-ice and snow-liquid terms never bind); h2osno_no_layers = 0 (the cv(c,1) += cpice*h2osno_no_layers addition of F90:880-882 is not exercised); the top snow layer's absorbed solar (sabg = 57.79 W/m2 in the dump) is inside hs_top_snow (ComputeGroundHeatFluxAndDeriv :1779-1783 adds no sabg to the top row), so the model's sabg parameter carries 0 at the top layer; eflx_bot = 0 in the dump (the sign convention of the F90 comment, +upward, vs the fn slot, +downward, is unpinned; see README.md); the top-layer dumped dz (0.015578352833079012) differs from the grid spacing ze[NLEV+1]-ze[NLEV] (0.015517897173545236): in CTSM the top snow layer's (z, dz) is inconsistent with its zi interfaces (suspected in DivideSnowLayers/AddNewSnow), so dz stays a dumped parameter.