Do not allow instantaneous fields on same history tape as other fields

cime_config/testdefs/testmods_dirs/clm/crop/user_nl_clm

@@ -15,3 +15,5 @@ hist_nhtfrq(3) = 17520
 hist_mfilt(3) = 1
 hist_type1d_pertape(3) = 'PFTS'
 hist_dov2xy(3) = .false.
+hist_avgflag_pertape(3) = 'I'
+

cime_config/testdefs/testmods_dirs/clm/extra_outputs/user_nl_clm

@@ -1,6 +1,6 @@
 calc_human_stress_indices = 'ALL'
 hist_master_list_file = .true.
 
-hist_fincl1   += 'GSSUN:L43200', 'GSSHA:L43200', 'FSDSND:L43200', 'FSRND:L43200', 'FSRSFND:L43200', 
-                 'SSRE_FSRND:L43200', 'FSDSVD:L43200', 'FSDSVI:L43200',
-                 'FSRVD:L43200', 'FSRSFVD:L43200', 'SSRE_FSRVD:L43200'
+hist_fincl3 = 'GSSUN', 'GSSHA', 'FSDSND', 'FSRND', 'FSRSFND', 'SSRE_FSRND',
+              'FSDSVD', 'FSDSVI', 'FSRVD', 'FSRSFVD', 'SSRE_FSRVD'
+hist_avgflag_pertape(3) = 'L43200'

cime_config/usermods_dirs/_includes/output_base_highfreq/user_nl_clm

@@ -20,11 +20,21 @@ hist_fincl7 += 'TREFMXAV','TREFMNAV'
 
 ! h7 stream (3-hourly average, gridcell-level)
 ! 3hr, E3hr, CF3hr
-! 3hr requires QRUNOFF for time mean, and SOILWATER_10CM, TSKIN for time point (I)
-! CF3hr requires QFLX_SOLIDEVAP_FROM_TOP_LAYER for time point (I)
+! 3hr requires QRUNOFF for time mean
 hist_mfilt(8) = 2920
 hist_dov2xy(8) = .true.
 hist_nhtfrq(8) = -3
 hist_type1d_pertape(8) = ' '
-hist_fincl8 += 'TSA','RH2M','SOILWATER_10CM:I','FSH','EFLX_LH_TOT','FSDS','QRUNOFF','QFLX_SOLIDEVAP_FROM_TOP_LAYER:I','TSKIN:I'
+hist_fincl8 += 'TSA','RH2M','FSH','EFLX_LH_TOT','FSDS','QRUNOFF'
+
+! h8 stream (3-hourly average, gridcell-level)
+! 3hr, E3hr, CF3hr
+! 3hr requires SOILWATER_10CM, TSKIN for time point (I)
+! CF3hr requires QFLX_SOLIDEVAP_FROM_TOP_LAYER for time point (I)
+hist_mfilt(9) = 2920
+hist_dov2xy(9) = .true.
+hist_nhtfrq(9) = -3
+hist_type1d_pertape(9) = ' '
+hist_avgflag_pertape(9) = 'I'
+hist_fincl9 += 'SOILWATER_10CM','QFLX_SOLIDEVAP_FROM_TOP_LAYER','TSKIN'
 

cime_config/usermods_dirs/output_bgc/user_nl_clm

@@ -11,11 +11,11 @@ hist_fincl2 += 'GPP', 'NPP', 'AGNPP', 'TOTVEGC', 'NPP_NUPTAKE', 'AR', 'HR', 'HTO
 
 ! h2 stream (monthly average, landunit-level)
 ! TOT_WOODPRODC:I, CROPPROD1C:I, and NEE are not available at the landunit level
-hist_fincl3 += 'GPP', 'NPP', 'AR', 'HR', 'DWT_CONV_CFLUX_PATCH', 'WOOD_HARVESTC', 'DWT_WOOD_PRODUCTC_GAIN_PATCH', 'SLASH_HARVESTC', 'COL_FIRE_CLOSS', 'FROOTC:I', 'HTOP'
+hist_fincl3 += 'GPP', 'NPP', 'AR', 'HR', 'DWT_CONV_CFLUX_PATCH', 'WOOD_HARVESTC', 'DWT_WOOD_PRODUCTC_GAIN_PATCH', 'SLASH_HARVESTC', 'COL_FIRE_CLOSS', 'HTOP'
 
 ! h3 stream (yearly average, gridcell-level)
