Heat-Conduction
- 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.