Merge pull request #8 from NCAR/modularize_infiltration_p3

Finish Infiltration modularization - mainly h2osfc updates

Finish the modularization of subroutine Infiltration. The main focus
here is modularizing the calculation of fluxes out of h2osfc and the
updates of the h2osfc state variable. Flux calculations and state
updates are now done separately. Where a flux calculation depends on a
partially-updated version of h2osfc, this is now made explicit in a way
that could facilitate removing this partial update later.

ChangeLog_branch

@@ -1,4 +1,84 @@
 ===============================================================
+Tag name: ctsm_n08_clm4_5_16_r249
+Originator(s): sacks
+Date: Aug 24, 2017
+One-line Summary: Finish Infiltration modularization - mainly h2osfc updates
+
+Purpose of changes
+------------------
+
+Finish the modularization of subroutine Infiltration. The main focus here is
+modularizing the calculation of fluxes out of h2osfc and the updates of the
+h2osfc state variable. Flux calculations and state updates are now done
+separately. Where a flux calculation depends on a partially-updated version of
+h2osfc, this is now made explicit in a way that could facilitate removing this
+partial update later.
+
+
+Notes of particular relevance for developers: (including Code reviews and testing)
+---------------------------------------------
+
+CLM testing:
+
+  build-namelist tests:
+
+    yellowstone - not run
+
+  unit-tests (components/clm/src):
+
+    yellowstone - pass
+
+  tools-tests (components/clm/test/tools):
+
+    yellowstone - not run
+
+  PTCLM testing (components/clm/tools/shared/PTCLM/test):
+
+     yellowstone - not run
+
+  regular tests (aux_clm):
+
+    yellowstone_intel - pass
+    yellowstone_pgi - pass
+    yellowstone_gnu - pass
+    cheyenne_intel - pass
+    hobart_nag - pass
+    hobart_pgi - pass
+    hobart_intel - pass
+
+CLM tag used for the baseline comparisons: ctsm_n07_clm4_5_16_r249
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: NO
+
+
+Detailed list of changes
+------------------------
+
+List any svn externals directories updated (cime, rtm, mosart, cism, etc.): none
+
+List all files eliminated: none
+
+List all files added and what they do: none
+
+List all existing files that have been modified, and describe the changes:
+
+========= Main changes, as described above
+M       components/clm/src/biogeophys/SoilHydrologyMod.F90
+M       components/clm/src/biogeophys/HydrologyNoDrainageMod.F90
+M       components/clm/src/biogeophys/HydrologyDrainageMod.F90
+M       components/clm/src/biogeophys/WaterfluxType.F90
+
+========= Tweak some comments based on feedback on
+          https://github.com/NCAR/clm-ctsm/pull/2
+M       components/clm/src/biogeophys/InfiltrationExcessRunoffMod.F90
+M       components/clm/src/biogeophys/SaturatedExcessRunoffMod.F90
+
+===============================================================
+===============================================================
 Tag name: ctsm_n07_clm4_5_16_r249
 Originator(s): sacks
 Date: Aug 22, 2017

src/biogeophys/HydrologyDrainageMod.F90