-hist_fincl4 += 'SOILC_vr', 'SOILN_vr', 'CWDC_vr', 'MET_LITC_vr', 'CEL_LITC_vr', 'LIG_LITC_vr', 'MET_LITN_vr', 'CEL_LITN_vr', 'LIG_LITN_vr','CWDN_vr', 'TOTLITC:I', 'TOT_WOODPRODC:I', 'TOTSOMC:I','TOTVEGC:I'
+hist_fincl4 += 'SOILC_vr', 'SOILN_vr', 'CWDC_vr', 'MET_LITC_vr', 'CEL_LITC_vr', 'LIG_LITC_vr', 'MET_LITN_vr', 'CEL_LITN_vr', 'LIG_LITN_vr','CWDN_vr'
 
 ! h4 stream (yearly average, landunit-level)
-hist_fincl5 += 'TOTSOMC:I', 'TOTSOMC_1m:I', 'TOTECOSYSC:I', 'TOTVEGC:I', 'WOODC:I', 'TOTLITC:I', 'LIVECROOTC:I', 'DEADCROOTC:I', 'FROOTC:I'
-
+hist_fincl5 += 'TOTSOMC', 'TOTSOMC_1m', 'TOTECOSYSC', 'TOTVEGC', 'WOODC', 'TOTLITC', 'LIVECROOTC', 'DEADCROOTC', 'FROOTC'
+hist_avgflag_pertape(5) = 'I'

cime_config/usermods_dirs/output_crop/user_nl_clm

@@ -12,5 +12,5 @@ hist_fincl2 += 'GRAINC_TO_FOOD','NFERTILIZATION'
 hist_fincl3 += 'GRAINC_TO_FOOD'
 
 ! h3 stream (yearly average, gridcell-level)
-hist_fincl4 += 'PCT_CFT','CROPPROD1C:I'
+hist_fincl4 += 'PCT_CFT'
 

doc/ChangeLog

@@ -1,4 +1,126 @@
 ===============================================================
