Merge branch 'rain_to_snow_runs_off' into release-clm5.0

Option for rain-to-snow to immediately run off in some regions

Up until now: When repartition_rain_snow is .true. (which is the default
for CLM5), rain that falls when the near-surface temperature is cold is
converted to snow. This repartitioning was put in place for two
reasons: (1) Downscaling to elevation classes: changing the balance
between rain and snow for different elevation classes; (2) Correcting
problems in CAM. However, members of the Land Ice Working Group would
like to change this behavior so that, when CAM produces cold-temperature
rain, this rain immediately runs off rather than being converted to
snow. The purpose of this is to reduce the too-high SMB over portions of
Greenland in CESM2 coupled runs (which results in part from CAM's
generation of liquid precipitation despite very cold temperatures).

This new behavior is implemented in a glacier region-specific manner,
based on a new namelist flag, glacier_region_rain_to_snow_behavior. It
is not at all ideal to make this aspect of the physics differ by region,
but this has been requested by members of the Land Ice Working Group in
order to address biases over Greenland while having minimal impact on
the climate (so that the climate can stay very similar to that of the
official CMIP6 runs). Note that, unlike other glacier region-specific
behaviors, this one applies to all landunits, not just glaciers. This
also seems a bit non-ideal, but we want the physics to be the same for
all landunit types in a given region, and we also want this behavior to
apply to vegetated columns because they are used for glacial
inception (and we want this alternate behavior to apply to glacial
inception, too, in order to decrease some instances of inception).

The justification for this new physics is: In the case of (1) above: If
CAM is generating rain at a given elevation / temperature, that doesn't
necessarily imply that an equal water equivalent of snow would be
generated at a higher elevation / lower temperature: indeed, in reality,
there might not be any precipitation falling at that higher elevation /
lower temperature. In the case of (2) above: There seem to be problems
with CAM's microphysics that cause it to produce too much rain when
temperatures are very cold; it seems (at least to some people) equally
justifiable to throw this cold rain away (by sending it to the ocean as
runoff) as it is to convert this cold rain to snow.

Note: I don't think any changes are needed in
BalanceCheck (unfortunately), since BalanceCheck currently uses the
post-downscaling precipitation fluxes, and the pre-lnd2atm runoff
fluxes (i.e., the new runoff flux isn't included in the terms in
BalanceCheck, and it doesn't need to be because BalanceCheck uses the
post-downscaling precipitation fluxes). (See also
#201 (comment) .)

CTSM Master Tag This Corresponds To: N/A

   At least for now, we are bringing this to the release branch but not
   to master. Here is an excerpt from the email explaining this
   rationale:

   My question is: Should I do this:

   (1) Just on a branch off of the release-clm5.0 branch, with no plan
       to bring it back to release-clm5.0 or master

   (2) On the release-clm5.0 branch, but not bring it back to master

   (3) On the release-clm5.0 branch and master

   My inclination right now is towards (2). I don't really like (1)
   because this change will be wanted for a number of CMIP6-related
   experiments, and it feels like it could be a pain to keep this branch
   up-to-date with the evolving release-clm5.0 branch. However, the
   changes are going to be a bit messy and having this be
   region-specific isn't really physically justifiable (it's just being
   done that way to keep the climate as close as possible to the
   official CMIP6 runs), so I'm not sure we really want this on
   master. If we did anything on master, I could imagine having a
   globally-applicable switch controlling this behavior, rather than
   having it apply to just certain glacier regions.

   Bette: The main reason I could see for bringing this to master is if
   you imagine needing to use this new option in isotope-enabled runs,
   since the isotope-enabled version of CTSM won't be on the
   release-clm5.0 branch. Do you think it's likely that you'd need to do
   that, or would the isotope-enabled runs use the standard CMIP6
   physics settings in this respect?

bld/CLMBuildNamelist.pm

@@ -2039,6 +2039,7 @@ sub setup_logic_glacier {
      add_default($opts,  $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'glacier_region_behavior');
      add_default($opts,  $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'glacier_region_melt_behavior');
      add_default($opts,  $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'glacier_region_ice_runoff_behavior');
+     add_default($opts,  $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'glacier_region_rain_to_snow_behavior');
   }
 }
 

bld/namelist_files/namelist_defaults_clm4_5.xml

@@ -336,6 +336,8 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
      Antarctica: remains_ice -->
 <glacier_region_ice_runoff_behavior>'melted','melted','remains_ice','remains_ice'</glacier_region_ice_runoff_behavior>
 
