River-Routing
- Channel
model
environmental_transport
mosart
MOSART main-channel routing step (stage 2 of the EqESM project): the per-cell Euler step 4 of mosart_physics.F90:Euler (F90:175-209) composed of mainchannelRouting -> Routing_KW (F90:273-348) and updateState_mainchannel (F90:385-402), written as a storage ODE with the pointwise laws imported from ./mosart_templates.esm. Equations, exactly as in the Fortran (RoutingMethod = 1, the only implemented method, F90:280-284): erin = -eroutUp (F90:302-303); with no river network (rlen <= 0) vr = 0 and erout = -(erin + erlateral) (F90:306-308); for an unrealistically small drainage density per channel (areaTotal2/(rwidth*rlen) > 1e6) erout = -(erin + erlateral) (F90:310-312); otherwise the Manning velocity vr = CRVRMAN_nosqrt(rslpsqrt, nr, rr) (F90:313) and erout = -vr*mr (F90:314), with the dry-cell clamp erout = -(erlateral + erin + wr/localdelt) when -erout > TINYVALUE and wr + (erlateral + erin + erout)*localdelt < TINYVALUE (F90:315-317), in which case vr = -erout/mr when mr > 0 (F90:318-320); the groundwater term temp_gwl = qgwl*area*frac (F90:325); dwr = erlateral + erin + erout + temp_gwl (F90:327), plus qirrig, the irrigation withdrawal (<= 0) that mosart_run takes out of wr once per coupling period (mosart_driver.F90:497), here a rate wired from the assembly's Control.qirrig_actual; d(wr)/dt = dwr (the Fortran advances wr += dwr*localdelt explicitly per substep, F90:189; here a continuous ODE, which is not the limit of that scheme - see README.md, 'Continuous ODEs vs the Fortran 3600-s Euler stepping'); updateState_mainchannel (F90:391-401) sets mr = GRMR(wr, rlen), yr = GRHR(mr, rwidth, rwidth0, rdepth), pr = GRPR(yr, rwidth, rwidth0, rdepth), rr = GRRR(mr, pr) when rlen > 0 and wr > 0, and zeroes all four otherwise; and the reach outflow streamflow flow = -erout (the Fortran accumulates flow -= erout over the m-levels and divides by DLevelH2R, F90:201, 216; here the instantaneous value) is exported to the assembly for the runoff aggregation. Units per mosart_tstatusflux_type.F90 / mosart_tspatialunit_type.F90: wr [m3]; erin, erout, dwr, erlateral, eroutUp [m3/s]; vr [m/s]; mr [m2]; yr, pr, rr [m]; rslpsqrt [1]; rlen, rwidth, rwidth0, rdepth, areaTotal2 [m2, m, m, m, m2]; nr is the main-reach Manning roughness (SI dimension s/m^(1/3)); qgwl [m/s]; localdelt = Tctl%DeltaT/DLevelH2R/numDT_r(nr) (F90:184). eroutUp is the outflow sum of the upstream gridcells delivered by the rh_eroutUp sparse-matrix gather over the ID/dnID network (F90:158) - a network-topology operation whose per-cell value is a parameter here until the frivinp network data source lands (boundaries.md 2.4). Two deliberate divergences, documented for reviewers: when the areaTotal2 branch fires the Fortran leaves vr stale (unused there), while here vr takes the Manning value; and the Fortran's negative-storage warning (F90:329-334) is a diagnostic, not physics, and is not transcribed. The tests block has three kinds of pins (the stage1/... paths refer to the EqESM instrumented-CESM checkout; see README.md, Testing): (1) dry-window CESM pins from stage1/dumps/mosart/ (gr_chan.csv, crvrman_chan.csv, mosart_euler.csv of the lane run, where every channel stays below TINYVALUE): the dry geometry chain and dry routing branches pointwise (time_span {0,0}) and a one-substep storage trace; (2) wet-window CESM pins from stage1/dumps/mosart_wet/ (a 1-day cold start whose runoff pulse drives reaches above bankfull): flood-plain geometry (floodplain_geom_*), wet Manning routing with qgwl and upstream inflow (wet_manning_*) and one wet m-level storage trace (wet_ode_*); (3) NOT from a CESM run: the in-bank/trapezoid/flood-plain geometry_*_cell100312 pins, whose expected values come from the unmodified GRHR/GRPR/GRRR compiled from mosart_physics.F90 into a standalone gfortran driver at chosen storages (EqESM checkout, stage1/analysis/mosart_geometry/mosart_geometry_driver.f90, gitignored); those pins caught and now guard the GRHR trapezoid transcription (the 0.1*(2.0/1.0) = 0.2 factor in place of SLOPE1/2 = 0.05 and the dropped rdepth prefix, F90:528). Reference: stage1/cesm/components/mosart/src/riverroute/mosart_physics.F90 (mosart1.1.13).
- Control
model
environmental_transport
mosart
MOSART river-routing top-level component (stage 2 of the EqESM project): the cesm3.0-alphabranch mosart1.1.13 rof component as an esm 2.0.0 assembly, per the stage1/boundaries.md 1.5 boundary table and 2.6 subassembly mapping. Five systems: RofCap (mounted from ./mosart_coupling.esm, the med<->rof cap unit conversions), Hillslope (./mosart_hillslope.esm), Subnetwork (./mosart_subnetwork.esm), Channel (./mosart_channel.esm) - the Euler cascade of mosart_physics.F90 (hillslope -> subnetwork -> main channel, with the shared pointwise laws in ./mosart_templates.esm) - and the inline Control model, which is mosart_run (mosart_driver.F90:375-873) steps 2-8 written as algebraic rate rules over one coupling period: the irrigation withdrawal qirrig_actual = -min(-qirrig*coupling_period, wr)/coupling_period, removed from the channel storage through Channel.qirrig (the Fortran's wr -= irrig_volume, F90:497), with the overage returned to qsub (F90:476-500), the flood rule flood = (volr - fthresh)/delt_coupling for mask==1 cells with volr = wt + wr + wh*area (F90:509-531, 854), the direct-transfer rules (frozen runoff, glc runoff, the qgwl_runoff_option all/negative/threshold branches, negative qsur/qsub, mask==0 cells; F90:533-772), the subcycling nsub = ceil(coupling_period/delt_mosart) with delt = delt_coupling/nsub (F90:786-800), the CFL sub-timesteps phi_r/phi_t and the integer numDT_r/numDT_t of set_subtimesteps with its mask/rlen/tlen guards and integer truncation (mosart_tspatialunit_type.F90:624-684; Control is also the single source of the cell geometry - area, frac, rlen, rwidth, rdepth, areaTotal2, rslpsqrt, tlen, twidth, tslpsqrt - which the coupling library wires into the routing systems, so the CFL and the routing see the same cell), the flow/runoff aggregation runofftot = direct + runoffocn + direct_glc with the mask==1/mask>=2 split (F90:844-867), and the ice_runoff branch of the rof_import_export export_fields (F90:362-382). The data flow is wired by the 43 variable_map param_to_var coupling edges of the mosart_routing_coupling.esm coupling library (esm-spec 10.9-10.10), imported by reference below and expanded at flatten in the Euler order; the one network operation not yet wired is the rh_eroutUp upstream gather (erout of each cell mapped to the downstream cell's eroutUp, F90:158) and the rh_direct outlet gather - they are per-cell parameters (Channel.eroutUp, Control.direct_*) until the frivinp network data source lands (boundaries.md 2.4). The routing steps are written as continuous storage ODEs. They are NOT the continuous limit of the Fortran scheme: the Fortran advances storage with forward Euler at fixed 3600-s substeps (subcycled by DLevelH2R*numDT in the subnetwork and channel) and applies its dry-cell clamps per Euler step, so the .esm's ifelse clamps evaluated continuously, and the hillslope outflow reaching the subnetwork as a smooth ramp, give a structurally different intra-step trajectory and wt/wr split, while conserving the same total water (see README.md). The once-per-coupling-period irrigation storage jump (wr -= irrig_volume, F90:497) is a rate rule here, as is the flood subtraction from qsur. All fields use the standard CESM/CMEPS names; units are SI except the CMEPS surface fluxes (kg/m^2/s = mm/s). The Control tests block holds: the one-coupling-period assembly trace from the cold start of cell 100312 of the EqESM instrumented-CESM dry window (stage1/dumps/mosart/, mosart_run_imports.csv / mosart_run_exports.csv / mosart_run_imports_wide.csv), pinning the mass-conserved volr, the hillslope fill wh, the CFL/subcycling diagnostics with the cell's real geometry (areaTotal2 from the frivinp dnID network) and the zero branches, with the wt/wr split documented rather than asserted; two wet-window coupling tests (stage1/dumps/mosart_wet/: the positive-qgwl import path with numDT_r = 7, and the negative-qgwl direct transfer); and two hand-derived irrigation tests (the dumps carry no irrigation demand) that check the withdrawal leaves the channel storage and the overage goes to the subsurface stream, plus the set_subtimesteps rlen = tlen = 0 guards (see README.md Testing). Reference: stage1/cesm/components/mosart/src/riverroute/mosart_driver.F90 and mosart_physics.F90 (mosart1.1.13).
- Hillslope
model
environmental_transport
mosart
MOSART hillslope routing step (stage 2 of the EqESM project): the per-cell Euler step 1 of mosart_physics.F90:Euler (F90:74-80) composed of hillslopeRouting (F90:225-239) and updateState_hillslope (F90:352-360), written as a storage ODE with the pointwise laws imported from ./mosart_templates.esm. Equations, exactly as in the Fortran: ehout_manning = -CREHT_nosqrt(hslpsqrt, nh, Gxr, yh) (F90:232); the dry-cell clamp replaces ehout by -(qsur + wh/delt) when ehout < 0 and wh + (qsur + ehout)*delt < TINYVALUE (F90:233-236); dwh = qsur + ehout (F90:237); d(wh)/dt = dwh (the Fortran advances wh += dwh*DeltaT explicitly once per substep, F90:77; here a continuous ODE, not the limit of that scheme - see README.md, 'Continuous ODEs vs the Fortran 3600-s Euler stepping'); yh = wh (updateState_hillslope, F90:358); and the lateral inflow to the subnetwork etin = (-ehout + qsub)*area*frac (F90:79). Units per mosart_tstatusflux_type.F90 / mosart_tspatialunit_type.F90: wh, yh [m]; dwh, qsur, qsub, ehout [m/s]; etin [m3/s]; hslpsqrt [1]; Gxr [1/m]; area [m2]; frac [1]; nh is the hillslope Manning roughness (SI dimension s/m^(1/3), see mosart_templates.esm); delt is Tctl%DeltaT = delt_coupling/nsub (mosart_driver.F90:800). The qsur/qsub forcing arrives from the cap in m/s (mosart_driver.F90:806-813 converts the m3/s streams by /area). The tests block pins the overland law CREHT_nosqrt pointwise (instantaneous D-boundary tests, time_span {0,0}) and the one-substep storage traces in the continuous-ODE form, with numeric tuples from the EqESM instrumented-CESM dumps (stage1/dumps/mosart/ dry lane window: creht_nosqrt.csv, mosart_euler.csv, area from mosart_run_imports_wide.csv; stage1/dumps/mosart_wet/ wet window: the wet_overland_* pins); the trace assertions carry the measured Euler-vs-continuous scheme gaps (see README.md (Testing)). Reference: stage1/cesm/components/mosart/src/riverroute/mosart_physics.F90 (mosart1.1.13).
- RofCap
model
environmental_transport
mosart
MOSART cap-boundary component (stage 2 of the EqESM project): the med<->rof field conversions of rof_comp_nuopc/rof_import_export.F90 (mosart1.1.13) as algebraic equations, per the stage1/boundaries.md 1.5 boundary table. Imports (med -> rof): Flrl_rofsur, Flrl_rofsub, Flrl_rofgwl, Flrl_rofi, Flrl_irrig (lnd runoff, CMEPS kg/m^2/s which for water equals mm/s), and Fgrg_rofl, Fgrg_rofi (glc runoff, active when rof_from_glc). Exports (rof -> med): Forr_rofl, Forr_rofi, Forr_rofl_glc, Forr_rofi_glc, Flrr_flood, Flrr_volr, Flrr_volrmch, Sr_tdepth, Sr_tdepth_max. Import conversion, exactly state_getimport (rof_import_export.F90:589-595): q [m3/s] = field [mm/s] * med2mod_areacor * area [m2] * 0.001 [m/mm], where med2mod_areacor is the mesh-area correction factor (F90:209-210, ~1 for the rof mesh on the model grid) and 0.001 is spelled as the parameter mm_to_m [m/mm] for dimensional honesty. Export conversion, exactly state_setexport (F90:636-643): field [mm/s] = q [m3/s] * mod2med_areacor / (area [m2] * 0.001 [m/mm]); Flrr_flood carries the sign flip flood = -ctl%flood/(area*0.001) (F90:395, the land->rof positive convention); Flrr_volr = volr/area and Flrr_volrmch = wr/area are depths [m] with no mm scaling (F90:396-397); Sr_tdepth/Sr_tdepth_max are stream depths exported only when flds_r2l_stream_channel_depths (F90:398-402, tdepth_max = max(twidth0,0)*(rdepth/rwidth)). The direct-transfer, irrigation, flood and subcycling orchestration of mosart_run lives in the assembly mosart_routing.esm (its Control model) because the qgwl threshold option and the flood threshold need the channel storage wr; this file keeps the pure unit conversions, per the boundaries.md 2.6 mapping (cap boundary row). The tests block pins the med<->rof import/export unit conversions pointwise (instantaneous tests, time_span {0,0}) from the step-1 boundary values of cell 100312 (EqESM instrumented-CESM dumps stage1/dumps/mosart/mosart_run_imports.csv, mosart_run_exports.csv, and the area/areacor columns of mosart_run_imports_wide.csv); see README.md (Testing). Reference: stage1/cesm/components/mosart/src/cpl/nuopc/rof_import_export.F90 (mosart1.1.13).
- Subnetwork
model
environmental_transport
mosart
MOSART subnetwork (tributary) routing step (stage 2 of the EqESM project): the per-cell Euler step 2 of mosart_physics.F90:Euler (F90:114-132) composed of subnetworkRouting (F90:243-269) and updateState_subnetwork (F90:364-381), written as a storage ODE with the pointwise laws imported from ./mosart_templates.esm. Equations, exactly as in the Fortran: with no tributaries (tlen <= hlen) the subnetwork passes the inflow straight through, etout = -etin (F90:250-252); otherwise the Manning velocity vt = CRVRMAN_nosqrt(tslpsqrt, nt, rt) (F90:253) and etout = -vt*mt (F90:254), with the dry-cell clamp etout = -(etin + wt/localdelt) when wt + (etin + etout)*localdelt < TINYVALUE (F90:255-260), in which case vt = -etout/mt when mt > 0 (F90:257-259); dwt = etin + etout (F90:262); d(wt)/dt = dwt (the Fortran advances wt += dwt*localdelt explicitly per substep, F90:123; here a continuous ODE, not the limit of that scheme - see README.md, 'Continuous ODEs vs the Fortran 3600-s Euler stepping'); updateState_subnetwork (F90:370-380) sets mt = GRMR(wt, tlen), yt = GRHT(mt, twidth), pt = GRPT(yt, twidth), rt = GRRR(mt, pt) when tlen > 0 and wt > 0, and zeroes all four otherwise; and the lateral outflow to the main channel erlateral = -etout (the instantaneous value of the Fortran's per-substep accumulation and numDT_t average, F90:125-127). Units per mosart_tstatusflux_type.F90 / mosart_tspatialunit_type.F90: wt [m3]; etin, etout, dwt, erlateral [m3/s]; vt [m/s]; mt [m2]; yt, rt, pt [m]; tslpsqrt [1]; tlen, hlen, twidth [m]; nt is the subnetwork Manning roughness (SI dimension s/m^(1/3)); localdelt = Tctl%DeltaT/DLevelH2R/numDT_t(nr) (F90:120). One deliberate divergence, documented for reviewers: when tlen <= hlen the Fortran leaves vt stale (it is unused in that branch) while here vt always takes the Manning value; and when the dry-cell clamp fires with mt <= 0 the Fortran also leaves vt at the Manning value, which is what the ifelse expresses. The tests block pins the geometry chain GRMR/GRHT/GRPT/GRRR pointwise (instantaneous tests, time_span {0,0}) and the one-substep storage traces in the continuous-ODE form, with numeric tuples from the EqESM instrumented-CESM dumps (stage1/dumps/mosart/ dry lane window: gr_subnet.csv, crvrman_trib.csv, mosart_euler.csv; stage1/dumps/mosart_wet/ wet window: wet_geometry_* and wet_manning_trib_* pins); the trace assertions carry the measured Euler-vs-continuous scheme gaps (see README.md (Testing)). Reference: stage1/cesm/components/mosart/src/riverroute/mosart_physics.F90 (mosart1.1.13).