ctsm5.4.059: Indoor humidity and air-conditioning dehumidification

bld/CLMBuildNamelist.pm

@@ -2403,9 +2403,26 @@ sub setup_logic_urban {
 
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'building_temp_method');
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'urban_hac');
+  add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'building_humidity_mode');
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'urban_explicit_ac');
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'urban_traffic');
   add_default($opts, $nl_flags->{'inputdata_rootdir'}, $definition, $defaults, $nl, 'init_interp_fill_missing_urban_with_HD');
+  my $building_humidity_mode = $nl->get_value('building_humidity_mode');
+  if ($building_humidity_mode < 0 || $building_humidity_mode > 2) {
+     $log->fatal_error("building_humidity_mode must be 0, 1, or 2");
+  }
+  if ($building_humidity_mode >= 1 && $nl->get_value('building_temp_method') != 1) {
+     $log->fatal_error("building_humidity_mode=1 or 2 requires building_temp_method=1");
+  }
+  if ($building_humidity_mode == 2) {
+     my $urban_hac = remove_leading_and_trailing_quotes($nl->get_value('urban_hac'));
+     if ($urban_hac ne 'ON' && $urban_hac ne 'ON_WASTEHEAT') {
+        $log->fatal_error("building_humidity_mode=2 requires urban_hac to be ON or ON_WASTEHEAT");
+     }
+     if (! value_is_true($nl->get_value('urban_explicit_ac'))) {
+        $log->fatal_error("building_humidity_mode=2 requires urban_explicit_ac=.true.");
+     }
+  }
 }
 
 #-------------------------------------------------------------------------------

bld/namelist_files/namelist_defaults_ctsm.xml

@@ -235,6 +235,9 @@ attributes from the config_cache.xml file (with keys converted to upper-case).
 <calc_human_stress_indices               >FAST</calc_human_stress_indices>
 <calc_human_stress_indices phys="clm4_5" >NONE</calc_human_stress_indices>
 
+<!-- Urban building humidity and air-conditioning dehumidification -->
+<building_humidity_mode>0</building_humidity_mode>
+
 <!-- Explicit, time-varying urban air conditioning adoption rate scheme -->
 <urban_explicit_ac>.false.</urban_explicit_ac>
 <urban_explicit_ac phys="clm6_0" >.true.</urban_explicit_ac>

bld/namelist_files/namelist_definition_ctsm.xml

@@ -1247,6 +1247,18 @@ Turn urban air conditioning/heating ON or OFF and add wasteheat:
 <entry id="urban_explicit_ac" type="logical" category="clm_physics"
        group="clmu_inparm" valid_values="" >
 If TRUE, use explicit, time-varying AC adoption rate for air-conditioning flux and interior building temperature calculations.
+See Li et al. (2024), doi:10.1029/2023MS004107
+</entry>
+
+<entry id="building_humidity_mode" type="integer" category="clm_physics"
+       group="clmu_inparm" valid_values="0,1,2" >
+Select treatment of indoor building humidity:
+    0 = Existing CLMU formulation without indoor humidity or air-conditioning dehumidification
+    1 = Indoor humidity and latent heat exchange without air-conditioning dehumidification
+    2 = Indoor humidity and latent heat exchange with air-conditioning dehumidification and condensate production
+Modes 1 and 2 require building_temp_method=1 (prognostic calculation of interior building temp (clm5_0)).
+Mode 2 also requires urban_hac to be ON or ON_WASTEHEAT and urban_explicit_ac=.true.
+See Li et al. (2026), doi:10.1038/s44284-026-00474-4
 </entry>
 
 <entry id="urban_traffic" type="logical" category="clm_physics"

bld/unit_testers/build-namelist_test.pl

