From 980bc1649a85c955369c456cd770b54ea1ac3965 Mon Sep 17 00:00:00 2001
From: Bill Sacks <sacks@ucar.edu>
Date: Thu, 22 Aug 2024 14:48:45 -0600
Subject: [PATCH] Improve documentation of glacier region namelist options

---
 .../namelist_definition_ctsm.xml              | 28 ++++++++++++++-----
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml
index 63525f7ab3..e6eadaae2c 100644
--- a/bld/namelist_files/namelist_definition_ctsm.xml
+++ b/bld/namelist_files/namelist_definition_ctsm.xml
@@ -564,7 +564,15 @@ Allowed values are:
    whose elevation matches the atmosphere's topographic height (so that there is no
    adjustment due to downscaling)
 '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
+Most (if not all) of the region where there is an ice sheet model should have a behavior
+of 'virtual': This behavior is needed to compute surface mass balance (SMB) in all
+elevation classes for the sake of vertical downscaling, and is needed to allow two-way
+feedbacks of glacier areas. You are allowed to have gridcells with non-virtual behavior in
+this domain, but this should be minimized: SMB cannot be computed there, and CLM subgrid
+areas will not remain in sync with the GLC model. (Within the icemask - i.e., the active
+glc domain - you are NOT allowed to have gridcells with non-virtual behavior that also
+have glacier_region_melt_behavior='replaced_by_ice': within the icemask, you're only
+allowed to have non-virtual behavior in places where you are not computing SMB).
 </entry>
 
 <entry id="glacier_region_melt_behavior" type="char*32(10)" category="clm_physics"
@@ -579,11 +587,12 @@ Allowed values are:
 '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 SMB is being sent to an ice sheet model.
-Regions with the 'replaced_by_ice' behavior also compute SMB for the
-vegetated column.
+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, most (if
+not all) of the region where there is an ice sheet model should have the 'replaced_by_ice'
+behavior; the SMB sent to the GLC model will be 0 in any gridcells with the
+'remains_in_place' behavior.
+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"
@@ -599,7 +608,12 @@ Allowed values are:
 'melted': ice runoff generated by the CLM physics (primarily due to snow capping) is melted
    (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.
+   cooling of the ocean and consequent runaway sea ice growth. This option cannot be
+   combined with glacier_region_melt_behavior='replaced_by_ice': While there is nothing
+   fundamentally wrong with this combination, it can result in problematic, non-physical
+   fluxes (particularly, a large positive sensible heat flux during glacial melt in
+   regions where the ice sheet is not fully dynamic and two-way-coupled; see
+   https://github.com/ESCOMP/ctsm/issues/423 for details).
 'UNSET': place-holder for non-existent regions
 Only applies when melt_non_icesheet_ice_runoff is .true.
 </entry>