@@ -185,6 +185,7 @@ subroutine HydrologyDrainage(bounds,               &
 
             qflx_drain_perched(c) = 0._r8
             qflx_rsub_sat(c)      = spval
+            qflx_infl(c)          = 0._r8
 
          end if
 

src/biogeophys/HydrologyNoDrainageMod.F90

@@ -62,7 +62,8 @@ subroutine HydrologyNoDrainage(bounds, &
     use SnowHydrologyMod     , only : SnowCompaction, CombineSnowLayers, DivideSnowLayers, SnowCapping
     use SnowHydrologyMod     , only : SnowWater, BuildSnowFilter 
     use SoilHydrologyMod     , only : CLMVICMap, SetSoilWaterFractions
-    use SoilHydrologyMod     , only : SetQflxInputs, Infiltration, TotalSurfaceRunoff
+    use SoilHydrologyMod     , only : SetQflxInputs, RouteInfiltrationExcess, UpdateH2osfc
+    use SoilHydrologyMod     , only : Infiltration, TotalSurfaceRunoff
     use SoilHydrologyMod     , only : UpdateUrbanPonding
     use SoilHydrologyMod     , only : WaterTable, PerchedWaterTable
     use SoilHydrologyMod     , only : ThetaBasedWaterTable, RenewCondensation
@@ -194,11 +195,17 @@ subroutine HydrologyNoDrainage(bounds, &
            soilhydrology_inst, soilstate_inst, saturated_excess_runoff_inst, waterflux_inst, &
            waterstate_inst)
 
-      call Infiltration(bounds, num_hydrologyc, filter_hydrologyc, num_urbanc, filter_urbanc,&
+      call RouteInfiltrationExcess(bounds, num_hydrologyc, filter_hydrologyc, &
+           waterflux_inst, infiltration_excess_runoff_inst, soilhydrology_inst)
+
+      call UpdateH2osfc(bounds, num_hydrologyc, filter_hydrologyc, &
            infiltration_excess_runoff_inst, &
-           energyflux_inst, soilhydrology_inst, saturated_excess_runoff_inst, &
+           energyflux_inst, soilhydrology_inst, &
            waterflux_inst, waterstate_inst)
 
+      call Infiltration(bounds, num_hydrologyc, filter_hydrologyc, &
+           waterflux_inst)
+
       call TotalSurfaceRunoff(bounds, num_hydrologyc, filter_hydrologyc, &
            num_urbanc, filter_urbanc, &
            waterflux_inst, soilhydrology_inst, saturated_excess_runoff_inst, waterstate_inst)

src/biogeophys/InfiltrationExcessRunoffMod.F90

@@ -36,7 +36,7 @@ module InfiltrationExcessRunoffMod
      ! Both of these give averages over the entire column. However, qinmax is implicitly
      ! 0 over the fraction of the column given by fsat, and qflx_infl_excess is
      ! implicitly 0 over both fsat and frac_h2osfc.
-     real(r8), pointer, public :: qinmax_col(:)  ! maximum infiltration capacity (mm H2O /s)
+     real(r8), pointer, public :: qinmax_col(:)  ! maximum infiltration rate (mm H2O /s)
      real(r8), pointer, public :: qflx_infl_excess_col(:)  ! infiltration excess runoff (mm H2O /s)
 
      ! Private data members
@@ -186,13 +186,13 @@ subroutine InfiltrationExcessRunoff(this, bounds, num_hydrologyc, filter_hydrolo
     !
     ! !LOCAL VARIABLES:
     integer  :: fc, c
-    real(r8) :: qinmax_on_unsaturated_area(bounds%begc:bounds%endc) ! maximum infiltration capacity on the unsaturated fraction of the column (mm H2O /s)
+    real(r8) :: qinmax_on_unsaturated_area(bounds%begc:bounds%endc) ! maximum infiltration rate on the unsaturated fraction of the column (mm H2O /s)
 
     character(len=*), parameter :: subname = 'InfiltrationExcessRunoff'
     !-----------------------------------------------------------------------
 
     associate( &
-         qinmax           =>    this%qinmax_col                     , & ! Output: [real(r8) (:)   ]  maximum infiltration capacity (mm H2O /s)
+         qinmax           =>    this%qinmax_col                     , & ! Output: [real(r8) (:)   ]  maximum infiltration rate (mm H2O /s)
          qflx_infl_excess =>    this%qflx_infl_excess_col           , & ! Output: [real(r8) (:)   ]  infiltration excess runoff (mm H2O /s)
 
          fsat             =>   saturated_excess_runoff_inst%fsat_col, & ! Input:  [real(r8) (:)   ]  fractional area with water table at surface       
@@ -245,7 +245,7 @@ subroutine ComputeQinmaxHksat(bounds, num_hydrologyc, filter_hydrologyc, &
     integer, intent(in) :: filter_hydrologyc(:) ! column filter for soil points
     type(soilhydrology_type) , intent(in) :: soilhydrology_inst
     type(soilstate_type), intent(in) :: soilstate_inst
-    real(r8), intent(inout) :: qinmax_on_unsaturated_area( bounds%begc: ) ! maximum infiltration capacity on the unsaturated fraction of the column (mm H2O /s)
+    real(r8), intent(inout) :: qinmax_on_unsaturated_area( bounds%begc: ) ! maximum infiltration rate on the unsaturated fraction of the column (mm H2O /s)
     !
     ! !LOCAL VARIABLES:
     integer :: fc, c
@@ -288,15 +288,15 @@ subroutine ComputeQinmaxVic(bounds, num_hydrologyc, filter_hydrologyc, &
     type(soilhydrology_type) , intent(in) :: soilhydrology_inst
     real(r8) , intent(in)    :: fsat( bounds%begc: )                       ! fractional area with water table at surface
     real(r8) , intent(in)    :: qflx_in_soil( bounds%begc: )               ! surface input to soil (mm/s)
-    real(r8) , intent(inout) :: qinmax_on_unsaturated_area( bounds%begc: ) ! maximum infiltration capacity on the unsaturated fraction of the column (mm H2O /s)
+    real(r8) , intent(inout) :: qinmax_on_unsaturated_area( bounds%begc: ) ! maximum infiltration rate on the unsaturated fraction of the column (mm H2O /s)
     !
     ! !LOCAL VARIABLES:
     integer  :: fc, c
     real(r8) :: dtime       ! land model time step (sec)
     real(r8) :: top_icefrac ! ice fraction in top VIC layers
-    real(r8) :: max_infil   ! max infiltration capacity in VIC (mm)
+    real(r8) :: max_infil   ! max infiltration capacity using the VIC parameterization (mm)
     real(r8) :: i_0         ! average soil moisture in top VIC layers (mm)
-    real(r8) :: rsurf_vic   ! VIC surface runoff
+    real(r8) :: rsurf_vic   ! surface runoff based on the VIC parameterization
     real(r8) :: basis       ! variable soil moisture holding capacity in top VIC layers for runoff calculation
 
     character(len=*), parameter :: subname = 'ComputeQinmaxVic'

src/biogeophys/SaturatedExcessRunoffMod.F90

@@ -231,7 +231,7 @@ subroutine SaturatedExcessRunoff (this, bounds, num_hydrologyc, filter_hydrology
     ! ------------------------------------------------------------------------
     ! Compute qflx_sat_excess_surf
     !
-    ! assume qinmax (maximum infiltration capacity) is large relative to
+    ! assume qinmax (maximum infiltration rate) is large relative to
     ! qflx_rain_plus_snomelt in control
     ! ------------------------------------------------------------------------