+Tag name: ctsm5.1.dev13?
+Originator(s): slevis (Samuel Levis,UCAR/TSS,303-665-1310)
+Date: Fri Aug 11 16:18:08 MDT 2023
+One-line Summary: Change history time var and put 'I' fields on separate hist file
+
+Purpose and description of changes
+----------------------------------
+
+ These changes make CTSM output consistent with CMIP.
+ Of course we will maintain consistency across CESM components, as well.
+ We have
+ - redefined our history time variable from "end of time_bounds" to
+ "middle of time_bounds" for all fields except instantaneous ('I')
+ - moved 'I' fields to their own separate history files because
+ their time variable is defined as "end of time_bounds"
+ - removed time_bounds from 'I' history tapes
+ - moved 'L' fields to their own separate history files because they represent
+ a local time within the time_bounds
+ - clarified the long_name for several history time variables
+
+ I made respective updates in ESCOMP/RTM#32 and ESCOMP/MOSART#52, as well.
+
+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_1
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed or introduced
+------------------------
+CTSM issues fixed (include CTSM Issue #):
+ Fixes #1059
+
+
+Notes of particular relevance for users
+---------------------------------------
+Caveats for users (e.g., need to interpolate initial conditions):
+ Changes to history time-related variables as explained above.
+
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Changes to tests or testing:
+
+
+Testing summary:
+----------------
+[Remove any lines that don't apply.]
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    cheyenne -
+
+  tools-tests (test/tools) (if tools have been changed):
+
+    cheyenne -
+
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
+
+    (any machine) -
+
+    [If python code has changed and you are NOT running aux_clm (e.g., because the only changes are in python
+     code) then also run the clm_pymods test suite; this is a small subset of aux_clm that runs the system
+     tests impacted by python changes. The best way to do this, if you expect no changes from the last tag in
+     either model output or namelists, is: create sym links pointing to the last tag's baseline directory,
+     named with the upcoming tag; then run the clm_pymods test suite comparing against these baselines but NOT
+     doing their own baseline generation. If you are already running the full aux_clm then you do NOT need to
+     separately run the clm_pymods test suite, and you can remove the following line.]
+
+    clm_pymods test suite on cheyenne - 
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    cheyenne ----
+    izumi -------
+
+  fates tests: (give name of baseline if different from CTSM tagname, normally fates baselines are fates-<FATES TAG>-<CTSM TAG>)
+    cheyenne ----
+    izumi -------
+
+  any other testing (give details below):
+
+If the tag used for baseline comparisons was NOT the previous tag, note that here:
+
+
+Answer changes
+--------------
+
+Changes answers relative to baseline:
+ Yes, for time-related variables only.
+
+  Summarize any changes to answers, i.e.,
+    - what code configurations: All
+    - what platforms/compilers: All
+    - nature of change: Time-related variables have changed as explained above.
+ Otherwise bit-for-bit.
+
+ I ran the LMWG diagnostics package at @billsacks recommendation and
+ confirmed that all results look identical despite the changes to time-related
+ variables.
+
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/2019
+
+===============================================================
+===============================================================
 Tag name: ctsm5.1.dev133
 Originator(s): adrifoster (Adrianna Foster), glemieux (Gregory Lemieux, LBL/NGEET)
 Date: Wed Aug  9 22:44:46 MDT 2023

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+    ctsm5.1.dev13?   slevis ??/??/2023 Change history time var and put 'I' fields on separate hist file
     ctsm5.1.dev133 glemieux 08/09/2023 FATES API update to facilitate fates refactor
     ctsm5.1.dev132   slevis 08/04/2023 Add parameterization to allow excess ice in soil and subsidence
     ctsm5.1.dev131 samrabin 07/27/2023 Enable prescribed crop calendars

src/biogeochem/CNVegCarbonFluxType.F90

@@ -930,6 +930,17 @@ subroutine InitHistory(this, bounds, carbon_type)
                   ptr_patch=data1dptr)
           end do
 
+          ! GRAINC_TO_FOOD_* are default='inactive' because they make more
+          ! sense to view as instantaneous fields. To view variables as
+          ! instantaneous fields:
+          ! 1) Users now cannot set avgflag='I' or 'L' in the code.
+          ! 2) Instead add lines like these to the user_nl_clm of a case. The
+          ! last two lines will look different according to each user's needs:
+          ! hist_fincl2 = 'GRAINC_TO_FOOD_PERHARV'
+          ! hist_fincl3 = 'GRAINC_TO_FOOD_PERHARV'
+          ! hist_avgflag_pertape = 'A','I','L180000'
+          ! hist_nhtfrq = -24,-24,-24
+          ! hist_mfilt = 1,1,1
           this%repr_grainc_to_food_perharv_patch(begp:endp,:,:) = spval
           do k = repr_grain_min, repr_grain_max
              data2dptr => this%repr_grainc_to_food_perharv_patch(:,:,k)
@@ -938,8 +949,8 @@ subroutine InitHistory(this, bounds, carbon_type)
                   fname=get_repr_hist_fname(k)//'C_TO_FOOD_PERHARV', &
                   units='gC/m^2', &
                   type2d='mxharvests', &
-                  avgflag='I', &
-                  long_name=get_repr_longname(k)//' C to food per harvest; should only be output annually', &
+                  avgflag='A', &
+                  long_name=get_repr_longname(k)//' C to food per harvest; should only be output annually and as an instantaneous field', &
                   ptr_patch=data2dptr, &
                   default='inactive')
           end do
@@ -951,8 +962,8 @@ subroutine InitHistory(this, bounds, carbon_type)
                   ! e.g., GRAINC_TO_FOOD_ANN
                   fname=get_repr_hist_fname(k)//'C_TO_FOOD_ANN', &
                   units='gC/m^2', &
-                  avgflag='I', &
-                  long_name=get_repr_longname(k)//' C to food harvested per calendar year; should only be output annually', &
+                  avgflag='A', &
+                  long_name=get_repr_longname(k)//' C to food harvested per calendar year; should only be output annually and as an instantaneous field', &
                   ptr_patch=data1dptr, &
                   default='inactive')
           end do

src/biogeochem/CNVegStateType.F90

