Merge pull request #3683 from swensosc/oversaturation

ctsm5.4.008: Oversaturation

Author: ekluzek

doc/.ChangeLog_template

@@ -146,13 +146,12 @@ Changes answers relative to baseline:
    only by roundoff level (because order of operation changes for example). Roundoff
    changes to state fields usually grow to greater than roundoff as the simulation progresses.
 
-   If this tag changes climate describe the run(s) done to evaluate the new
-   climate (put details of the simulations in the experiment database)
-       - casename:
-
-   URL for LMWG diagnostics output used to validate new climate:
-
+   If this tag changes climate list the run(s) done to evaluate the new
+   climate (from https://github.com/NCAR/LMWG_dev)
+       - issue number:
 
+   URL for LDF diagnostics output used to validate new climate:
+       - 
 Other details
 -------------
 [Remove any lines that don't apply. Remove entire section if nothing applies.]

doc/ChangeLog

@@ -1,4 +1,84 @@
 ===============================================================
+Tag name: ctsm5.4.008
+Originator(s): swensosc (Sean Swenson)
+Date: Mon Jan 12 11:19:38 PM MST 2026
+One-line Summary: Add a correction for oversaturated soil layers in SoilWaterMovement
+
+Purpose and description of changes
+----------------------------------
+
+Add a correction for oversaturated soil layers immediately after the soil water flux calculation in SoilWaterMovementMod.
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+  Second checkbox in #3879 -- placeholder issue soil water movement
+
+Notes of particular relevance for users
+---------------------------------------
+
+Notes of particular relevance for developers:
+---------------------------------------------
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+    
+
+Testing summary: regular
+----------------
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+If the tag used for baseline comparisons was NOT the previous tag, note that here:
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: Yes! Changes in most fields
+
+  Summarize any changes to answers, i.e.,
+    - what code configurations: All
+    - what platforms/compilers: All
+    - nature of change (larger than roundoff/same climate)
+
+   If this tag changes climate list the run(s) done to evaluate the new
+   climate (from https://github.com/NCAR/LMWG_dev)
+       - issue number: 132
+
+   URL for LMWG diagnostics output used to validate new climate:
+       - https://webext.cgd.ucar.edu/I20TR/ctsm5.4.004_bgc_f09_131_HIST/lnd/ctsm5.4.004_bgc_f09_Oversaturation_131b_HIST_1994_2023_vs_ctsm5.4.004_bgc_f09_131_HIST_1994_2023/website/
+
+
+Other details
+-------------
+
+Pull Requests that document the changes (include PR ids):
+(https://github.com/ESCOMP/ctsm/pull)
+    #3683 -- Oversaturation
+
+===============================================================
+===============================================================
 Tag name: ctsm5.4.007
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Fri Jan  9 11:53:19 MST 2026

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.4.008 swensosc 01/12/2026 Add a correction for oversaturated soil layers in SoilWaterMovement (erik)
        ctsm5.4.007 samrabin 01/09/2026 Update (irrigated_)rice grnfill and lfemerg
        ctsm5.4.006     erik 01/07/2026 Merge b4b-dev to master
        ctsm5.4.005   rgknox 12/19/2025 FATES JSON parameter files

src/biogeophys/SoilWaterMovementMod.F90

@@ -1147,8 +1147,7 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
     real(r8) :: vLiqIter(bounds%begc:bounds%endc,1:nlevsoi)   !  iteration increment for the volumetric liquid water content (v/v)
     real(r8) :: vLiqRes(bounds%begc:bounds%endc,1:nlevsoi)   ! residual for the volumetric liquid water content (v/v)
 
-    real(r8) :: dwat_temp
-    real(r8) :: over_saturation 
+    real(r8) :: over_saturation  ! Amount of water that over saturates this soil layer [kg/m2]
     !-----------------------------------------------------------------------
 
     associate(&
@@ -1163,6 +1162,7 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
          zwt               =>    soilhydrology_inst%zwt_col         , & ! Input:  [real(r8) (:)   ]  water table depth (m)                             
          qout_col          =>    soilhydrology_inst%qout_col        , & ! Output: [real(r8) (:,:) ]  soil water out of the bottom, mm h2o/s
          qin_col           =>    soilhydrology_inst%qin_col         , & ! Output: [real(r8) (:,:) ]  soil water into the bottom, mm h2o/s
+         eff_porosity      =>    soilstate_inst%eff_porosity_col    , & ! Input:  [real(r8) (:,:) ]  effective porosity = porosity - vol_ice         
          watsat            =>    soilstate_inst%watsat_col          , & ! Input:  [real(r8) (:,:) ] volumetric soil water at saturation (porosity)
          smp_l             =>    soilstate_inst%smp_l_col           , & ! Input:  [real(r8) (:,:) ]  soil matrix potential [mm]                      
          hk_l              =>    soilstate_inst%hk_l_col            , & ! Input:  [real(r8) (:,:) ]  hydraulic conductivity (mm/s)                   
@@ -1183,8 +1183,6 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
          ! set number of layers over which to solve soilwater movement
          nlayers = nbedrock(c)
 
-         dwat_temp = 0.
-
          ! initialize the number of substeps
          nsubstep=0
 
@@ -1403,6 +1401,13 @@ subroutine soilwater_moisture_form(bounds, num_hydrologyc, &
          !  save number of adaptive substeps used during time step
          nsubsteps(c) = nsubstep
 
+         ! check for over-saturated layers and move excess upward
+         do j = nlayers,2,-1
+            over_saturation   = max(h2osoi_liq(c,j)-(eff_porosity(c,j)*m_to_mm*dz(c,j)),0._r8)
+            h2osoi_liq(c,j)   = min(eff_porosity(c,j)*m_to_mm*dz(c,j), h2osoi_liq(c,j))
+            h2osoi_liq(c,j-1) = h2osoi_liq(c,j-1) + over_saturation
+         end do
+
          ! check for negative moisture values
          do j = 2, nlayers
             if(h2osoi_liq(c,j) < -1e-6_r8) then