Merge pull request ESCOMP#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.

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
     ! ------------------------------------------------------------------------