From 9bcfcffe27bb46c6ee230fb6c29e5bd9c1c6f16d Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Thu, 22 Aug 2024 11:48:48 -0600
Subject: [PATCH] Keep GLACIER_REGION=1 unused

We realized that the renumbering of regions could cause silent wrong
behavior if a user was using an old user_nl_clm file that specified
behaviors for the old 4 regions. So instead, we're keeping the old
numbering for the Greenland and Antarctica regions and keeping
GLACIER_REGION=1 unused for now.
---
 bld/namelist_files/namelist_defaults_ctsm.xml      | 11 +++++++----
 bld/namelist_files/namelist_definition_ctsm.xml    | 14 ++++++++------
 cime_config/SystemTests/lvg.py                     |  4 ++--
 .../cmip6_glaciers_virtual_antarctica/user_nl_clm  |  2 +-
 src/main/glcBehaviorMod.F90                        |  9 ++++++---
 tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml  |  2 +-
 6 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/bld/namelist_files/namelist_defaults_ctsm.xml b/bld/namelist_files/namelist_defaults_ctsm.xml
index cd5e723baa..ae40b99d0c 100644
--- a/bld/namelist_files/namelist_defaults_ctsm.xml
+++ b/bld/namelist_files/namelist_defaults_ctsm.xml
@@ -466,6 +466,7 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 
 <!-- Default glacier behavior is:
      Mountain glaciers: single_at_atm_topo
+     Currently-unused region 1: UNSET
      Greenland: virtual
      Antarctica: multiple
 
@@ -473,20 +474,22 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
      behavior to virtual. Note that the Greenland behavior is always
      virtual, even if Greenland isn't included in this run.
 -->
-<glacier_region_behavior glc_use_antarctica="0">'single_at_atm_topo','virtual','multiple'</glacier_region_behavior>
-<glacier_region_behavior glc_use_antarctica="1">'single_at_atm_topo','virtual','virtual' </glacier_region_behavior>
+<glacier_region_behavior glc_use_antarctica="0">'single_at_atm_topo','UNSET','virtual','multiple'</glacier_region_behavior>
+<glacier_region_behavior glc_use_antarctica="1">'single_at_atm_topo','UNSET','virtual','virtual' </glacier_region_behavior>
 
 <!-- Default glacier melt behavior is:
      Mountain glaciers: remains_in_place
+     Currently-unused region 1: UNSET
      Greenland: replaced_by_ice
      Antarctica: replaced_by_ice -->
-<glacier_region_melt_behavior>'remains_in_place','replaced_by_ice','replaced_by_ice'</glacier_region_melt_behavior>
+<glacier_region_melt_behavior>'remains_in_place','UNSET','replaced_by_ice','replaced_by_ice'</glacier_region_melt_behavior>
 
 <!-- Default glacier ice runoff behavior is:
      Mountain glaciers: melted
+     Currently-unused region 1: UNSET
      Greenland: remains_ice
      Antarctica: remains_ice -->
-<glacier_region_ice_runoff_behavior>'melted','remains_ice','remains_ice'</glacier_region_ice_runoff_behavior>
+<glacier_region_ice_runoff_behavior>'melted','UNSET','remains_ice','remains_ice'</glacier_region_ice_runoff_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
diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml
index 0912617872..63525f7ab3 100644
--- a/bld/namelist_files/namelist_definition_ctsm.xml
+++ b/bld/namelist_files/namelist_definition_ctsm.xml
@@ -550,7 +550,7 @@ Only works when running with a non-stub glacier model.
 
 <entry id="glacier_region_behavior" type="char*32(10)" category="clm_physics"
        group="clm_glacier_behavior"
-       valid_values="multiple,virtual,single_at_atm_topo" >
+       valid_values="multiple,virtual,single_at_atm_topo,UNSET" >
 Behavior of each glacier region (GLACIER_REGION in surface dataset).
 First item corresponds to GLACIER_REGION with ID 0 in the surface dataset,
 second to GLACIER_REGION with ID 1, etc.
