ctsm5.4.048: Merge b4bdev 20260727

cime_config/testdefs/ExpectedTestFails.xml

@@ -44,13 +44,6 @@
       <comment>Restart issues with default "inactive" fields added to history by hist_all_fields.</comment>
     </phase>
   </test>
-  <test name="ERP_P64x2_D_Ld3.f10_f10_mt232.IHistClm60BgcCropCrujra.derecho_gnu.clm-default--clm-all_outputs">
-    <phase name="COMPARE_base_rest">
-      <status>FAIL</status>
-      <issue>#3661</issue>
-      <comment>Restart issues with default "inactive" fields added to history by hist_all_fields.</comment>
-    </phase>
-  </test>
   <test name="SUBSETDATAPOINT_Ld5_D_Mmpi-serial.CLM_USRDAT.I2000Clm60BgcCropCrujra.derecho_intel.clm-default">
     <phase name="NLCOMP">
       <status>FAIL</status>

cime_config/usermods_dirs/clm/PLUMBER2/defaults/shell_commands

@@ -66,7 +66,7 @@ if [[ $compset =~ .*CLM[0-9]+%[^_]*SP.* ]]; then
 	    'SNO_EXISTENCE','QSNOMELT','H2OCAN','H2OSNO','SNOCAN','SOILICE','SOILLIQ',
 	    'SOILWATER_10CM','TWS','SNOWLIQ','SNOWDP','RH2M','TSA','FLDS','Q2M','PBOT','TLAI',
 	    'WIND','FIRE','FCTR','FCEV','FGEV','FSM','COSZEN','H2OSOI','BTRANMN','TV','RSSUN',
-	    'RSSHA','FSH_G','RHAF','RH_LEAF','RH','T10','TG','SABG','SABV','FPSN','TBOT','TAUX',
+	    'RSSHA','FSH_G','RH_LEAF','RH','T10','TG','SABG','SABV','FPSN','TBOT','TAUX',
 	    'TAUY','QSNOEVAP','QFLX_SOLIDEVAP_FROM_TOP_LAYER','QFLX_SNOW_DRAIN','H2OSFC','FPSN'" >> user_nl_clm 
   else
     echo "lai_dtlimit=30." >> user_nl_clm
@@ -82,7 +82,7 @@ else  # for BGC cases
                'FSNO','SNO_T','RAIN','SNOW','QVEGT','QVEGE','QSOIL','QRUNOFF','QOVER','QH2OSFC',
                'QDRAI','QDRAI_PERCH','SNO_EXISTENCE','QSNOMELT','H2OCAN','H2OSNO','SNOCAN','SOILICE',
                'SOILLIQ','SOILWATER_10CM','TWS','SNOWLIQ','SNOWDP','RH2M','TSA','FLDS','Q2M','PBOT',
-               'TLAI','WIND','FIRE','FSM','COSZEN','BTRANMN','TV','RSSUN','RSSHA','FSH_G','RHAF',
+               'TLAI','WIND','FIRE','FSM','COSZEN','BTRANMN','TV','RSSUN','RSSHA','FSH_G',
                'RH_LEAF','RH','T10','TG','SABG','SABV','TBOT','TAUX','TAUY','QSNOEVAP','H2OSFC'" >> user_nl_clm
     echo "" >> user_nl_clm
   fi

doc/source/tech_note/BVOCs/CLM50_Tech_Note_BVOCs.rst

@@ -1,11 +1,17 @@
-.. _rst_Biogenic Volatile Organic Compounds (BVOCs):
+.. _rst_Biogenic Volatile Organic Compounds (BVOCs) and Dry Dep:
+
+Biogenic Volatile Organic Compounds (BVOCs) and Dry Deposition of Atmospheric Gases
+===================================================================================
+
+This section describes (1) emissions of volatile organic compounds from vegetation and (2) dry deposition of atmospheric gases.  
+These processes are needed for atmospheric composition simulations, but do not affect the land state.
 
 Biogenic Volatile Organic Compounds (BVOCs)
