Merge branch 'isotope_prep'

Rework water data types to accommodate isotopes and other tracers This tag reworks the various water data types to allow having multiple instances of variables that are needed for isotopes and other water tracers. Specific changes include: (1) Separated "water state" variables into state, diagnostic and balance check-related variables. This separation was not essential for the work here, but was desired by Martyn Clark and others. (2) For each of water state, diagnostic and flux variables, separated variables into those needed for both bulk and tracers vs. those only needed for bulk. This way, we can have multiple instances of the variables needed by tracers, but only a single instance of variables that only apply to bulk water. This follows the design laid out in #395. The separation was based largely on what was done in the old water isotope branch; we didn't put a lot of thought into this, because the new design allows us to easily migrate variables between bulk-only and bulk-and-tracer as needed. (3) Moved water fluxes that were defined in science modules back into waterflux_type or waterfluxbulk_type. This was needed for (2); there is more discussion on this in #395 and the log message for commit 711e5cd. (4) Introduced a top-level water_type that holds instances of all of the other water-related objects. This follows the design laid out in #395. This is particularly valuable for the tracer instances: the logic related to number of tracers can be encapsulated in water_type, rather than infiltrating clm_instMod. (5) Added placeholders for water tracer instances (6) Added infrastructure to generate history / restart field names for the tracer instances. Eventually, the isotope class can also hold information specific to each isotope. This work was a joint effort between Mathew Rothstein and myself; Mat gets much of the credit for the actual refactoring done here. Issues fixed (include CTSM Issue #): - Fixes #358 (Separate WaterStateType into multiple types) - Fixes #434 (Separate WaterFluxType into a base class and a class that just applies to bulk) - Fixes #359 (Set up infrastructure for multiple instances of WaterState and WaterFlux types) - Fixes #458 (Implement handling of history and restart variables for water tracers)
ESCOMP · Aug 3, 2018 · b043949 · b043949
2 parents 8b435be + 0ab3058
commit b043949
Show file tree

Hide file tree

Showing 79 changed files with 5,340 additions and 3,002 deletions.
diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -1,4 +1,163 @@
 ===============================================================