@@ -321,9 +321,20 @@ subroutine InitHistory(this, bounds)
             ptr_patch=this%gddmaturity_patch, default='inactive')
 
        ! Per harvest
+       ! GDDHARV_PERHARV is default='inactive' because it makes more
+       ! sense to view as an instantaneous field. To view variables as
+       ! instantaneous fields:
+       ! 1) Users now cannot set avgflag='I' or 'L' in the code.
+       ! 2) Instead add lines like these to the user_nl_clm of a case. The
+       ! last two lines will look different according to each user's needs:
+       ! hist_fincl2 = 'GDDHARV_PERHARV'
+       ! hist_fincl3 = 'GDDHARV_PERHARV'
+       ! hist_avgflag_pertape = 'A','I','L180000'
+       ! hist_nhtfrq = -24,-24,-24
+       ! hist_mfilt = 1,1,1
        this%gddmaturity_thisyr(begp:endp,:) = spval
        call hist_addfld2d (fname='GDDHARV_PERHARV', units='ddays', type2d='mxharvests', &
-            avgflag='I', long_name='Growing degree days (gdd) needed to harvest; should only be output annually', &
+            avgflag='A', long_name='Growing degree days (gdd) needed to harvest; should only be output annually and as an instantaneous field', &
             ptr_patch=this%gddmaturity_thisyr, default='inactive')
 
     end if

src/biogeochem/CropType.F90

@@ -297,49 +297,58 @@ subroutine InitHistory(this, bounds)
             ptr_patch=this%latbaset_patch, default='inactive')
     end if
 
+    ! SDATES, HDATES make sense as instantaneous fields; to view as such:
+    ! 1) Users now cannot set avgflag='I' or 'L' in the code.
+    ! 2) Instead add lines like these to the user_nl_clm of a case. The
+    ! last two lines will look different according to each user's needs:
+    ! hist_fincl2 = 'SDATES','HDATES'
+    ! hist_fincl3 = 'SDATES','HDATES'
+    ! hist_avgflag_pertape = 'A','I','L180000'
+    ! hist_nhtfrq = -24,-24,-24
+    ! hist_mfilt = 1,1,1
     this%sdates_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='SDATES', units='day of year', type2d='mxsowings', &
-         avgflag='I', long_name='actual crop sowing dates; should only be output annually', &
+         avgflag='A', long_name='actual crop sowing dates; should only be output annually and as an instantaneous field', &
          ptr_patch=this%sdates_thisyr_patch, default='inactive')
 
     this%sdates_perharv_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='SDATES_PERHARV', units='day of year', type2d='mxharvests', &
-         avgflag='I', long_name='actual sowing dates for crops harvested this year; should only be output annually', &
+         avgflag='A', long_name='actual sowing dates for crops harvested this year; should only be output annually and as an instantaneous field', &
          ptr_patch=this%sdates_perharv_patch, default='inactive')
 
     this%syears_perharv_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='SYEARS_PERHARV', units='year', type2d='mxharvests', &
-         avgflag='I', long_name='actual sowing years for crops harvested this year; should only be output annually', &
+         avgflag='A', long_name='actual sowing years for crops harvested this year; should only be output annually and as an instantaneous field', &
          ptr_patch=this%syears_perharv_patch, default='inactive')
 
     this%hdates_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='HDATES', units='day of year', type2d='mxharvests', &
-         avgflag='I', long_name='actual crop harvest dates; should only be output annually', &
+         avgflag='A', long_name='actual crop harvest dates; should only be output annually and as an instantaneous field', &
          ptr_patch=this%hdates_thisyr_patch, default='inactive')
 
     this%gddaccum_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='GDDACCUM_PERHARV', units='ddays', type2d='mxharvests', &
-         avgflag='I', long_name='At-harvest accumulated growing degree days past planting date for crop; should only be output annually', &
+         avgflag='A', long_name='At-harvest accumulated growing degree days past planting date for crop; should only be output annually and as an instantaneous field', &
          ptr_patch=this%gddaccum_thisyr_patch, default='inactive')
 
     this%hui_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='HUI_PERHARV', units='ddays', type2d='mxharvests', &