@@ -563,12 +563,13 @@ Allowed values are:
 'single_at_atm_topo': glacier landunits in these grid cells have a single column,
    whose elevation matches the atmosphere's topographic height (so that there is no
    adjustment due to downscaling)
-Behavior of 'virtual' is required in the region where we have an ice sheet model
+'UNSET': place-holder for non-existent regions
+Behavior of 'virtual' is required in the region(s) where SMB is being sent to an ice sheet model
 </entry>
 
 <entry id="glacier_region_melt_behavior" type="char*32(10)" category="clm_physics"
        group="clm_glacier_behavior"
-       valid_values="replaced_by_ice,remains_in_place" >
+       valid_values="replaced_by_ice,remains_in_place,UNSET" >
 Treatment of ice melt for each glacier region (GLACIER_REGION in surface dataset).
 First item corresponds to GLACIER_REGION with ID 0 in the surface dataset,
 second to GLACIER_REGION with ID 1, etc.
@@ -577,17 +578,17 @@ Allowed values are:
    this results in positive liquid runoff and negative ice runoff
 'remains_in_place': any melted ice remains in place as liquid until it refreezes;
    thus, ice melt does not result in any runoff
+'UNSET': place-holder for non-existent regions
 IMPORTANT NOTE: Regions with the 'remains_in_place' behavior also do not
 compute SMB (because negative SMB would be pretty much meaningless in
-those regions). Thus, you cannot use this behavior where GLC is
-operating.
+those regions). Thus, you cannot use this behavior where SMB is being sent to an ice sheet model.
 Regions with the 'replaced_by_ice' behavior also compute SMB for the
 vegetated column.
 </entry>
 
 <entry id="glacier_region_ice_runoff_behavior" type="char*32(10)" category="clm_physics"
        group="clm_glacier_behavior"
-       valid_values="remains_ice,melted" >
+       valid_values="remains_ice,melted,UNSET" >
 Treatment of ice runoff for each glacier region (GLACIER_REGION in surface dataset).
 First item corresponds to GLACIER_REGION with ID 0 in the surface dataset,
 second to GLACIER_REGION with ID 1, etc.
@@ -599,6 +600,7 @@ Allowed values are:
    (generating a negative sensible heat flux) and runs off as liquid; this is appropriate in
    regions that have little iceberg calving in reality. This can be important to avoid unrealistic
    cooling of the ocean and consequent runaway sea ice growth.
+'UNSET': place-holder for non-existent regions
 Only applies when melt_non_icesheet_ice_runoff is .true.
 </entry>
 
diff --git a/cime_config/SystemTests/lvg.py b/cime_config/SystemTests/lvg.py
index 286712ce0f..d73f4e707b 100644
--- a/cime_config/SystemTests/lvg.py
+++ b/cime_config/SystemTests/lvg.py
@@ -32,12 +32,12 @@ def _case_one_setup(self):
         append_to_user_nl_files(
             caseroot=self._get_caseroot(),
             component="clm",
-            contents="glacier_region_behavior = 'single_at_atm_topo', 'virtual', 'multiple'",
+            contents="glacier_region_behavior = 'single_at_atm_topo', 'UNSET', 'virtual', 'multiple'",
         )
 
     def _case_two_setup(self):
         append_to_user_nl_files(
             caseroot=self._get_caseroot(),
             component="clm",
-            contents="glacier_region_behavior = 'single_at_atm_topo', 'virtual', 'virtual'",
+            contents="glacier_region_behavior = 'single_at_atm_topo', 'UNSET', 'virtual', 'virtual'",
         )