+Tag name:  ctsm1.0.dev005
+Originator(s):  sacks (Bill Sacks), mvr (Mathew Rothstein)
+Date: Fri Aug  3 07:54:59 MDT 2018
+One-line Summary: Rework water data types to accommodate isotopes and other tracers
+
+Purpose of changes
+------------------
+
+This tag reworks the various water data types to allow having multiple
+instances of variables that are needed for isotopes and other water
+tracers.
+
+Specific changes include:
+
+(1) Separated "water state" variables into state, diagnostic and balance
+    check-related variables. This separation was not essential for the
+    work here, but was desired by Martyn Clark and others.
+
+(2) For each of water state, diagnostic and flux variables, separated
+    variables into those needed for both bulk and tracers vs. those only
+    needed for bulk. This way, we can have multiple instances of the
+    variables needed by tracers, but only a single instance of variables
+    that only apply to bulk water. This follows the design laid out in
+    https://github.com/escomp/ctsm/pull/395. The separation was based
+    largely on what was done in the old water isotope branch; we didn't
+    put a lot of thought into this, because the new design allows us to
+    easily migrate variables between bulk-only and bulk-and-tracer as
+    needed.
+
+(3) Moved water fluxes that were defined in science modules back into
+    waterflux_type or waterfluxbulk_type. This was needed for (2); there
+    is more discussion on this in
+    https://github.com/escomp/ctsm/pull/395 and the log message for
+    commit 711e5cd7.
+
+(4) Introduced a top-level water_type that holds instances of all of the
+    other water-related objects. This follows the design laid out in
+    https://github.com/escomp/ctsm/pull/395. This is particularly
+    valuable for the tracer instances: the logic related to number of
+    tracers can be encapsulated in water_type, rather than infiltrating
+    clm_instMod.
+
+(5) Added placeholders for water tracer instances
+
+(6) Added infrastructure to generate history / restart field names for
+    the tracer instances. Eventually, the isotope class can also hold
+    information specific to each isotope.
+
+This work was a joint effort between Mathew Rothstein and myself; Mat
+gets much of the credit for the actual refactoring done here.
+
+
+Bugs fixed or introduced
+------------------------
+
+Issues fixed (include CTSM Issue #):
+- Fixes #358 (Separate WaterStateType into multiple types)
+- Fixes #434 (Separate WaterFluxType into a base class and a class that just applies to bulk)
+- Fixes #359 (Set up infrastructure for multiple instances of WaterState and WaterFlux types)
+- Fixes #458 (Implement handling of history and restart variables for water tracers)
+
+Known bugs introduced in this tag (include github issue ID):
+- #464 (Some lines longer than 132 characters)
+- #456 (Remove backwards compatibility check for snw_rds) (not a
+  newly-introduced issue, but it's more important to fix this with the
+  separation of waterstate_type)
+
+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.]
+
+[ ] clm5_0
+
+[ ] clm4_5
+
+[ ] clm4_0
+
+Notes of particular relevance for users
+---------------------------------------
+
+Caveats for users (e.g., need to interpolate initial conditions): none
+
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables): none
+
+Changes made to namelist defaults (e.g., changed parameter values): none
+
+Changes to the datasets (e.g., parameter, surface or initial files): none
+
+Substantial timing or memory changes: none
+
+Notes of particular relevance for developers: (including Code reviews and testing)
+---------------------------------------------
+NOTE: Be sure to review the steps in .CTSMTrunkChecklist as well as the coding style in the Developers Guide
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+- Water tracers are not yet functional - they are just placeholders
+- Whether to use water tracers and which water tracers to use are
+  currently hard-coded; eventually, this should be namelist-controlled
+
+Changes to tests or testing: none
+
+Code reviewed by: Mathew Rothstein and Bill Sacks worked together on
+these changes and reviewed each other's changes to some extent. The
+high-level design was also reviewed and co-developed by Mariana
+Vertenstein. Martyn Clark contributed substantially to the breakout of
+water state into state, diagnostic and balance check-related variables.
+
+
+CTSM testing:
+
+ [PASS means all tests PASS and OK means tests PASS other than expected fails.]
+
+  build-namelist tests:
+
+    cheyenne - not run
+
+  unit-tests (components/clm/src):
+
+    cheyenne - pass
+
+  tools-tests (components/clm/test/tools):
+
+    cheyenne - not run
+
+  PTCLM testing (components/clm/tools/shared/PTCLM/test):
+
+     cheyenne - not run
+
+  regular tests (aux_clm):
+
+    cheyenne_intel ---- pass
+    cheyenne_gnu ------ pass
+    hobart_nag -------- pass
+    hobart_pgi -------- pass
+    hobart_intel ------ pass
+
+CTSM tag used for the baseline comparisons: ctsm1.0.dev004
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: NO - bit-for-bit
+
+
+Detailed list of changes
+------------------------
+
+List any externals directories updated (cime, rtm, mosart, cism, fates, etc.): none
+
+Pull Requests that document the changes (include PR ids):
+- https://github.com/escomp/ctsm/pull/395 (documents the high-level design)
+
+===============================================================
+===============================================================
 Tag name:  ctsm1.0.dev004
 Originator(s):  erik (Erik Kluzek,UCAR/TSS,303-497-1326)
 Date: Wed Jul 18 02:10:23 MDT 2018

diff --git a/doc/ChangeSum b/doc/ChangeSum
@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+  ctsm1.0.dev005    sacks 08/03/2018 Rework water data types to accommodate isotopes and other tracers
   ctsm1.0.dev004     erik 07/18/2018 Add some new diagnostic fields, fix a few issues, update cmip6 output
   ctsm1.0.dev003     erik 07/15/2018 Update cime/cism to work on upgraded hobart and with glade changes on cheyenne
   ctsm1.0.dev002     erik 07/06/2018 Fix NFIX flux variables so special land-units are zeroed out, tools update, add some *_MAX fields on mksurfdata_map for transient cases

diff --git a/src/biogeochem/CNDriverMod.F90 b/src/biogeochem/CNDriverMod.F90
@@ -28,8 +28,9 @@ module CNDriverMod
   use CanopyStateType                 , only : canopystate_type
   use SoilStateType                   , only : soilstate_type
   use TemperatureType                 , only : temperature_type
-  use WaterstateType                  , only : waterstate_type
-  use WaterfluxType                   , only : waterflux_type
+  use WaterStateBulkType                  , only : waterstatebulk_type
+  use WaterDiagnosticBulkType                  , only : waterdiagnosticbulk_type
+  use WaterFluxBulkType                   , only : waterfluxbulk_type
   use atm2lndType                     , only : atm2lnd_type
   use SoilStateType                   , only : soilstate_type
   use TemperatureType                 , only : temperature_type 