-         avgflag='I', long_name='At-harvest accumulated heat unit index for crop; should only be output annually', &
+         avgflag='A', long_name='At-harvest accumulated heat unit index for crop; should only be output annually and as an instantaneous field', &
          ptr_patch=this%hui_thisyr_patch, default='inactive')
 
     this%sowing_reason_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='SOWING_REASON', units='unitless', type2d='mxsowings', &
-         avgflag='I', long_name='Reason for each crop sowing; should only be output annually', &
+         avgflag='A', long_name='Reason for each crop sowing; should only be output annually and as an instantaneous field', &
          ptr_patch=this%sowing_reason_thisyr_patch, default='inactive')
 
     this%sowing_reason_perharv_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='SOWING_REASON_PERHARV', units='unitless', type2d='mxharvests', &
-         avgflag='I', long_name='Reason for sowing of each crop harvested this year; should only be output annually', &
+         avgflag='A', long_name='Reason for sowing of each crop harvested this year; should only be output annually and as an instantaneous field', &
          ptr_patch=this%sowing_reason_perharv_patch, default='inactive')
 
     this%harvest_reason_thisyr_patch(begp:endp,:) = spval
     call hist_addfld2d (fname='HARVEST_REASON_PERHARV', units='1 = mature; 2 = max season length; 3 = incorrect Dec. 31 sowing; 4 = sowing today; 5 = sowing tomorrow; 6 = tomorrow == idop; 7 = killed by cold temperature during vernalization', type2d='mxharvests', &
-         avgflag='I', long_name='Reason for each crop harvest; should only be output annually', &
+         avgflag='A', long_name='Reason for each crop harvest; should only be output annually and as an instantaneous field', &
          ptr_patch=this%harvest_reason_thisyr_patch, default='inactive')
 
   end subroutine InitHistory

src/biogeophys/PhotosynthesisMod.F90

@@ -515,25 +515,34 @@ subroutine InitHistory(this, bounds)
 
        ! Don't by default output this rate limiting step as only makes sense if you are outputing
        ! the others each time-step
+       ! and viewing this as an instantaneous field. To view as instantaneous:
+       ! 1) Users now cannot set avgflag='I' or 'L' in the code.
+       ! 2) Instead add lines like these to the user_nl_clm of a case. The
+       ! last two lines will look different according to each user's needs:
+       ! hist_fincl2 = 'FPSN_WC','FPSN_WJ','FPSN_WP'
+       ! hist_fincl3 = 'FPSN_WC','FPSN_WJ','FPSN_WP'
+       ! hist_avgflag_pertape = 'A','I','L180000'
+       ! hist_nhtfrq = -24,-24,-24
+       ! hist_mfilt = 1,1,1
        this%fpsn_wc_patch(begp:endp) = spval
        call hist_addfld1d (fname='FPSN_WC', units='umol m-2 s-1',  &
-            avgflag='I', long_name='Rubisco-limited photosynthesis', &
+            avgflag='A', long_name='Rubisco-limited photosynthesis; should be output as an instantaneous field', &
             ptr_patch=this%fpsn_wc_patch, set_lake=0._r8, set_urb=0._r8, &
             default='inactive')
 
        ! Don't by default output this rate limiting step as only makes sense if you are outputing
        ! the others each time-step
        this%fpsn_wj_patch(begp:endp) = spval
        call hist_addfld1d (fname='FPSN_WJ', units='umol m-2 s-1',  &
-            avgflag='I', long_name='RuBP-limited photosynthesis', &
+            avgflag='A', long_name='RuBP-limited photosynthesis; should be output as an instantaneous field', &
             ptr_patch=this%fpsn_wj_patch, set_lake=0._r8, set_urb=0._r8, &
             default='inactive')
 
        ! Don't by default output this rate limiting step as only makes sense if you are outputing
        ! the others each time-step
        this%fpsn_wp_patch(begp:endp) = spval
        call hist_addfld1d (fname='FPSN_WP', units='umol m-2 s-1',  &
-            avgflag='I', long_name='Product-limited photosynthesis', &
+            avgflag='A', long_name='Product-limited photosynthesis; should be output as an instantaneous field', &
             ptr_patch=this%fpsn_wp_patch, set_lake=0._r8, set_urb=0._r8, &
             default='inactive')
     end if