diff --git a/cime_config/usermods_dirs/_includes/cmip6_glaciers_virtual_antarctica/user_nl_clm b/cime_config/usermods_dirs/_includes/cmip6_glaciers_virtual_antarctica/user_nl_clm
index b6c563ed2c..9aeba5c9d3 100644
--- a/cime_config/usermods_dirs/_includes/cmip6_glaciers_virtual_antarctica/user_nl_clm
+++ b/cime_config/usermods_dirs/_includes/cmip6_glaciers_virtual_antarctica/user_nl_clm
@@ -5,5 +5,5 @@
 ! This differs from the default in that it turns on virtual columns over Antarctica
 ! This is desired so that we have the output needed to drive a later offline CISM Antarctica simulation
 ! However, this increases the cost of CLM by about 10%
-glacier_region_behavior = 'single_at_atm_topo', 'virtual', 'virtual'
+glacier_region_behavior = 'single_at_atm_topo', 'UNSET', 'virtual', 'virtual'
 
diff --git a/src/main/glcBehaviorMod.F90 b/src/main/glcBehaviorMod.F90
index 0476fe3ecb..d2719a6533 100644
--- a/src/main/glcBehaviorMod.F90
+++ b/src/main/glcBehaviorMod.F90
@@ -405,7 +405,8 @@ subroutine translate_glacier_region_behavior
                glacier_region_behavior(i) = BEHAVIOR_SINGLE_AT_ATM_TOPO
             case (behavior_str_unset)
                write(iulog,*) ' ERROR: glacier_region_behavior not specified for ID ', i
-               write(iulog,*) 'You probably need to extend the glacier_region_behavior namelist array'
+               write(iulog,*) 'You may need to extend the glacier_region_behavior namelist array,'
+               write(iulog,*) 'or you may be running with an old/incompatible surface dataset.'
                call endrun(msg=' ERROR: glacier_region_behavior not specified for ID '// &
                     errMsg(sourcefile, __LINE__))
             case default
@@ -436,7 +437,8 @@ subroutine translate_glacier_region_melt_behavior
                glacier_region_melt_behavior(i) = MELT_BEHAVIOR_REMAINS_IN_PLACE
             case (behavior_str_unset)
                write(iulog,*) ' ERROR: glacier_region_melt_behavior not specified for ID ', i
-               write(iulog,*) 'You probably need to extend the glacier_region_melt_behavior namelist array'
+               write(iulog,*) 'You may need to extend the glacier_region_melt_behavior namelist array,'
+               write(iulog,*) 'or you may be running with an old/incompatible surface dataset.'
                call endrun(msg=' ERROR: glacier_region_melt_behavior not specified for ID '// &
                     errMsg(sourcefile, __LINE__))
             case default
@@ -467,7 +469,8 @@ subroutine translate_glacier_region_ice_runoff_behavior
                glacier_region_ice_runoff_behavior(i) = ICE_RUNOFF_BEHAVIOR_MELTED
             case (behavior_str_unset)
                write(iulog,*) ' ERROR: glacier_region_ice_runoff_behavior not specified for ID ', i
-               write(iulog,*) 'You probably need to extend the glacier_region_ice_runoff_behavior namelist array'
+               write(iulog,*) 'You may need to extend the glacier_region_ice_runoff_behavior namelist array,'
+               write(iulog,*) 'or you may be running with an old/incompatible surface dataset.'
                call endrun(msg=' ERROR: glacier_region_ice_runoff_behavior not specified for ID '// &
                     errMsg(sourcefile, __LINE__))
             case default
diff --git a/tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml b/tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml
index f9bb6a3a02..683ea14058 100644
--- a/tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml
+++ b/tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml
@@ -140,7 +140,7 @@ version of the raw dataset will probably go away.
 
   <mksrf_fglacierregion>
     <entry>
-      <data_filename>lnd/clm2/rawdata/mksrf_GlacierRegion_10x10min_nomask_cd5_c240815.nc</data_filename>
+      <data_filename>lnd/clm2/rawdata/mksrf_GlacierRegion_10x10min_nomask_cd5_c240822.nc</data_filename>
       <mesh_filename>lnd/clm2/mappingdata/grids/UNSTRUCTgrid_10x10min_nomask_cdf5_c200129.nc</mesh_filename>
     </entry>
   </mksrf_fglacierregion>