-===============================================
+-------------------------------------------
 
 This section briefly describes the biogenic volatile organic compound (BVOC) emissions model implemented in CLM. The CLM3 version (:ref:`Levis et al. 2003 <Levisetal2003>`; :ref:`Oleson et al. 2004 <Olesonetal2004>`) was based on :ref:`Guenther et al. (1995) <Guentheretal1995>`. :ref:`Heald et al. (2008) <Healdetal2008>` updated this scheme in CLM4 based on :ref:`Guenther et al (2006) <Guentheretal2006>`. The current version was first implemented in CLM4.5 and is currently based on MEGAN2.1 discussed in detail in :ref:`Guenther et al. (2012) <Guentheretal2012>`. As of CLM5, CLM-MEGAN has included these features: 1) expansion to 147 chemical compounds, 2) the treatment of the light-dependent fraction (LDF) for each compound, 3) inclusion of the inhibition of isoprene emission by atmospheric CO\ :sub:`2`, 4) emission factors mapped to the specific PFTs of the CLM. As of CLM6, CLM-MEGAN includes two new features: 5) the impact of drought, and 6) high-latitude specific isoprene emissions.
 
-MEGAN2.1 describes the emissions of speciated monoterpenes, sesquiterpenes, oxygenated VOCs as well as isoprene. A flexible scheme has been implemented in the CLM to specify a subset of emissions. This allows for additional flexibility in grouping chemical compounds to form the lumped species frequently used in atmospheric chemistry. The mapping or grouping is therefore defined through a namelist parameter in drv\_flds\_in, e.g. megan\_specifier = 'ISOP = isoprene', 'BIGALK pentane + hexane + heptane + tricyclene'.
+MEGAN2.1 describes the emissions of speciated monoterpenes, sesquiterpenes, oxygenated VOCs as well as isoprene. A flexible scheme has been implemented in the CLM to specify a subset of emissions. This allows for additional flexibility in grouping chemical compounds to form the lumped species frequently used in atmospheric chemistry. The mapping or grouping is therefore defined through a namelist parameter in drv\_flds\_in, e.g. megan\_specifier = 'ISOP = isoprene', 'BIGALK = tricyclene + camphor + fenchone + thujone_a + thujone_b + cineole_1_8 + borneol + bornyl_ACT + cedrol + decanal + heptanal + heptane + hexane + nonanal + octanal + octanol + oxopentanal + pentane + hexanal + hexanol_1 + pentanal + heptanone'.
 
 Terrestrial BVOC emissions from plants to the atmosphere are expressed as a flux, :math:`F_{i}` (:math:`\mu` \ g C m\ :sup:`-2` ground area h\ :sup:`-1`), for emission of chemical compound :math:`i`
 
@@ -63,3 +69,14 @@ where :math:`T_{leaf}` denotes the leaf temperature, :math:`R` is the gas consta
    :label: C3 arctic grass parameter
 
    C_{g} = 95 + 9.49 e^{0.53 (288.15-T_{240})}
+
+
+Dry Deposition of Gases in the Atmosphere
+-----------------------------------------
+
+Dry deposition is represented following the Wesely resistance approach as described in :ref:`Lamarque et al. (2012) <Lamarqueetal2012>`. Following this approach, all deposited chemical species (the specific list of deposited species depends on the chemical mechanism used) are mapped to a weighted-combination of ozone and sulfur dioxide depositions; this combination represents a definition of the ability of each considered species to oxidize or to be taken up by water. In particular, the latter is dependent on the effective Henry's law coefficient. While this weighting is applicable to many species, we have included specific representations for CO/H\ :sub:`2` and peroxyacetylnitrate (PAN). Furthermore, it is assumed that the surface resistance for SO\ :sub:`2` can be neglected. See :ref:`Lamarque et al. (2012) <Lamarqueetal2012>` for details and additional references.
+
+The computation of surface resistances in CLM leads to a representation at the level of each plant functional type of the various drivers for deposition velocities. The grid-averaged velocity is computed as the weighted-mean over all land cover types available at each grid point. This ensures that the impact on deposition velocities from changes in land cover, land use or climate is taken into account. All species in the atmospheric chemical mechanism are by default affected by dry deposition if deposition velocities are defined in the model.
+
+Dry deposition of ozone also includes stomatal uptake, initially described in :ref:`Val Martin et al. (2014) <ValMartinetal2014>` and updated in :ref:`Emmons et al. (2020) <Emmonsetal2020>`.
+