+<glacier_region_rain_to_snow_behavior>'converted_to_snow','converted_to_snow','converted_to_snow','converted_to_snow'</glacier_region_rain_to_snow_behavior>
+
 <!-- This parameter is tied (in a scientific sense) to h2osno_max: For large
      values of h2osno_max, glc_snow_persistence_max_days should be 0; for small
      values of h2osno_max, glc_snow_persistence_max_days should be non-zero. For

bld/namelist_files/namelist_definition_clm4_5.xml

@@ -507,6 +507,23 @@ Allowed values are:
 Only applies when melt_non_icesheet_ice_runoff is .true.
 </entry>
 
+<entry id="glacier_region_rain_to_snow_behavior" type="char*32(10)" category="clm_physics"
+       group="clm_glacier_behavior"
+       valid_values="converted_to_snow,runs_off" >
+When rain-snow repartitioning / downscaling results in rain being converted to
+snow, the behavior of the resulting additional snow.
+First item corresponds to GLACIER_REGION with ID 0 in the surface dataset,
+second to GLACIER_REGION with ID 1, etc.
+Allowed values are:
+'converted_to_snow': rain is converted to snow, with a corresponding sensible
+   heat flux correction
+'runs_off': rather than being converted to snow, the excess rain runs off
+   immediately
+IMPORTANT NOTE: Unlike other glacier_region*behavior namelist options, this
+option applies to all landunit types in the given regions.
+Only applies when repartition_rain_snow is .true.
+</entry>
+
 <entry id="glc_snow_persistence_max_days" type="integer" category="clm_physics"
        group="clm_inparm" valid_values="" >
 Number of days before one considers the perennially snow-covered point 'land ice'

cime_config/testdefs/testlist_clm.xml

@@ -382,6 +382,15 @@
       <option name="wallclock">00:20:00</option>
     </options>
   </test>
+  <test name="ERP_D_P36x2_Ld3" grid="f10_f10_musgs" compset="I1850Clm50BgcCrop" testmods="clm/rain_to_snow_runs_off">
+    <machines>
+      <machine name="cheyenne" compiler="intel" category="aux_clm">
+        <options>
+          <option name="wallclock">00:20:00</option>
+        </options>
+      </machine>
+    </machines>
+  </test>
   <test name="ERP_D_P36x2_Ld3" grid="f10_f10_musgs" compset="I2000Clm50BgcCrop" testmods="clm/cropColdStart">
     <machines>
       <machine name="cheyenne" compiler="intel" category="aux_clm"/>

cime_config/testdefs/testmods_dirs/clm/rain_to_snow_runs_off/include_user_mods

@@ -0,0 +1 @@
+../default

cime_config/testdefs/testmods_dirs/clm/rain_to_snow_runs_off/user_nl_clm

@@ -0,0 +1,2 @@
+ glacier_region_rain_to_snow_behavior = 'converted_to_snow','converted_to_snow','runs_off','converted_to_snow'
+

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+release-clm5.0.15    sacks 12/06/2018 Option for rain-to-snow to immediately run off in some regions
 release-clm5.0.14     erik 11/29/2018 Update cime and fix surface dataset for f05 1850 non-crop case
 release-clm5.0.13     erik 11/14/2018 Update externals with new CO2/presearo/rtm/mosart, add science_support, change testing
 release-clm5.0.12     erik 11/03/2018 New IC files for clm45/clm50 coupled cases, add 2010 compset

doc/release-clm5.0.ChangeLog

@@ -1,4 +1,178 @@
 ===============================================================