@@ -165,7 +165,7 @@ sub cat_and_create_namelistinfile {
 #
 # Figure out number of tests that will run
 #
-my $ntests = 3411;
+my $ntests = 3417;
 
 if ( defined($opts{'compare'}) ) {
    $ntests += 2061;
@@ -634,6 +634,36 @@ sub cat_and_create_namelistinfile {
 system( "touch $finidat" );
 
 my %failtest = (
+     "building humidity mode below range"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=-1",
+                                     phys=>"clm6_0",
+                                   },
+     "building humidity mode above range"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=3",
+                                     phys=>"clm6_0",
+                                   },
+     "humidity mode 1 with simple temperature"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=1,building_temp_method=0",
+                                     phys=>"clm6_0",
+                                   },
+     "humidity mode 2 with simple temperature"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=2,building_temp_method=0,urban_hac='ON',urban_explicit_ac=.true.",
+                                     phys=>"clm6_0",
+                                   },
+     "humidity mode 2 with AC off"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=2,building_temp_method=1,urban_hac='OFF',urban_explicit_ac=.true.",
+                                     phys=>"clm6_0",
+                                   },
+     "humidity mode 2 without explicit AC"
+                                  =>{ options=>"-envxml_dir .",
+                                     namelst=>"building_humidity_mode=2,building_temp_method=1,urban_hac='ON',urban_explicit_ac=.false.",
+                                     phys=>"clm6_0",
+                                   },
      "cmip7_w_issp"              =>{ options=>"-envxml_dir . -use_case 1850-2100_SSP2-4.5_transient",
                                      namelst=>"",
                                      CLM_CMIP_ERA=>"cmip7",

doc/ChangeLog

@@ -1,4 +1,78 @@
 ===============================================================
+Tag name: ctsm5.4.059
+Originator(s): cathyxinchangli (Cathy Xinchang Li, U of Illinois - Urbana-Champaign)
+Date: Mon Sep 21 10:55:44 AM MDT 2026
+One-line Summary: Indoor humidity and A/C dehumidification
+
+Purpose and description of changes
+----------------------------------
+
+ This PR adds indoor humidity and air-conditioning dehumidification to the CLMU BEM (Building Energy Model). It prognoses indoor specific humidity, calculates sensible cooling and latent dehumidification loads, and diagnoses condensate production and routes the condensate into urban runoff. The behavior is controlled by an integer CLM namelist variable, building_humidity_mode:
+
+ 0: use the existing CLMU formulation without indoor humidity or AC dehumidification;
+ 1: enable indoor humidity and latent heat exchange, but no AC dehumidification (requires prognostic building temperature, building_temp_method=1); and
+ 2: enable indoor humidity, latent heat exchange, dehumidification load, and condensate production (requires prognostic building temperature, urban_hac to be ON or ON_WASTEHEAT and urban_explicit_ac=.true.).
+
+ The default is set to 0 to ensure bit-for-bit reproducibility with the original scheme.
+
+ Indoor humidity and air-conditioning dehumidification are described by Li et al. (2026), doi:10.1038/s44284-026-00474-4.
+
+Bugs fixed
+----------
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+ Resolves #4162
+
+Notes of particular relevance for users
+---------------------------------------
+Changes to CTSM's user interface (e.g., new/renamed XML or namelist variables):
+ building_humidity_mode is added as a namelist variable
+
+Changes to documentation:
+ #4195 will address the need for new docs
+
+Contributors:
+ Lei Zhao (@Face2sea)
+ Zhiwen Luo
+ Keith Oleson (@olyson)
+ Yifan Cheng (@yifanc17)
+ Xiaoxiong Xie
+ Alvin C. G. Varquez
+ Mitsuna Sekiya
+
+Notes of particular relevance for developers:
+---------------------------------------------
+Changes to tests or testing:
+ 6 new tests in build-namelist_test.pl
+
+Testing summary:
+----------------
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho - OK (2 expected fails)
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+Answer changes
+--------------
+Changes answers relative to baseline: No (read the caveat)
+
+ Caveat:
+ - Results remain bit-for-bit under building_humidity_mode=0 (default).
+ - Comparing building_humidity_mode=1 with 0, two new variables are added (QBUILD, RHBUILD), and VENTILATION and EFLXBUILD changes because they now include latent heat exchanges between indoors and outdoors, and URBAN_AC and URBAN_HEAT changes slightly because of the changes in ventilation and higher heat capacity of moist air.
+ - Comparing building_humidity_mode=2 with 1, three more new variables (URBAN_AC_SEN, QCOND_FROM_AC, QCOND_FROM_AC_LUN) are added, and URBAN_AC increases because it now includes sensible (for cooling) and latent (for dehumidification) heat components of urban AC demand. URBAN_HEAT, VENTILATION, EFLXBUILD, WASTEHEAT changes slightly as an indirect results of the changes in AC.
+
+Other details
+-------------
+Pull Requests that document the changes (include PR ids):
+ https://github.com/ESCOMP/ctsm/pull/4164
+
+===============================================================
+===============================================================
 Tag name: ctsm5.4.058
 Originator(s): erik (Erik Kluzek,UCAR/TSS,+1 303 497 1326)
 Date: Fri Sep 18 02:58:26 PM MDT 2026

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.4.059 cathyxin 09/21/2026 Indoor humidity and A/C dehumidification
        ctsm5.4.058     erik 09/18/2026 Merge b4b-dev to master
        ctsm5.4.057     erik 09/17/2026 CDEPS/CMEPS updates for CPLHIST mode and 1850 ndep from DATM
        ctsm5.4.056 multiple 09/10/2026 Merge the wetlands branch to master

doc/source/users_guide/setting-up-and-running-a-case/history_fields_fates.rst

@@ -393,10 +393,13 @@ PROD10C_LOSS                        -                loss from 10-yr wood produc
 PROD10N                             -                10-yr wood product N                                                                           gN/m^2                                                                 F
 PROD10N_LOSS                        -                loss from 10-yr wood product pool                                                              gN/m^2/s                                                               F
 PSurf                               -                atmospheric pressure at surface (downscaled for glacier and hillslope columns)                 Pa                                                                     F
+P_AC                                -                prescribed air-conditioning ownership rate                                                     a fraction between 0 and 1                                             F
 Q2M                                 -                2m specific humidity                                                                           kg/kg                                                                  T
 QAF                                 -                canopy air humidity                                                                            kg/kg                                                                  F
 QBOT                                -                atmospheric specific humidity (downscaled to columns in glacier regions)                       kg/kg                                                                  T
 QBOT_NOT_DOWNSCALED                 -                atmospheric specific humidity (pre-downscaling)                                                kg/kg                                                                  F
+QBUILD                              -                internal urban building air specific humidity                                                  kg/kg                                                                  F
+QCOND_FROM_AC                       -                Condensed water flux from AC dehumidification                                                  mm/s                                                                   F
 QDIRECT_THROUGHFALL                 -                direct throughfall of liquid (rain + above-canopy irrigation)                                  mm/s                                                                   F
 QDIRECT_THROUGHFALL_SNOW            -                direct throughfall of snow                                                                     mm/s                                                                   F
 QDRAI                               -                sub-surface drainage                                                                           mm/s                                                                   T
@@ -477,6 +480,7 @@ RH2M                                -                2m relative humidity
 RH2M_R                              -                Rural 2m relative humidity                                                                     %                                                                      F
 RH2M_U                              -                Urban 2m relative humidity                                                                     %                                                                      F
 RHAF                                -                fractional humidity of canopy air                                                              fraction                                                               F
+RHBUILD                             -                Internal urban building air relative humidity                                                  %                                                                      F
 RH_LEAF                             -                fractional humidity at leaf surface                                                            fraction                                                               F
 RSCANOPY                            -                canopy resistance                                                                               s m-1                                                                 T
 RSSHA                               -                shaded leaf stomatal resistance                                                                s/m                                                                    T
@@ -651,6 +655,7 @@ U10_ICE                             -                10-m wind (ice landunits on
 UAF                                 -                canopy air speed                                                                               m/s                                                                    F
 UM                                  -                wind speed plus stability effect                                                               m/s                                                                    F
 URBAN_AC                            -                urban air conditioning flux                                                                    W/m^2                                                                  T
+URBAN_AC_SEN                        -                sensible heat component of urban air conditioning flux                                         W/m^2                                                                  F
 URBAN_HEAT                          -                urban heating flux                                                                             W/m^2                                                                  T
 USTAR                               -                aerodynamical resistance                                                                       s/m                                                                    F
 UST_LAKE                            -                friction velocity (lakes only)                                                                 m/s                                                                    F