doc/source/tech_note/FATES/CLM50_Tech_Note_FATES.rst

@@ -0,0 +1,60 @@
+.. _rst_Ecosystem Demography with FATES:
+
+Ecosystem Demography with FATES
+===================================
+
+Ecosystem Demography
+^^^^^^^^^^^^^^^^^^^^^^^
+
+An important component of representing the land surface is accurately capturing vegetation dynamics and their impact on and interaction with the Earth system. Some models utilize dynamic global vegetation models (DGVMs), which track the fractional cover of plant functional types (PFTs) on a grid cell over time, usually driven by "climate envelopes" which use climate metrics (e.g., temperature and precipitation) to determine where PFTs can grow. However, many DGVMs still do not simulate important processes like mortality, regeneration, and plant competition, which we know are important for accurately capturing vegetation and carbon dynamics (:ref:`Fisher et al. 2015<Fisheretal2015>`).
+
+Ecosystem demography models explicitly represent the size structure and successional state of vegetation, through direct simulation of plant growth, mortality, and regeneration. Thus, important vegetation characteristics such as vegetation canopy height, succession, and even potential biome shifts become emergent properties of the model rather than being prescribed.
+
+FATES
+^^^^^^^^^^^^^^^^^^^^
+
+FATES is the "Functionally Assembled Terrestrial Ecosystem Simulator". It is an external module which can run within a given "Host Land Model" (HLM) like CLM. FATES was derived from the CLM Ecosystem Demography model (CLM(ED)). FATES is documented in :ref:`Fisher et al. (2015)<Fisheretal2015>`, and has since been further developed and evaluated across a range of ecosystems and configurations (e.g., :ref:`Koven et al., 2020<Kovenetal2020>`; :ref:`Buotte et al., 2021<Buotteetal2021>`; :ref:`Needham et al., 2022<Needhametal2022>`; :ref:`Shuman et al., 2024<Shumanetal2024>`)
+
+FATES is derived from the work of :ref:`Moorcroft et al. (2001)<mc_2001>` and is a cohort model of vegetation competition and co-existence, allowing a representation of the biosphere which accounts for the division of the land surface into successional stages, and for competition for light between height structured cohorts of representative trees of various plant functional types. Individual plants within FATES are grouped into "cohorts" of the same size and PFT, and these cohorts compete for light and resources on individual "patches" that represent different disturbance histories (:numref:`fig_FATES_vs_CLM`). This type of ecosystem heterogeneity is in contrast to the default vegetation model in CLM, which uses two (sunlit & shaded) "big leaf" canopies per PFT, each on their own patch, with no representation of within-canopy structural heterogeneity or disturbance history. Recent work comparing the parametric sensitivity of default CLM and CLM-FATES highlights key structural differences between the two approaches (:ref:`Foster et al., 2026<Fosteretal2026>`).
+
+.. _fig_FATES_vs_CLM:
+
+.. figure:: FATES_tiling.png
+
+   Comparison of grid structure in CLM-FATES and CLM. (a) An example grid of FATES patches showing individual cohorts of plants of different size and PFT. (b) those same FATES patches represented as their age-since-disturbance. (c) the equivalent gridcell in default CLM, showing instead a set of specific PFTs with fixed areas.
+
+FATES also introduces a new organizational structure to CLM which differs from its default organization. The original hierarchical organization of CLM as described in :ref:`Oleson et al. (2013)<Olesonetal2013>` are gridcells which contain land units (e.g. vegetated, lake, urban), which contain columns (e.g., naturally vegetated), which contain PFTs. FATES replaces the PFT level of this hierarchy with patches and cohorts. Thus, gridcells contain land units, which contain columns, which contain patches, which in turn contain some number of cohorts of the same or different PFT (:numref:`fig_FATES_and_CLM_hierarchy`). 
+
+.. _fig_FATES_and_CLM_hierarchy:
+
+.. figure:: FATES_and_CLM_hierarchy.png
+   :width: 60%
+
+   Comparison of the organizational hierarchy of default CLM (left) and CLM-FATES (right).
+
+The implementation of the Ecosystem Demography concept within FATES links the surface flux and canopy physiology concepts in CLM with numerous additional developments necessary to accommodate the new model. These include a version of the SPITFIRE (Spread and InTensity of Fire) model of :ref:`Thonicke et al. (2010)<thonickeetal2010>`, and an adoption of the concept of `Perfect Plasticity Approximation` approach of :ref:`Purves et al. 2008<purves2008>`, :ref:`Lichstein et al. 2011<lichstein2011>` and :ref:`Weng et al. 2014<weng2014>`, in accounting for the spatial arrangement of crowns. Novel algorithms accounting for the fragmentation of coarse woody debris into chemical litter streams, for the physiological optimization of canopy thickness, for the accumulation of seeds in the seed bank, for multi-layer multi-PFT radiation transfer, for drought-deciduous and cold-deciduous phenology, for carbon storage allocation, and for tree mortality under carbon stress, are also included.
+
+
+FATES Reduced Complexity Modes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, FATES can be run in several different "reduced complexity modes", where parts of the vegetation model are driven by input data rather than simulated. These modes can be used to facilitate calibration, test features, or run simulations more quickly. These modes are:
+
+1. **Satellite Phenology (SP) Mode**: this mode is designed to run with leaf area index (LAI), stem area index (SAI), and canopy height (HTOP) as input to the model. As such, all processes that are normally used to calculate these values are turned off (e.g., mortality, allocation, etc.)
+
+2. **No-Competition Mode**: this mode runs with full complexity in terms of processes, but places each FATES PFT on its own patch. As such, PFTs do not compete with one another. 
+
+3. **Fixed Biogeography Mode**: this mode turns off prognostic spatial changes in the distribution of vegetation and instead, the model uses input data to determine which PFTs are present at any given gridcell. The patch area for each PFT is derived from the input CLM surface dataset. However, please note that the PFTs in the FATES parameter file do not always map one-to-one with the CLM PFTs on the surface dataset. See the FATES parameter *fates_hlm_pft_map* on the FATES parameter file for the correct mapping of FATES to CLM PFTs.
+
+Note that there are different combinations of no-competition and fixed biogeography mode that will result in different behaviors. See the `FATES namelist documentation <https://fates-users-guide.readthedocs.io/en/latest/user/namelist-options.html>`_ for these options.
+
+Scientifically Supported CLM-FATES Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We currently scientifally support CLM-FATES run in `carbon-only mode <https://fates-users-guide.readthedocs.io/en/latest/user/PARTEH-Modes.html>`_, and with either SP or no-competition + fixed biogeography mode. Carbon and nitrogen capabilities are currently enabled, but are still being scientifically tested. C-N mode can be turned on using the CLM namelist variable ``fates_parteh_mode = "carbon_nitrogen"``, as opposed to the default ``fates_parteh_mode = "carbon_only"``.
+
+
+Further reading
+^^^^^^^^^^^^^^^^^^^^
+
+For more information about FATES, including a Users Guide and Technical Note, please see the `FATES documentation <https://fates-users-guide.readthedocs.io/en/latest/index.html>`_.