+Tag name:  release-clm5.0.15
+Originator(s):  sacks (Bill Sacks)
+Date: Thu Dec  6 10:14:30 MST 2018
+One-line Summary: Option for rain-to-snow to immediately run off in some regions
+
+Purpose of this version:
+------------------------
+
+Up until now: When repartition_rain_snow is .true. (which is the default
+for CLM5), rain that falls when the near-surface temperature is cold is
+converted to snow. This repartitioning was put in place for two
+reasons: (1) Downscaling to elevation classes: changing the balance
+between rain and snow for different elevation classes; (2) Correcting
+problems in CAM. However, members of the Land Ice Working Group would
+like to change this behavior so that, when CAM produces cold-temperature
+rain, this rain immediately runs off rather than being converted to
+snow. The purpose of this is to reduce the too-high SMB over portions of
+Greenland in CESM2 coupled runs (which results in part from CAM's
+generation of liquid precipitation despite very cold temperatures).
+
+This new behavior is implemented in a glacier region-specific manner,
+based on a new namelist flag, glacier_region_rain_to_snow_behavior. It
+is not at all ideal to make this aspect of the physics differ by region,
+but this has been requested by members of the Land Ice Working Group in
+order to address biases over Greenland while having minimal impact on
+the climate (so that the climate can stay very similar to that of the
+official CMIP6 runs). Note that, unlike other glacier region-specific
+behaviors, this one applies to all landunits, not just glaciers. This
+also seems a bit non-ideal, but we want the physics to be the same for
+all landunit types in a given region, and we also want this behavior to
+apply to vegetated columns because they are used for glacial
+inception (and we want this alternate behavior to apply to glacial
+inception, too, in order to decrease some instances of inception).
+
+The justification for this new physics is: In the case of (1) above: If
+CAM is generating rain at a given elevation / temperature, that doesn't
+necessarily imply that an equal water equivalent of snow would be
+generated at a higher elevation / lower temperature: indeed, in reality,
+there might not be any precipitation falling at that higher elevation /
+lower temperature. In the case of (2) above: There seem to be problems
+with CAM's microphysics that cause it to produce too much rain when
+temperatures are very cold; it seems (at least to some people) equally
+justifiable to throw this cold rain away (by sending it to the ocean as
+runoff) as it is to convert this cold rain to snow.
+
+Note: I don't think any changes are needed in
+BalanceCheck (unfortunately), since BalanceCheck currently uses the
+post-downscaling precipitation fluxes, and the pre-lnd2atm runoff
+fluxes (i.e., the new runoff flux isn't included in the terms in
+BalanceCheck, and it doesn't need to be because BalanceCheck uses the
+post-downscaling precipitation fluxes). (See also
+https://github.com/ESCOMP/ctsm/issues/201#issuecomment-444264954 .)
+
+CTSM Master Tag This Corresponds To: N/A
+
+   At least for now, we are bringing this to the release branch but not to
+   master. Here is an excerpt from the email explaining this rationale:
+
+   My question is: Should I do this:
+
+   (1) Just on a branch off of the release-clm5.0 branch, with no plan to
+       bring it back to release-clm5.0 or master
+
+   (2) On the release-clm5.0 branch, but not bring it back to master
+
+   (3) On the release-clm5.0 branch and master
+
+   My inclination right now is towards (2). I don't really like (1) because
+   this change will be wanted for a number of CMIP6-related experiments,
+   and it feels like it could be a pain to keep this branch up-to-date with
+   the evolving release-clm5.0 branch. However, the changes are going to be
+   a bit messy and having this be region-specific isn't really physically
+   justifiable (it's just being done that way to keep the climate as close
+   as possible to the official CMIP6 runs), so I'm not sure we really want
+   this on master. If we did anything on master, I could imagine having a
+   globally-applicable switch controlling this behavior, rather than having
+   it apply to just certain glacier regions.
+
+   Bette: The main reason I could see for bringing this to master is if you
+   imagine needing to use this new option in isotope-enabled runs, since
+   the isotope-enabled version of CTSM won't be on the release-clm5.0
+   branch. Do you think it's likely that you'd need to do that, or would
+   the isotope-enabled runs use the standard CMIP6 physics settings in this
+   respect?
+
+Summary of changes:
+-------------------
+
+Science changes since: release-clm5.0.14
+   None by default: just introduces a new option
+
+Software changes since: release-clm5.0.14
+   Introduces a new option, glacier_region_rain_to_snow_behavior,
+   controlling whether would-be rain-to-snow conversion ends up as snow
+   or instead ends up as liquid runoff.
+
+Changes to User Interface since: release-clm5.0.14
+   Introduces a new option, glacier_region_rain_to_snow_behavior,
+   controlling whether would-be rain-to-snow conversion ends up as snow
+   or instead ends up as liquid runoff.
+
+Testing:
+--------
+
+ [PASS means all tests PASS and OK means tests PASS other than expected fails.]
+
+  build-namelist tests:
+
+    cheyenne - ok
+
+    Tests pass, namelists differ as expected
+
+  unit-tests (components/clm/src):
+
+    cheyenne - pass
+    hobart --- not run
+
+  tools-tests (components/clm/test/tools):
+
+    cheyenne - not run
+    hobart --- not run
+
+  PTCLM testing (components/clm/tools/shared/PTCLM/test):
+
+     cheyenne - not run
+     hobart --- not run
+
+  regular tests (aux_clm):
+
+    cheyenne_intel ---- pass
+    cheyenne_gnu ------ pass
+    hobart_nag -------- pass
+    hobart_pgi -------- pass
+    hobart_intel ------ pass
+
+  regular tests (prealpha):
+
+    cheyenne_intel - not run
+    cheyenne_gnu --- not run
+    hobart_nag ----- not run
+
+  regular tests (prebeta):
+
+    cheyenne_intel - not run
+    cheyenne_gnu --- not run
+    hobart_nag ----- not run
+
+Summary of Answer changes:
+-------------------------
+
+Baseline version for comparison: release-clm5.0.14
+
+Changes answers relative to baseline: NO
+
+Detailed list of changes:
+------------------------
+
+Externals being used:
+
+   cism:   release-cesm2.0.04
+   rtm:    release-cesm2.0.02
+   mosart: release-cesm2.0.03
+   cime:   cime_cesm2_1_rel_05
+   FATES:  fates_s1.8.1_a3.0.0
+   PTCLM:  PTCLM2_180611
+
+CTSM Tag versions pulled over from master development branch: none
+
+Pull Requests that document the changes (include PR ids):
+   ESCOMP/ctsm#586 - Option for rain-to-snow to immediately run off in
+   some regions
+
+===============================================================
+===============================================================
 Tag name:  release-clm5.0.14
 Originator(s):  erik (Erik Kluzek)
 Date: Thu Nov 29 11:46:41 MST 2018

src/biogeophys/WaterfluxType.F90

@@ -87,6 +87,7 @@ module WaterfluxType
      real(r8), pointer :: qflx_snomelt_lyr_col     (:,:) ! col snow melt in each layer (mm H2O /s)
      real(r8), pointer :: qflx_snow_drain_col      (:)   ! col drainage from snow pack
      real(r8), pointer :: qflx_qrgwl_col           (:)   ! col qflx_surf at glaciers, wetlands, lakes
+     real(r8), pointer :: qflx_runoff_rain_to_snow_conversion_col(:) ! col runoff flux from rain-to-snow conversion, when this conversion leads to immediate runoff rather than snow (mm H2O /s)
      real(r8), pointer :: qflx_runoff_col          (:)   ! col total runoff (qflx_drain+qflx_surf+qflx_qrgwl) (mm H2O /s)
      real(r8), pointer :: qflx_runoff_r_col        (:)   ! col Rural total runoff (qflx_drain+qflx_surf+qflx_qrgwl) (mm H2O /s)
      real(r8), pointer :: qflx_runoff_u_col        (:)   ! col urban total runoff (qflx_drain+qflx_surf) (mm H2O /s) 
@@ -226,6 +227,7 @@ subroutine InitAllocate(this, bounds)
     allocate(this%qflx_snofrz_col          (begc:endc))              ; this%qflx_snofrz_col          (:)   = nan
     allocate(this%qflx_snofrz_lyr_col      (begc:endc,-nlevsno+1:0)) ; this%qflx_snofrz_lyr_col      (:,:) = nan
     allocate(this%qflx_qrgwl_col           (begc:endc))              ; this%qflx_qrgwl_col           (:)   = nan
+    allocate(this%qflx_runoff_rain_to_snow_conversion_col(begc:endc)); this%qflx_runoff_rain_to_snow_conversion_col(:) = nan
     allocate(this%qflx_drain_perched_col   (begc:endc))              ; this%qflx_drain_perched_col   (:)   = nan
     allocate(this%qflx_deficit_col         (begc:endc))              ; this%qflx_deficit_col         (:)   = nan
     allocate(this%qflx_floodc_col          (begc:endc))              ; this%qflx_floodc_col          (:)   = nan
@@ -299,6 +301,12 @@ subroutine InitHistory(this, bounds)
          long_name='surface runoff at glaciers (liquid only), wetlands, lakes; also includes melted ice runoff from QSNWCPICE', &
          ptr_col=this%qflx_qrgwl_col, c2l_scale_type='urbanf')
 
+    this%qflx_runoff_rain_to_snow_conversion_col(begc:endc) = spval
+    call hist_addfld1d (fname='QRUNOFF_RAIN_TO_SNOW_CONVERSION', units='mm/s', &
+         avgflag='A', &
+         long_name='liquid runoff from rain-to-snow conversion when this conversion leads to immediate runoff', &
+         ptr_col=this%qflx_runoff_rain_to_snow_conversion_col, c2l_scale_type='urbanf')
+
     this%qflx_drain_col(begc:endc) = spval
     call hist_addfld1d (fname='QDRAI',  units='mm/s',  &
          avgflag='A', long_name='sub-surface drainage', &