@@ -89,7 +90,7 @@ subroutine CNDriverNoLeaching(bounds,
        c14_soilbiogeochem_carbonflux_inst, c14_soilbiogeochem_carbonstate_inst,            &
        soilbiogeochem_state_inst,                                                          &
        soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst,                &
-       atm2lnd_inst, waterstate_inst, waterflux_inst,                                      &
+       atm2lnd_inst, waterstatebulk_inst, waterdiagnosticbulk_inst, waterfluxbulk_inst,                                      &
        canopystate_inst, soilstate_inst, temperature_inst, crop_inst, ch4_inst,            &
        dgvs_inst, photosyns_inst, saturated_excess_runoff_inst, energyflux_inst,                   &
        nutrient_competition_method, cnfire_method)
@@ -166,8 +167,9 @@ subroutine CNDriverNoLeaching(bounds,
     type(soilbiogeochem_nitrogenflux_type)  , intent(inout) :: soilbiogeochem_nitrogenflux_inst
     type(soilbiogeochem_nitrogenstate_type) , intent(inout) :: soilbiogeochem_nitrogenstate_inst
     type(atm2lnd_type)                      , intent(in)    :: atm2lnd_inst
-    type(waterstate_type)                   , intent(in)    :: waterstate_inst
-    type(waterflux_type)                    , intent(inout)    :: waterflux_inst
+    type(waterstatebulk_type)                   , intent(in)    :: waterstatebulk_inst
+    type(waterdiagnosticbulk_type)                   , intent(in)    :: waterdiagnosticbulk_inst
+    type(waterfluxbulk_type)                    , intent(inout)    :: waterfluxbulk_inst
     type(canopystate_type)                  , intent(inout)    :: canopystate_inst
     type(soilstate_type)                    , intent(inout) :: soilstate_inst
     type(temperature_type)                  , intent(inout) :: temperature_inst
@@ -268,7 +270,7 @@ subroutine CNDriverNoLeaching(bounds,
     if(use_fun)then
         call t_startf('CNFLivFixation')
         call CNFreeLivingFixation( num_soilc, filter_soilc, &
-             waterflux_inst, soilbiogeochem_nitrogenflux_inst)
+             waterfluxbulk_inst, soilbiogeochem_nitrogenflux_inst)
         call t_stopf('CNFLivFixation')
     else
        call t_startf('CNFixation')
@@ -284,7 +286,7 @@ subroutine CNDriverNoLeaching(bounds,
 
        if (.not. use_fun) then  ! if FUN is active, then soy fixation handled by FUN
           call  CNSoyfix (bounds, num_soilc, filter_soilc, num_soilp, filter_soilp, &
-               waterstate_inst, crop_inst, cnveg_state_inst, cnveg_nitrogenflux_inst , &
+               waterdiagnosticbulk_inst, crop_inst, cnveg_state_inst, cnveg_nitrogenflux_inst , &
                soilbiogeochem_state_inst, soilbiogeochem_nitrogenstate_inst, soilbiogeochem_nitrogenflux_inst)
        end if
     end if
@@ -323,7 +325,7 @@ subroutine CNDriverNoLeaching(bounds,
     ! calculate nitrification and denitrification rates (previously subroutine nitrif_denitrif called from CNDecompAlloc)
     if (use_nitrif_denitrif) then 
        call SoilBiogeochemNitrifDenitrif(bounds, num_soilc, filter_soilc, &
-            soilstate_inst, waterstate_inst, temperature_inst, ch4_inst, &
+            soilstate_inst, waterstatebulk_inst, temperature_inst, ch4_inst, &
             soilbiogeochem_carbonflux_inst, soilbiogeochem_nitrogenstate_inst, soilbiogeochem_nitrogenflux_inst)
     end if
     call t_stopf('SoilBiogeochem')
@@ -349,7 +351,7 @@ subroutine CNDriverNoLeaching(bounds,
        call t_startf('CNPhenology_phase1')
        call CNPhenology (bounds, num_soilc, filter_soilc, num_soilp, &
             filter_soilp, num_pcropp, filter_pcropp, &
-            doalb, waterstate_inst, temperature_inst, atm2lnd_inst, &
+            doalb, waterdiagnosticbulk_inst, temperature_inst, atm2lnd_inst, &
             crop_inst, canopystate_inst, soilstate_inst, dgvs_inst, &
             cnveg_state_inst, cnveg_carbonstate_inst, cnveg_carbonflux_inst, &
             cnveg_nitrogenstate_inst, cnveg_nitrogenflux_inst, &
@@ -387,8 +389,8 @@ subroutine CNDriverNoLeaching(bounds,
 
 
      call t_startf('soilbiogeochemcompetition')
-     call SoilBiogeochemCompetition (bounds, num_soilc, filter_soilc,num_soilp, filter_soilp, waterstate_inst, &
-                                     waterflux_inst,temperature_inst,soilstate_inst,cnveg_state_inst,          &
+     call SoilBiogeochemCompetition (bounds, num_soilc, filter_soilc,num_soilp, filter_soilp, waterstatebulk_inst, &
+                                     waterfluxbulk_inst,temperature_inst,soilstate_inst,cnveg_state_inst,          &
                                      cnveg_carbonstate_inst               ,&
                                      cnveg_carbonflux_inst,cnveg_nitrogenstate_inst,cnveg_nitrogenflux_inst,   &
                                      soilbiogeochem_carbonflux_inst,&
@@ -444,7 +446,7 @@ subroutine CNDriverNoLeaching(bounds,
     if ( .not. use_fun ) then
        call CNPhenology (bounds, num_soilc, filter_soilc, num_soilp, &
             filter_soilp, num_pcropp, filter_pcropp, &
-            doalb, waterstate_inst, temperature_inst, atm2lnd_inst, &
+            doalb, waterdiagnosticbulk_inst, temperature_inst, atm2lnd_inst, &
             crop_inst, canopystate_inst, soilstate_inst, dgvs_inst, &
             cnveg_state_inst, cnveg_carbonstate_inst, cnveg_carbonflux_inst, &
             cnveg_nitrogenstate_inst, cnveg_nitrogenflux_inst, &
@@ -455,7 +457,7 @@ subroutine CNDriverNoLeaching(bounds,
     end if
     call CNPhenology (bounds, num_soilc, filter_soilc, num_soilp, &
          filter_soilp, num_pcropp, filter_pcropp, &
-         doalb, waterstate_inst, temperature_inst, atm2lnd_inst, &
+         doalb, waterdiagnosticbulk_inst, temperature_inst, atm2lnd_inst, &
          crop_inst, canopystate_inst, soilstate_inst, dgvs_inst, &
          cnveg_state_inst, cnveg_carbonstate_inst, cnveg_carbonflux_inst, &
          cnveg_nitrogenstate_inst, cnveg_nitrogenflux_inst, &
@@ -744,7 +746,7 @@ subroutine CNDriverNoLeaching(bounds,
 
     call t_startf('CNFire')
     call cnfire_method%CNFireArea(bounds, num_soilc, filter_soilc, num_soilp, filter_soilp, &
-         atm2lnd_inst, energyflux_inst, saturated_excess_runoff_inst, waterstate_inst, &
+         atm2lnd_inst, energyflux_inst, saturated_excess_runoff_inst, waterdiagnosticbulk_inst, &
          cnveg_state_inst, cnveg_carbonstate_inst, &
          totlitc_col=soilbiogeochem_carbonstate_inst%totlitc_col(begc:endc), &
          decomp_cpools_vr_col=soilbiogeochem_carbonstate_inst%decomp_cpools_vr_col(begc:endc,1:nlevdecomp_full,1:ndecomp_pools), &
@@ -818,7 +820,7 @@ end subroutine CNDriverNoLeaching
   !-----------------------------------------------------------------------
   subroutine CNDriverLeaching(bounds, &
        num_soilc, filter_soilc, num_soilp, filter_soilp, &
-       waterstate_inst, waterflux_inst, &
+       waterstatebulk_inst, waterfluxbulk_inst, &
        cnveg_nitrogenflux_inst, cnveg_nitrogenstate_inst, &
        soilbiogeochem_nitrogenflux_inst, soilbiogeochem_nitrogenstate_inst)
     !
@@ -836,8 +838,8 @@ subroutine CNDriverLeaching(bounds, &
     integer                                 , intent(in)    :: filter_soilc(:)   ! filter for soil columns
     integer                                 , intent(in)    :: num_soilp         ! number of soil patches in filter
     integer                                 , intent(in)    :: filter_soilp(:)   ! filter for soil patches
-    type(waterstate_type)                   , intent(in)    :: waterstate_inst
-    type(waterflux_type)                    , intent(inout)    :: waterflux_inst
+    type(waterstatebulk_type)                   , intent(in)    :: waterstatebulk_inst
+    type(waterfluxbulk_type)                    , intent(inout)    :: waterfluxbulk_inst
     type(cnveg_nitrogenflux_type)           , intent(inout) :: cnveg_nitrogenflux_inst
     type(cnveg_nitrogenstate_type)          , intent(inout) :: cnveg_nitrogenstate_inst
     type(soilbiogeochem_nitrogenflux_type)  , intent(inout) :: soilbiogeochem_nitrogenflux_inst
@@ -848,7 +850,7 @@ subroutine CNDriverLeaching(bounds, &
 
     call t_startf('SoilBiogeochemNLeaching')
     call SoilBiogeochemNLeaching(bounds, num_soilc, filter_soilc, &
-         waterstate_inst, waterflux_inst, soilbiogeochem_nitrogenstate_inst, &
+         waterstatebulk_inst, waterfluxbulk_inst, soilbiogeochem_nitrogenstate_inst, &
          soilbiogeochem_nitrogenflux_inst)
     call t_stopf('SoilBiogeochemNLeaching')
 

diff --git a/src/biogeochem/CNFUNMod.F90 b/src/biogeochem/CNFUNMod.F90
@@ -36,8 +36,8 @@ module CNFUNMod
   use SoilBiogeochemNitrogenStateType  , only : soilbiogeochem_nitrogenstate_type
 
   use SoilBiogeochemCarbonFluxType    , only : soilbiogeochem_carbonflux_type
-  use WaterStateType                  , only : waterstate_type
-  use WaterfluxType                   , only : waterflux_type
+  use WaterStateBulkType                  , only : waterstatebulk_type
+  use WaterFluxBulkType                   , only : waterfluxbulk_type
   use TemperatureType                 , only : temperature_type
   use SoilStateType                   , only : soilstate_type
   use CanopyStateType                 , only : canopystate_type
@@ -200,8 +200,8 @@ end subroutine CNFUNInit
   !--------------------------------------------------------------------
   !---
   subroutine CNFUN(bounds,num_soilc, filter_soilc,num_soilp&
-       &,filter_soilp,waterstate_inst                 ,&
-       & waterflux_inst,temperature_inst,soilstate_inst&
+       &,filter_soilp,waterstatebulk_inst, &
+       & waterfluxbulk_inst,temperature_inst,soilstate_inst&
        &,cnveg_state_inst,cnveg_carbonstate_inst,&
        & cnveg_carbonflux_inst,cnveg_nitrogenstate_inst&
        &,cnveg_nitrogenflux_inst                ,&
@@ -224,8 +224,8 @@ subroutine CNFUN(bounds,num_soilc, filter_soilc,num_soilp&
    integer                                 , intent(in)    :: filter_soilc(:)       ! filter for soil columns
    integer                                 , intent(in)    :: num_soilp             ! number of soil patches in filter
    integer                                 , intent(in)    :: filter_soilp(:)       ! filter for soil patches
-   type(waterstate_type)                   , intent(in)    :: waterstate_inst
-   type(waterflux_type)                    , intent(in)    :: waterflux_inst
+   type(waterstatebulk_type)                   , intent(in)    :: waterstatebulk_inst
+   type(waterfluxbulk_type)                    , intent(in)    :: waterfluxbulk_inst
    type(temperature_type)                  , intent(in)    :: temperature_inst
    type(soilstate_type)                    , intent(in)    :: soilstate_inst
    type(cnveg_state_type)                  , intent(inout) :: cnveg_state_inst
@@ -706,9 +706,9 @@ subroutine CNFUN(bounds,num_soilc, filter_soilc,num_soilp&
          !  NO3              
          soilc_change           => cnveg_carbonflux_inst%soilc_change_patch               , & ! Output:  [real(r8)
          !  (:) ]  Used C from the soil (gC/m2/s)
-         h2osoi_liq             => waterstate_inst%h2osoi_liq_col                                , & ! Input:   [real(r8) (:,:)]
+         h2osoi_liq             => waterstatebulk_inst%h2osoi_liq_col                                , & ! Input:   [real(r8) (:,:)]
          !   liquid water (kg/m2) (new) (-nlevsno+1:nlevgrnd)
-         qflx_tran_veg          => waterflux_inst%qflx_tran_veg_patch                            , & ! Input:   [real(r8) (:)  ]
+         qflx_tran_veg          => waterfluxbulk_inst%qflx_tran_veg_patch                            , & ! Input:   [real(r8) (:)  ]
          !   vegetation transpiration (mm H2O/s) (+ = to atm)
          t_soisno               => temperature_inst%t_soisno_col                                 , & ! Input:   [real(r8) (:,:)]
          !   soil temperature (Kelvin)  (-nlevsno+1:nlevgrnd)