From e413977009b44f6142fa7ae694d9bf48b7ed0438 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Tue, 4 Aug 2026 15:11:03 -0600 Subject: [PATCH 01/12] Make ClmSp, ClmBgc, and ClmBgcCrop acronyms consistent in the docs --- doc/source/users_guide/overview/getting-help.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 439d764823..0d19e4c6ac 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -60,9 +60,9 @@ If you have any problems, additional questions, bug reports, or any other feedba .. _acronyms-and-terms: ---------------------------------------- -Some Acronym's and Terms We'll be Using ---------------------------------------- +-------------------------------------- +Some Acronyms and Terms We'll be Using +-------------------------------------- CAM Community Atmosphere Model (CAM). The prognostically active atmosphere model component of CESM. @@ -77,12 +77,12 @@ CLM Community Land Model (CLM). The prognostically active land model component of CESM. CLMBGC - Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option for this is + Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. Hereonafter we will refer to this as ClmBgc, similar to the corresponding compset alias (e.g. Clm60Bgc). The CLM_CONFIG_OPTS option is ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc`` CLMBGC-Crop - Community Land Model (|version|) with BGC Biogeochemistry and prognotic crop. The CLM_CONFIG_OPTS option for this is + Community Land Model (|version|) with BGC Biogeochemistry and prognotic crop. Hereonafter we will refer to this as ClmBgcCrop, similar to the corresponding compset alias (e.g. Clm60BgcCrop). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc -crop`` @@ -92,7 +92,7 @@ CLMCN ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` CLMSP - Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0, CLM4.5 or |version|) The CLM_CONFIG_OPTS option for this is + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0, CLM4.5 or |version|). Hereonafter we will refer to this as ClmSp, similar to the corresponding compset alias (e.g. Clm60Sp). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc sp" -append`` From eb6bf0e07fb54f8a08d8f12ccde7d3725006ff4a Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Tue, 4 Aug 2026 18:51:03 -0600 Subject: [PATCH 02/12] Make ClmSp, ClmBgc, ClmBgcCrop acronyms consistent in the docs The docs build without error, but I have not inspected them, yet --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 16 +++++----- .../users_guide/overview/introduction.rst | 10 +++--- ...0_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png} | 0 ...0_1deg_CRUJRA2024_fini_2000_SP_Spinup.png} | 0 .../Running-with-irrigation.rst | 2 +- ...atellite-Phenology-Model-ClmSp-spinup.rst} | 32 +++++++++---------- ...ing-up-the-biogeochemistry-Bgc-spinup.rst} | 32 +++++++++---------- .../running-special-cases/index.rst | 4 +-- .../customizing-the-clm-configuration.rst | 4 +-- 9 files changed, 50 insertions(+), 50 deletions(-) rename doc/source/users_guide/running-special-cases/{Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png => Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png} (100%) rename doc/source/users_guide/running-special-cases/{Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png => Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png} (100%) rename doc/source/users_guide/running-special-cases/{Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst => Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst} (80%) rename doc/source/users_guide/running-special-cases/{Spinning-up-the-biogeochemistry-BGC-spinup.rst => Spinning-up-the-biogeochemistry-Bgc-spinup.rst} (69%) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index ec43a50cd8..8f3375dcdb 100755 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -10,7 +10,7 @@ Summary of CLM5.0 updates relative to the CLM4.5 We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). -CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the BGC configuration: +CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the Bgc configuration: - New crop functional types @@ -53,7 +53,7 @@ Introduction Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `), and CLM4.5BGC. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), and those are now incorporated into CLM5. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `), and Clm45Bgc. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), and those are now incorporated into CLM5. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. @@ -70,7 +70,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr .. _Table Crop plant functional types: -.. table:: Crop plant functional types (PFTs) included in CLM5BGCCROP. +.. table:: Crop plant functional types (PFTs) included in Clm50BgcCrop. === =========================== ================ =========================== IVT Plant function types (PFTs) Management Class Crop Parameters Used @@ -146,7 +146,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr Phenology ^^^^^^^^^ -CLM5-BGC includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). CLM5-BGC-crop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. +Clm50Bgc includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). Clm50BgcCrop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. @@ -217,7 +217,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When :math:`GD .. _Table Crop phenology parameters: -.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM5BGCCROP. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in Clm50BgcCrop. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. :header-rows: 1 * - \ @@ -569,7 +569,7 @@ Annual food crop yields (g dry matter m\ :sup:`-2`) can be calculated by saving .. _Table Crop allocation parameters: -.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM5BGCCROP. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in Clm50BgcCrop. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ \ temperate corn spring wheat temperate soybean cotton rice sugarcane tropical corn tropical soybean miscanthus switchgrass @@ -622,7 +622,7 @@ where :math:`z_{top}^{\max }` is the maximum top-of-canopy height of the crop (: Interactive Fertilization ''''''''''''''''''''''''' -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM5BGCCROP is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field ``manunitro``. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States :ref:`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current CLM5BGCCROP, manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in Clm50BgcCrop is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field ``manunitro``. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States :ref:`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current Clm50BgcCrop, manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: .. math:: :label: 25.17 @@ -658,7 +658,7 @@ where :math:`baset` is the *base temperature for GDD* (7\ :sup:`th` row) in :num Separate reproductive pool '''''''''''''''''''''''''' -One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM5BGCCROP, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. +One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In Clm50BgcCrop, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. .. _Tillage: diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 1dcf901ff8..f4f04d5195 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -61,7 +61,7 @@ In this introduction we first give a simple guide to understand the document con As a followup to the tools chapter, :ref:`adding-new-resolutions-section` tells how to add files to the XML database for build-namelist to use. This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (CLM4.0, CLM4.5 and |version| physics). -In :ref:`running-special-cases-section`, again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up the |version|-BGC and CLMCN models as well as CLM with dynamic vegetation active (CNDV). We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. We also give instructions on running both the prognostic crop and irrigation models. Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. +In :ref:`running-special-cases-section`, again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up the Bgc and Sp models, and we tell the user how to use the DATM model to send historical CO2 data to CLM. :ref:`running-single-points` outlines how to do single-point or regional simulations using |version|. This is useful to either compare |version| simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple sampling of existing inputs to more complex where you create all your own datasets, tying into :ref:`using-clm-tools-section` and also :ref:`adding-new-resolutions-section` to add the files into the build-namelist XML database. @@ -92,15 +92,15 @@ The README (which can be found in ``$CTSMROOT/doc``) is repeated here. - |version| includes BOTH the old CLM4.0, CLM4.5 physics AND the new |version| physics and you can toggle between those three. The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. And finally the "standard" practice for |version| is to run with BGC and Prognostic Crop on, with the MOSART model for river routing, as well as the CISM ice sheet model, and using GSWP3 atmospheric forcing. "BGC" is the new |version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see :ref:`acronyms-and-terms`). -- When running with CLMCN (either CLM4.0 or |version| physics) or |version|-BGC, it is critical to begin with initial conditions that are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` for information on how to provide initial conditions for your simulation. +- When running with BGC vegetation (either CLM4.5, CLM5.0, or |version| physics), it is critical to begin with initial conditions that are provided with the release or to spin the model up following the BGC spinup procedure before conducting scientific runs (see :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` for information on how to provide initial conditions for your simulation. -- Initial condition files are provided for CLM4.0-CN as before, for fully coupled BCN and offline ICN cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with CLMSP for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. +- Initial condition files are provided for CLM4.5 and CLM5.0 from the previous release, for fully coupled B compsets with BGC and offline I compset BGC and SP cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ClmBgc with the prognostic crop model for 2000 at 2deg resolution, and one with ClmSp for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. -- Initial condition files are also provided for |version| for several configurations and resolutions. For CLM4.5-SP and CLM4.5-BGC with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For |version|-SP and |version|-BGC-Crop with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at. +- Initial condition files are also provided for |version| for several configurations and resolutions. For Clm45Sp and Clm45Bgc with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For |version| Sp and BgcCrop with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at. - Users can interpolate initial condition files at different resolutions at startup of a CLM4.5 or |version| simulation. And the file created can be stored for later use. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In |version| for both |version|-CN, |version|-BGC, and |version|-BGC-Crop the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. +- In |version| for both Bgc and BgcCrop the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. - Aerosol deposition is a required field to both CLM4.0, CLM4.5 and |version| physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. diff --git a/doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png b/doc/source/users_guide/running-special-cases/Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png similarity index 100% rename from doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png rename to doc/source/users_guide/running-special-cases/Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png diff --git a/doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png b/doc/source/users_guide/running-special-cases/Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png similarity index 100% rename from doc/source/users_guide/running-special-cases/Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png rename to doc/source/users_guide/running-special-cases/Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png diff --git a/doc/source/users_guide/running-special-cases/Running-with-irrigation.rst b/doc/source/users_guide/running-special-cases/Running-with-irrigation.rst index 5e9adb4b6a..d04e413401 100644 --- a/doc/source/users_guide/running-special-cases/Running-with-irrigation.rst +++ b/doc/source/users_guide/running-special-cases/Running-with-irrigation.rst @@ -15,7 +15,7 @@ Example: Irrigation Simulation ------------------------------------------ :: - # Note here we do a CLMSP simulation as that is what has been validated + # Note here we do a ClmSp simulation as that is what has been validated > cd cime/scripts > ./create_newcase -case IRRIG -res f19_g17_gl4 -compset I1850Clm50BgcCrop > cd IRRIG diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst similarity index 80% rename from doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst rename to doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst index 6580860a83..cdb730a758 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst @@ -8,14 +8,14 @@ The spin-up of a land surface model is generally defined as an adjustment process as the model approaches equilibrium in its state variables (:ref:`Yang et al. 1995`). This is usually accomplished by forcing the model with repeated years of identical atmospheric forcing until the model state at year ``n+1`` is the same as that at year ``n`` within some defined threshold in the state variables. -To spin-up the CLM60SP model you generally need to run CLM60SP for a few cycles of repeated atmospheric forcing starting from arbitrary initial conditions, the main goal being to ensure that the turbulent fluxes and soil water and temperature have reached equilibrium (minimal trends). You then use the final restart file resulting from that simulation as initial conditions in other simulations. Alternatively, you can also start from an initial file that is typically already provided for you as part of the selected compset. Generally, this will allow for shorter spinup times if your simulation configuration is similar to the one run to generate the default initial file. +To spin-up the Clm60Sp model you generally need to run Clm60Sp for a few cycles of repeated atmospheric forcing starting from arbitrary initial conditions, the main goal being to ensure that the turbulent fluxes and soil water and temperature have reached equilibrium (minimal trends). You then use the final restart file resulting from that simulation as initial conditions in other simulations. Alternatively, you can also start from an initial file that is typically already provided for you as part of the selected compset. Generally, this will allow for shorter spinup times if your simulation configuration is similar to the one run to generate the default initial file. -The following steps illustrate how to setup and run a 51 year CLM60SP spinup from arbitrary initial conditions using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): +The following steps illustrate how to setup and run a 51 year Clm60Sp spinup from arbitrary initial conditions using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): :: cd cime/scripts - ./create_newcase --case Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX - cd Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000/ + ./create_newcase --case Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX + cd Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000/ ./case.setup ./xmlchange CLM_FORCE_COLDSTART=on ./xmlchange RUN_STARTDATE=0001-01-01 @@ -32,12 +32,12 @@ Setting ``CLM_FORCE_COLDSTART=on`` forces the model to use arbitrary initial con The spinup stability script available in the CLM checkout at ``tools/contrib/SpinupStability_SP_v10.ncl`` can be used to assess the stability or equilibrium of key model variables. Key settings in that script for this example simulation are :: - caseid = "Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000" + caseid = "Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000" subper = 10 The ``subper`` setting tells the script how many years of atmospheric forcing were repeated, thus the equilibrium state of the model in this example is evaluated every 10 years. -:numref:`Figure CLM60SP spinup plot for arbitrary initial conditions` shows spinup behavior for this simulation. Variables are plotted every 10 years, hence six points (years 1, 11, 21, 31, 41, and 51) are plotted in the leftmost plots for each variable. These include FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), FPSN (photosynthesis), H2OSOI (soil water at layer 8 which is about 1 meter), TSOI (soil temperature at layer 10 which is about 3 meters), and TWS (total water storage). The speed at which these variables reach a specified equilibrium state (denoted by falling within the dotted lines in the rightmost plots for each variable) varies by variable, TWS generally takes the longest to equilibrium. The plot in the lower left denotes the percent of land area that is not in TWS equilibrium. The contour plots show which grid cells are not in equilibrium for the last two cycles of atmospheric forcing. The equilibrium thresholds are fairly arbitrary for the SP configuration and can be chosen by the user. The current settings are +:numref:`Figure Clm60Sp spinup plot for arbitrary initial conditions` shows spinup behavior for this simulation. Variables are plotted every 10 years, hence six points (years 1, 11, 21, 31, 41, and 51) are plotted in the leftmost plots for each variable. These include FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), FPSN (photosynthesis), H2OSOI (soil water at layer 8 which is about 1 meter), TSOI (soil temperature at layer 10 which is about 3 meters), and TWS (total water storage). The speed at which these variables reach a specified equilibrium state (denoted by falling within the dotted lines in the rightmost plots for each variable) varies by variable, TWS generally takes the longest to equilibrium. The plot in the lower left denotes the percent of land area that is not in TWS equilibrium. The contour plots show which grid cells are not in equilibrium for the last two cycles of atmospheric forcing. The equilibrium thresholds are fairly arbitrary for the Sp configuration and can be chosen by the user. The current settings are :: glob_thresh_fsh = 0.02 ; global threshold for FSH equilibrium (delta W m-2 / yr) @@ -48,18 +48,18 @@ The ``subper`` setting tells the script how many years of atmospheric forcing we glob_thresh_tsoi = 0.02 ; global threshold for TSOI equilibrium (delta K / yr) glob_thresh_area = 3.0 ; global threshold percent area with TWS disequilibrium gt 0.01 m -.. _Figure CLM60SP spinup plot for arbitrary initial conditions: +.. _Figure Clm60Sp spinup plot for arbitrary initial conditions: -.. figure:: Clm60SP_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png +.. figure:: Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png - SP spinup plot for arbitrary initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. + Sp spinup plot for arbitrary initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. -You can also start from a default initial file that is provided as part of the selected compset. The following steps illustrate how to setup and run a 51 year CLM60SP spinup from default initial conditions again using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): +You can also start from a default initial file that is provided as part of the selected compset. The following steps illustrate how to setup and run a 51 year Clm60Sp spinup from default initial conditions again using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): :: cd cime/scripts - ./create_newcase --case Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX - cd Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000/ + ./create_newcase --case Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000 --compset I2000Clm60SpCrujra --res f09_t232 --run-unsupported --project XX + cd Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000/ ./case.setup echo "use_init_interp = .true" >> user_nl_clm ./xmlchange RUN_STARTDATE=0001-01-01 @@ -73,10 +73,10 @@ You can also start from a default initial file that is provided as part of the s The difference from the previous simulation is that we don't set ``CLM_FORCE_COLDSTART=on`` so that the model uses the default provided initial conditions. In this case, setting ``use_init_interp = .true`` is required because the model configuration used is slightly different from that used to generate the initial file. -:numref:`Figure CLM60SP spinup plot for default initial conditions` shows spinup behavior for this simulation. Here we can see that equilbrium is reached much sooner because the default initial file is from a spinup where the model configuration was very similar to this one. +:numref:`Figure Clm60Sp spinup plot for default initial conditions` shows spinup behavior for this simulation. Here we can see that equilbrium is reached much sooner because the default initial file is from a spinup where the model configuration was very similar to this one. -.. _Figure CLM60SP spinup plot for default initial conditions: +.. _Figure Clm60Sp spinup plot for default initial conditions: -.. figure:: Clm60SP_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png +.. figure:: Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png - SP spinup plot for default initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. + Sp spinup plot for default initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst similarity index 69% rename from doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst rename to doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst index 4372c946f0..58545ed567 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-BGC-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst @@ -2,37 +2,37 @@ .. _spinning-up-clm-bgc: -============================= - Spinup of CLM-BGC-Crop -============================= +===================== + Spinup of ClmBgcCrop +===================== -To get the CLM-BGC-Crop model to a steady state, you start it from arbitrary initial conditions using the "accelerated decomposition spinup" (``CLM_ACCELERATED_SPINUP on`` in CLM `env_run.xml`, see example below) mode for 300-400 simulation years. :numref:`Figure BGC-Crop AD spinup plot for 1850` shows spinup behavior for an 1850 BGC-Crop accelerated decomposition (AD) case using CRUJRA atmospheric forcing. Generally, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. +To get the ClmBgcCrop model to a steady state, you start it from arbitrary initial conditions using the "accelerated decomposition spinup" (``CLM_ACCELERATED_SPINUP on`` in CLM `env_run.xml`, see example below) mode for 300-400 simulation years. :numref:`Figure BgcCrop AD spinup plot for 1850` shows spinup behavior for an 1850 BgcCrop accelerated decomposition (AD) case using CRUJRA atmospheric forcing. Generally, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. -.. _Figure BGC-Crop AD spinup plot for 1850: +.. _Figure BgcCrop AD spinup plot for 1850: .. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_AD_Spinup-0.png - BGC-Crop AD spinup plot for a year 1850 case with CRUJRA atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. + BgcCrop AD spinup plot for a year 1850 case with CRUJRA atmospheric forcing. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. -After this you continue in "SASU" mode (``CLM_ACCELERATED_SPINUP sasu`` in CLM `env_run.xml`, see example below), and run for 300-350 simulation years. :numref:`Figure BGC-Crop SASU spinup plot for 1850` shows spinup behavior for an 1850 BGC-Crop SASU case using CRUJRA atmospheric forcing. The criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy and need not be met for this step. +After this you continue in "SASU" mode (``CLM_ACCELERATED_SPINUP sasu`` in CLM `env_run.xml`, see example below), and run for 300-350 simulation years. :numref:`Figure BgcCrop SASU spinup plot for 1850` shows spinup behavior for an 1850 BgcCrop SASU case using CRUJRA atmospheric forcing. The criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy and need not be met for this step. -.. _Figure BGC-Crop SASU spinup plot for 1850: +.. _Figure BgcCrop SASU spinup plot for 1850: .. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_SASU_Spinup-0.png - BGC-Crop SASU spinup plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BGC-Crop AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. + BgcCrop SASU spinup plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BgcCrop AD spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. -After this you continue in standard mode for 200 years. We refer to this phase as post-SASU, pSASU, or normal mode (``CLM_ACCELERATED_SPINUP off`` in CLM `env_run.xml`, see example below). :numref:`Figure BGC-Crop normal mode plot for 1850` shows spinup behavior for an 1850 BGC-Crop normal mode case using CRUJRA atmospheric forcing. As before, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy. +After this you continue in standard mode for 200 years. We refer to this phase as post-SASU, pSASU, or normal mode (``CLM_ACCELERATED_SPINUP off`` in CLM `env_run.xml`, see example below). :numref:`Figure BgcCrop normal mode plot for 1850` shows spinup behavior for an 1850 BgcCrop normal mode case using CRUJRA atmospheric forcing. As before, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy. -.. _Figure BGC-Crop normal mode plot for 1850: +.. _Figure BgcCrop normal mode plot for 1850: .. figure:: ctsm5.4.CMIP7_ciso_ctsm5.3.075_f09_124_pSASU_Spinup-0.png - BGC-Crop normal mode plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BGC-Crop SASU spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. + BgcCrop normal mode plot for a year 1850 case with CRUJRA atmospheric forcing and initialization from the end of the BgcCrop SASU spinup case. Variables examined are TOTECOSYSC (total ecosystem carbon), TOTSOMC (total soil organic matter carbon), TOTVEGC (total vegetation carbon), TLAI (total leaf area index), GPP (gross primary production) and TWS (total water storage). Generated using .../tools/contrib/SpinupStability_BGC_v11.ncl. As an alternative to spinning up, one may start from a default initial file that is setup as part of the selected compset. When the simulation's spatial resolution is identical to the initial file's resolution, it may still take 10 or more years for variables such as TLAI (total leaf area index), GPP (gross primary production), and TWS (total water storage) to reach a new equilibrium state due to the different atmospheric forcing. Similarly, it may take 10 or more years for these variables to reach a new equilibrium when switching atmospheric CO2 from 1850 to a present-day value. -Example: AD_spinup Simulation for CLM-BGC-Crop +Example: AD_spinup Simulation for ClmBgcCrop -------------------------------------------------------- For the first step of running in ``CLM_ACCELERATED_SPINUP on`` mode, you will setup a case, and then edit the values in env_build.xml and env_run.xml so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. Try the following: @@ -63,7 +63,7 @@ In CLM's /tools/contrib directory there are three versions of this .ncl script: - SpinupStability_BGC_v11.ncl for Bgc and BgcCrop compsets run on 2D lat/lon grids. - SpinupStability_BGC_v12_SE.ncl for Bgc, BgcCrop, or Fates compsets run on certain spectral element grids (currently ne120, ne30, ne16). -- SpinupStability_SP_v10.ncl for Sp compsets run on 2D lat/lon grids. See section :numref:`spinning-up-sp` for helpful pointers about this script that may also apply to the BGC-Crop versions. +- SpinupStability_SP_v10.ncl for Sp compsets run on 2D lat/lon grids. See section :numref:`spinning-up-sp` for helpful pointers about this script that may also apply to the BgcCrop versions. To run one of these scripts on derecho, one loads ncl (``module load ncl``) and submits with ``ncl SpinupStability_BGC_v11.ncl``, for example. Before running one needs to confirm a few easy settings appearing near the top of each script. @@ -71,7 +71,7 @@ One of the settings that may not be intuitive at first glance is ``annual_hist`` .. _eg-sasu-spinup: -Example: SASU_spinup Simulation for CLM-BGC-Crop +Example: SASU_spinup Simulation for ClmBgcCrop ------------------------------------------------------------------ :: @@ -99,7 +99,7 @@ Example: SASU_spinup Simulation for CLM-BGC-Crop Save the last restart file from this step and use it as the ``finidat`` file for the normal mode simulation. Save the restart file from the end of the normal mode simulation to use as a "finidat" file for future simulations. -Example: Normal mode simulation for CLM-BGC-Crop +Example: Normal mode simulation for ClmBgcCrop -------------------------------------------------- :: diff --git a/doc/source/users_guide/running-special-cases/index.rst b/doc/source/users_guide/running-special-cases/index.rst index 31d5a3b148..e8384ebd49 100644 --- a/doc/source/users_guide/running-special-cases/index.rst +++ b/doc/source/users_guide/running-special-cases/index.rst @@ -19,8 +19,8 @@ Running Special Cases Running-with-irrigation.rst Running-with-custom-crop-calendars.rst Running-with-tillage.rst - Spinning-up-the-Satellite-Phenology-Model-CLMSP-spinup.rst - Spinning-up-the-biogeochemistry-BGC-spinup.rst + Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst + Spinning-up-the-biogeochemistry-Bgc-spinup.rst Running-with-excess-ground-ice.rst Running-with-MOAR-data-as-atmospheric-forcing-to-spinup-the-model.rst Running-with-your-own-previous-simulation-as-atmospheric-forcing-to-spinup-the-model.rst diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index e0c09c0dd1..074a750c26 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -284,7 +284,7 @@ The ``$CTSMROOT/cime_config/buildnml`` script already sets the resolution and ma #. ``-verbose`` -``-bgc_spinup`` is an option only available for |version| for any configuration when CN is turned on (so either CLMCN or CLMBGC). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See :ref:`spinning-up-clm-bgc` for an example using this option. +``-bgc_spinup`` is an option only available for |version| for any configuration when BGC is turned on (ClmBgc). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See :ref:`spinning-up-clm-bgc` for an example using this option. .. todo:: Update the above. @@ -449,7 +449,7 @@ Thus a setting in ``CLM_BLDNML_OPTS`` will override a setting for the same thing Setting Your Initial Conditions File ------------------------------------ -Especially with CLMBGC and CLMCN starting from initial conditions is very important. Even with CLMSP it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file. +Especially with ClmBgc starting from initial conditions is very important. Even with ClmSp it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file. - :ref:`doing-a-hybrid-sim-for-init-conds` - :ref:`doing-a-branch-sim-for-init-conds` From d982c7211e695315d3293d70780bcda9fbab25a7 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 17:02:29 -0600 Subject: [PATCH 03/12] Clarify the use of BGC & CROP in CLM50_Tech_Note_Crop_Irrigation.rst --- .../CLM50_Tech_Note_Crop_Irrigation.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index 8f3375dcdb..ef078b194d 100755 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -10,7 +10,7 @@ Summary of CLM5.0 updates relative to the CLM4.5 We describe here the complete crop and irrigation parameterizations that appear in CLM5.0. Corresponding information for CLM4.5 appeared in the CLM4.5 Technical Note (:ref:`Oleson et al. 2013 `). -CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the Bgc configuration: +CLM5.0 includes the following new updates to the CROP option, where CROP refers to the interactive crop management model and is included as an option with the BGC configuration: - New crop functional types @@ -53,7 +53,7 @@ Introduction Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `), and Clm45Bgc. Additional updates after the release of CLM4.5 were available by request (:ref:`Levis et al. 2016 `), and those are now incorporated into CLM5. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `) and CLM45BGC. Updates after CLM4.5 were available initially by request (:ref:`Levis et al. 2016 `) and were later incorporated into CLM5. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. @@ -70,7 +70,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr .. _Table Crop plant functional types: -.. table:: Crop plant functional types (PFTs) included in Clm50BgcCrop. +.. table:: Crop plant functional types (PFTs) included in CLM's CROP model. === =========================== ================ =========================== IVT Plant function types (PFTs) Management Class Crop Parameters Used @@ -146,7 +146,7 @@ In addition, CLM's default list of plant functional types (PFTs) includes an irr Phenology ^^^^^^^^^ -Clm50Bgc includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). Clm50BgcCrop uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. +CLM's BGC model includes evergreen, seasonally deciduous (responding to changes in day length), and stress deciduous (responding to changes in temperature and/or soil moisture) phenology algorithms (Chapter :numref:`rst_Vegetation Phenology and Turnover`). CLM's CROP model uses the AgroIBIS crop phenology algorithm, consisting of three distinct phases. Phase 1 starts at planting and ends with leaf emergence, phase 2 continues from leaf emergence to the beginning of grain fill, and phase 3 starts from the beginning of grain fill and ends with physiological maturity and harvest. @@ -217,7 +217,7 @@ Harvest is assumed to occur as soon as the crop reaches maturity. When :math:`GD .. _Table Crop phenology parameters: -.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in Clm50BgcCrop. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. list-table:: Crop phenology and morphology parameters for the active crop plant functional types (PFTs) in CLM's CROP model. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. :header-rows: 1 * - \ @@ -569,7 +569,7 @@ Annual food crop yields (g dry matter m\ :sup:`-2`) can be calculated by saving .. _Table Crop allocation parameters: -.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in Clm50BgcCrop. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. +.. table:: Crop allocation parameters for the active crop plant functional types (PFTs) in CLM's CROP model. Numbers in the first row correspond to the list of PFTs in :numref:`Table Crop plant functional types`. =========================================== ============== ============ ================== ====== ====== ========= ============= ================ ================ ================ \ temperate corn spring wheat temperate soybean cotton rice sugarcane tropical corn tropical soybean miscanthus switchgrass @@ -622,7 +622,7 @@ where :math:`z_{top}^{\max }` is the maximum top-of-canopy height of the crop (: Interactive Fertilization ''''''''''''''''''''''''' -CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in Clm50BgcCrop is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field ``manunitro``. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States :ref:`(Cheng et al., 2019)` rather than the LUMIP timeseries. For the current Clm50BgcCrop, manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: +CLM simulates fertilization by adding nitrogen directly to the soil mineral nitrogen pool to meet crop nitrogen demands using both industrial fertilizer and manure application. CLM's separate crop land unit ensures that natural vegetation will not access the fertilizer applied to crops. Fertilizer in CLM's CROP model is prescribed by crop functional types and varies spatially for each year based on the LUMIP land use and land cover change time series (LUH2 for historical and SSPs for future) (:ref:`Lawrence et al. 2016 `). One of two fields is used to prescribe industrial fertilizer based on the type of simulation. For non-transient simulations, annual fertilizer application in g N/m\ :sup:`2`/yr is specified on the land surface data set by the field CONST_FERTNITRO_CFT. In transient simulations, annual fertilizer application is specified on the land use time series file by the field FERTNITRO_CFT, which is also in g N/m\ :sup:`2`/yr. The values for both of these fields come from the LUMIP time series for each year. In addition to the industrial fertilizer, background manure fertilizer is specified on the parameter file by the field ``manunitro``. For perennial bioenergy crops, little fertilizer (56kg/ha/yr) is applied to switchgrass and no fertilizer is applied to Miscanthus. Note these rates are only based on local land management practices at the University of Illinois Energy Farm located in Central Midwestern United States :ref:`(Cheng et al., 2019)` rather than the LUMIP timeseries. In CLM5, manure N is applied at a rate of 0.002 kg N/m\ :sup:`2`/yr. Because previous versions of CLM (e.g., CLM4) had rapid denitrification rates, fertilizer is applied slowly to minimize N loss (primarily through denitrification) and maximize plant uptake. The current implementation of CLM5 inherits this legacy, although denitrification rates are slower in the current version of the model (:ref:`Koven et al. 2013 `). As such, fertilizer application begins during the leaf emergence phase of crop development (phase 2) and continues for 20 days, which helps reduce large losses of nitrogen from leaching and denitrification during the early stage of crop development. The 20-day period is chosen as an optimization to limit fertilizer application to the emergence stage. A fertilizer counter in seconds, *f*, is set as soon as the leaf emergence phase for crops initiates: .. math:: :label: 25.17 @@ -658,7 +658,7 @@ where :math:`baset` is the *base temperature for GDD* (7\ :sup:`th` row) in :num Separate reproductive pool '''''''''''''''''''''''''' -One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In Clm50BgcCrop, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. +One notable difference between natural vegetation and crops is the presence of reproductive carbon and nitrogen pools. Accounting for the reproductive pools helps determine whether crops are performing reasonably through yield calculations. The reproductive pool is maintained similarly to the leaf, stem, and fine root pools, but allocation of carbon and nitrogen does not begin until the grain fill stage of crop development. Equation :eq:`25.5` describes the carbon and nitrogen allocation coefficients to the reproductive pool. In CLM5, as allocation declines in stem, leaf, and root pools (see section :numref:`Grain fill to harvest`) during the grain fill stage of growth, increasing amounts of carbon and nitrogen are available for grain development. .. _Tillage: From 6389d23c1b7f6a692b0581def6467919d259f9f1 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 17:10:11 -0600 Subject: [PATCH 04/12] Revert a character removal in CLM50_Tech_Note_Crop_Irrigation.rst --- .../Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst index ef078b194d..4f5afcc8da 100755 --- a/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst +++ b/doc/source/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.rst @@ -53,7 +53,7 @@ Introduction Groups developing Earth System Models generally account for the human footprint on the landscape in simulations of historical and future climates. Traditionally we have represented this footprint with natural vegetation types and particularly grasses because they resemble many common crops. Most modeling efforts have not incorporated more explicit representations of land management such as crop type, planting, harvesting, tillage, fertilization, and irrigation, because global scale datasets of these factors have lagged behind vegetation mapping. As this begins to change, we increasingly find models that will simulate the biogeophysical and biogeochemical effects not only of natural but also human-managed land cover. -AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `) and CLM45BGC. Updates after CLM4.5 were available initially by request (:ref:`Levis et al. 2016 `) and were later incorporated into CLM5. +AgroIBIS is a state-of-the-art land surface model with options to simulate dynamic vegetation (:ref:`Kucharik et al. 2000 `) and interactive crop management (:ref:`Kucharik and Brye 2003 `). The interactive crop management parameterizations from AgroIBIS (March 2003 version) were coupled as a proof-of-concept to the Community Land Model version 3 [CLM3.0, :ref:`Oleson et al. (2004) ` ] (not published), then coupled to the CLM3.5 (:ref:`Levis et al. 2009 `) and later released to the community with CLM4CN (:ref:`Levis et al. 2012 `) and CLM4.5BGC. Updates after CLM4.5 were available initially by request (:ref:`Levis et al. 2016 `) and were later incorporated into CLM5. With interactive crop management and, therefore, a more accurate representation of agricultural landscapes, we hope to improve the CLM's simulated biogeophysics and biogeochemistry. These advances may improve fully coupled simulations with the Community Earth System Model (CESM), while helping human societies answer questions about changing food, energy, and water resources in response to climate, environmental, land use, and land management change (e.g., :ref:`Kucharik and Brye 2003 `; :ref:`Lobell et al. 2006 `). As implemented here, the crop model uses the same physiology as the natural vegetation but with uses different crop-specific parameter values, phenology, and allocation, as well as fertilizer and irrigation management. From 1e545aea99b6b8a3c5655cf8a6f5bdf164d44eb5 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 17:22:26 -0600 Subject: [PATCH 05/12] More complete updates to getting-help.rst --- doc/source/users_guide/overview/getting-help.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 0d19e4c6ac..8df3f8fd98 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -76,13 +76,13 @@ CIME CLM Community Land Model (CLM). The prognostically active land model component of CESM. -CLMBGC - Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. Hereonafter we will refer to this as ClmBgc, similar to the corresponding compset alias (e.g. Clm60Bgc). The CLM_CONFIG_OPTS option is +ClmBgc (formatted as the corresponding compset alias, e.g. Clm60Bgc) + Community Land Model (|version|) with BGC Biogeochemistry. Uses CN Biogeochemistry with vertically resolved soil Carbon, CENTURY model like pools, and Nitrification/De-Nitrification. The CLM_CONFIG_OPTS option is ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc`` -CLMBGC-Crop - Community Land Model (|version|) with BGC Biogeochemistry and prognotic crop. Hereonafter we will refer to this as ClmBgcCrop, similar to the corresponding compset alias (e.g. Clm60BgcCrop). The CLM_CONFIG_OPTS option for this is +ClmBgcCrop (formatted as the corresponding compset alias, e.g. Clm60BgcCrop) + Community Land Model (|version|) with BGC Biogeochemistry and prognotic crop. The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="phys clm5_0 -bgc bgc -crop`` @@ -91,8 +91,8 @@ CLMCN ``./xmlchange CLM_CONFIG_OPTS="-bgc cn" -append`` -CLMSP - Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0, CLM4.5 or |version|). Hereonafter we will refer to this as ClmSp, similar to the corresponding compset alias (e.g. Clm60Sp). The CLM_CONFIG_OPTS option for this is +ClmSp (formatted as the corresponding compset alias, e.g. Clm60Sp) + Community Land Model (CLM) with Satellite Phenology (SP) (either CLM4.0, CLM4.5 or |version|). The CLM_CONFIG_OPTS option for this is ``./xmlchange CLM_CONFIG_OPTS="-bgc sp" -append`` From da098b1669ac72ebb560437e48e644a11dda06dd Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 18:04:25 -0600 Subject: [PATCH 06/12] More complete updates to introduction.rst --- doc/source/users_guide/overview/introduction.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index f4f04d5195..78e021ae3c 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -61,7 +61,7 @@ In this introduction we first give a simple guide to understand the document con As a followup to the tools chapter, :ref:`adding-new-resolutions-section` tells how to add files to the XML database for build-namelist to use. This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with CLM (CLM4.0, CLM4.5 and |version| physics). -In :ref:`running-special-cases-section`, again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up the Bgc and Sp models, and we tell the user how to use the DATM model to send historical CO2 data to CLM. +In :ref:`running-special-cases-section`, again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up ClmBgc and ClmSp compsets, and we tell the user how to use the DATM model to send historical CO2 data to CLM. :ref:`running-single-points` outlines how to do single-point or regional simulations using |version|. This is useful to either compare |version| simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with CLM for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple sampling of existing inputs to more complex where you create all your own datasets, tying into :ref:`using-clm-tools-section` and also :ref:`adding-new-resolutions-section` to add the files into the build-namelist XML database. @@ -92,15 +92,15 @@ The README (which can be found in ``$CTSMROOT/doc``) is repeated here. - |version| includes BOTH the old CLM4.0, CLM4.5 physics AND the new |version| physics and you can toggle between those three. The "standard" practice for CLM4.0 is to run with CN on, and with Qian atmospheric forcing. While the "standard" practice for CLM4.5 is to run with BGC on, and CRUNCEP atmospheric forcing. And finally the "standard" practice for |version| is to run with BGC and Prognostic Crop on, with the MOSART model for river routing, as well as the CISM ice sheet model, and using GSWP3 atmospheric forcing. "BGC" is the new |version| biogeochemistry and include CENTURY-like pools, vertical resolved carbon, as well as Nitrification and de-Nitrification (see :ref:`acronyms-and-terms`). -- When running with BGC vegetation (either CLM4.5, CLM5.0, or |version| physics), it is critical to begin with initial conditions that are provided with the release or to spin the model up following the BGC spinup procedure before conducting scientific runs (see :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` for information on how to provide initial conditions for your simulation. +- When running with BGC vegetation (either CLM4.5, CLM5.0, or |version| physics), it is critical to begin with initial conditions that are provided with the release or to spin the model up following the ClmBgc spinup procedure before conducting scientific runs (see :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` for information on how to provide initial conditions for your simulation. -- Initial condition files are provided for CLM4.5 and CLM5.0 from the previous release, for fully coupled B compsets with BGC and offline I compset BGC and SP cases for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ClmBgc with the prognostic crop model for 2000 at 2deg resolution, and one with ClmSp for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. +- Initial condition files are provided for CLM4.5 and CLM5.0 from the previous release, for fully coupled (B) compsets with BGC and offline (I) ClmBgc and ClmSp compsets for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ClmBgcCrop for 2000 at 2deg resolution, and one with ClmSp for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. -- Initial condition files are also provided for |version| for several configurations and resolutions. For Clm45Sp and Clm45Bgc with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For |version| Sp and BgcCrop with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at. +- Initial condition files are also provided for |version| for several configurations and resolutions. For Clm45Sp and Clm45Bgc compsets with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For |version| Sp and BgcCrop compsets with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at. - Users can interpolate initial condition files at different resolutions at startup of a CLM4.5 or |version| simulation. And the file created can be stored for later use. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. -- In |version| for both Bgc and BgcCrop the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. +- In |version| for both Bgc and BgcCrop compsets the new fire model requires lightning frequency data, and human population density (both are read inside of CLM). By default we have provided a climatology dataset for lightning frequency and a dataset with coverage from 1850 to 2014 for population density. Both of these datasets are interpolated from the native resolution of the datasets to the resolution you are running the model on. If you are running with an atmosphere model or forcing that is significantly different than present day -- the lightning frequency may NOT appropriately correspond to your atmosphere forcing and fire initiation would be inappropriate. - Aerosol deposition is a required field to both CLM4.0, CLM4.5 and |version| physics, sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or DATM). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. From 63ee9592cfeccb8da0b272834704c32de62b16af Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 18:20:56 -0600 Subject: [PATCH 07/12] Remove CNDV-related sentence in introduction.rst --- doc/source/users_guide/overview/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index 78e021ae3c..eff02f2a81 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -94,7 +94,7 @@ The README (which can be found in ``$CTSMROOT/doc``) is repeated here. - When running with BGC vegetation (either CLM4.5, CLM5.0, or |version| physics), it is critical to begin with initial conditions that are provided with the release or to spin the model up following the ClmBgc spinup procedure before conducting scientific runs (see :ref:`spinning-up-clm-bgc` or :ref:`spinning-up-sp`). Simulations without a proper spinup will effectively be starting from an unvegetated world. See :ref:`setting-initial-conditions` for information on how to provide initial conditions for your simulation. -- Initial condition files are provided for CLM4.5 and CLM5.0 from the previous release, for fully coupled (B) compsets with BGC and offline (I) ClmBgc and ClmSp compsets for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ClmBgcCrop for 2000 at 2deg resolution, and one with ClmSp for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. +- Initial condition files are provided for CLM4.5 and CLM5.0 from the previous release, for fully coupled (B) compsets with BGC and offline (I) ClmBgc and ClmSp compsets for 1850 and 2000 at finite volume grids: 1deg (0.9x1.25), 2deg (1.9x2.5), and T31 resolutions. We also have interpolated initial conditions for BCN for 1850 and 2000 for two finite volume grids: 10x15, 4x5 and two HOMME grids (ne30np4 and ne120np4). There's also an initial condition file for ClmBgcCrop for 2000 at 2deg resolution, and one with ClmSp for 2000 at 2deg resolution. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. - Initial condition files are also provided for |version| for several configurations and resolutions. For Clm45Sp and Clm45Bgc compsets with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. For |version| Sp and BgcCrop compsets with both CRUNCEP and GSWP3 forcing we have initial conditions at 1deg resolution for 1850. Normally, these files are interpolated to any other resolution that you run at. From 22994b903f6d8fbead7f2ff2e1d9df49259f6de1 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 18:32:48 -0600 Subject: [PATCH 08/12] Update to Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst --- ...Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst index cdb730a758..85c62b2a80 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst @@ -52,7 +52,7 @@ The ``subper`` setting tells the script how many years of atmospheric forcing we .. figure:: Clm60Sp_ctsm54030_1deg_CRUJRA2024_arbi_2000_SP_Spinup.png - Sp spinup plot for arbitrary initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. + ClmSp spinup plot for arbitrary initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. You can also start from a default initial file that is provided as part of the selected compset. The following steps illustrate how to setup and run a 51 year Clm60Sp spinup from default initial conditions again using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): :: @@ -79,4 +79,4 @@ The difference from the previous simulation is that we don't set ``CLM_FORCE_COL .. figure:: Clm60Sp_ctsm54030_1deg_CRUJRA2024_fini_2000_SP_Spinup.png - Sp spinup plot for default initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. + ClmSp spinup plot for default initial conditions. Variables examined are FSH (sensible heat flux), EFLX_LH_TOT (latent heat flux), GPP (photosynthesis), TWS (total water storage), H2OSOI (volumetric soil water in layer 8) and TSOI (soil temperature in layer 10). Generated using ``tools/contrib/SpinupStability_SP_v10.ncl``. From 0a93257de9d811be5fc7bff1e1d547598ab54921 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 18:39:30 -0600 Subject: [PATCH 09/12] Define arbitrary initial conditions as finidat = ' ' --- .../Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst | 2 +- .../Spinning-up-the-biogeochemistry-Bgc-spinup.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst index 85c62b2a80..51eae3bb6f 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-Satellite-Phenology-Model-ClmSp-spinup.rst @@ -8,7 +8,7 @@ The spin-up of a land surface model is generally defined as an adjustment process as the model approaches equilibrium in its state variables (:ref:`Yang et al. 1995`). This is usually accomplished by forcing the model with repeated years of identical atmospheric forcing until the model state at year ``n+1`` is the same as that at year ``n`` within some defined threshold in the state variables. -To spin-up the Clm60Sp model you generally need to run Clm60Sp for a few cycles of repeated atmospheric forcing starting from arbitrary initial conditions, the main goal being to ensure that the turbulent fluxes and soil water and temperature have reached equilibrium (minimal trends). You then use the final restart file resulting from that simulation as initial conditions in other simulations. Alternatively, you can also start from an initial file that is typically already provided for you as part of the selected compset. Generally, this will allow for shorter spinup times if your simulation configuration is similar to the one run to generate the default initial file. +To spin-up the Clm60Sp model you generally need to run Clm60Sp for a few cycles of repeated atmospheric forcing starting from arbitrary initial conditions (finidat = ' '), the main goal being to ensure that the turbulent fluxes and soil water and temperature have reached equilibrium (minimal trends). You then use the final restart file resulting from that simulation as initial conditions in other simulations. Alternatively, you can also start from an initial file that is typically already provided for you as part of the selected compset. Generally, this will allow for shorter spinup times if your simulation configuration is similar to the one run to generate the default initial file. The following steps illustrate how to setup and run a 51 year Clm60Sp spinup from arbitrary initial conditions using the ``I2000Clm60SpCrujra`` compset and ``f09_t232`` spatial resolution. From a checkout of the CLM code (choose your own case name): :: diff --git a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst index 58545ed567..ebb4250e36 100644 --- a/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst +++ b/doc/source/users_guide/running-special-cases/Spinning-up-the-biogeochemistry-Bgc-spinup.rst @@ -6,7 +6,7 @@ Spinup of ClmBgcCrop ===================== -To get the ClmBgcCrop model to a steady state, you start it from arbitrary initial conditions using the "accelerated decomposition spinup" (``CLM_ACCELERATED_SPINUP on`` in CLM `env_run.xml`, see example below) mode for 300-400 simulation years. :numref:`Figure BgcCrop AD spinup plot for 1850` shows spinup behavior for an 1850 BgcCrop accelerated decomposition (AD) case using CRUJRA atmospheric forcing. Generally, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. +To get the ClmBgcCrop model to a steady state, you start it from arbitrary initial conditions (finidat = ' ') using the "accelerated decomposition spinup" (``CLM_ACCELERATED_SPINUP on`` in CLM `env_run.xml`, see example below) mode for 300-400 simulation years. :numref:`Figure BgcCrop AD spinup plot for 1850` shows spinup behavior for an 1850 BgcCrop accelerated decomposition (AD) case using CRUJRA atmospheric forcing. Generally, the criterion that less than 3% of the land surface be in total ecosystem carbon disequilibrium takes the longest to satisfy due to slow soil carbon (TOTSOMC) turnover times in the Arctic. .. _Figure BgcCrop AD spinup plot for 1850: From d492f1ea6ee0ab28eb2ab1fc70b6ef2fbdbc4a7e Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Wed, 5 Aug 2026 18:42:58 -0600 Subject: [PATCH 10/12] Small updates to customizing-the-clm-configuration.rst --- .../customizing-the-clm-configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst index 074a750c26..5f90ef7a91 100644 --- a/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst +++ b/doc/source/users_guide/setting-up-and-running-a-case/customizing-the-clm-configuration.rst @@ -284,7 +284,7 @@ The ``$CTSMROOT/cime_config/buildnml`` script already sets the resolution and ma #. ``-verbose`` -``-bgc_spinup`` is an option only available for |version| for any configuration when BGC is turned on (ClmBgc). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See :ref:`spinning-up-clm-bgc` for an example using this option. +``-bgc_spinup`` is an option only available for |version| for any configuration when BGC is turned on (ClmBgc compsets). It can be set to "on" or "off". If "on" the model will go into Accelerated Decomposition mode, while for "off" (the default) it will have standard decomposition rates. If you are starting up from initial condition files the model will check what mode the initial condition file is in and do the appropriate action on the first time-step to change the Carbon pools to the appropriate spinup setting. See :ref:`spinning-up-clm-bgc` for an example using this option. .. todo:: Update the above. @@ -449,7 +449,7 @@ Thus a setting in ``CLM_BLDNML_OPTS`` will override a setting for the same thing Setting Your Initial Conditions File ------------------------------------ -Especially with ClmBgc starting from initial conditions is very important. Even with ClmSp it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file. +Especially with ClmBgc, starting from initial conditions is very important. Even with ClmSp it takes many simulation years to get the model fully spunup. There are a couple different ways to provide an initial condition file. - :ref:`doing-a-hybrid-sim-for-init-conds` - :ref:`doing-a-branch-sim-for-init-conds` From 84f3b4583a47288a9e31f4608605d1607f1e04e5 Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Thu, 6 Aug 2026 11:37:14 -0600 Subject: [PATCH 11/12] Make ClmSp/Bgc/BgcCrop acronyms consistent also in /bld (very few) --- bld/namelist_files/namelist_definition_ctsm.xml | 6 +++--- bld/unit_testers/build-namelist_test.pl | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/bld/namelist_files/namelist_definition_ctsm.xml b/bld/namelist_files/namelist_definition_ctsm.xml index 75a96a6c5f..668b23ea6b 100644 --- a/bld/namelist_files/namelist_definition_ctsm.xml +++ b/bld/namelist_files/namelist_definition_ctsm.xml @@ -1365,13 +1365,13 @@ eg. if nyr_forcing = 20, nyr_SASU = 5, number of analytic solutions is 20/5=4 -Turn on methane model. Standard part of CLM45BGC model. +Turn on methane model. Standard part of Clm45Bgc model. CLM Biogeochemistry mode : Carbon Nitrogen model (CN) -(or CLM45BGC if phys=clm4_5, vsoilc_centbgc='on', and clm4me='on') +(or Clm45Bgc if phys=clm4_5, vsoilc_centbgc='on', and clm4me='on') Command line arguement for biogeochemistry mode for CLM4.5 sp = Satellitte Phenology - bgc = CLM4.5 BGC model with: + bgc = Clm45Bgc model with: CENTURY model pools Nitrification/De-nitrification Methane model diff --git a/bld/unit_testers/build-namelist_test.pl b/bld/unit_testers/build-namelist_test.pl index b77dc9670a..08cc4b28e3 100755 --- a/bld/unit_testers/build-namelist_test.pl +++ b/bld/unit_testers/build-namelist_test.pl @@ -1595,7 +1595,7 @@ sub cat_and_create_namelistinfile { print "Test ALL resolutions that have surface datasets with SP for 1850 and 2000\n"; print "========================================================================\n"; -# Check for ALL resolutions with CLM50SP +# Check for ALL resolutions with Clm50Sp my @resolutions = ( "360x720cru", "10x15", "4x5", "0.9x1.25", "1.9x2.5", "ne3np4", "ne3np4.pg3", "ne16np4.pg3", "ne30np4", "ne30np4.pg2", "ne30np4.pg3", "ne120np4.pg3", "ne0np4CONUS.ne30x8", "ne0np4.ARCTIC.ne30x4", "ne0np4.ARCTICGRIS.ne30x8", "C96", "mpasa480", "mpasa120" ); my @only2000_resolutions = ( "1x1_numaIA", "1x1_brazil", "1x1_mexicocityMEX", "1x1_vancouverCAN", "1x1_urbanc_alpha", "5x5_amazon", "0.125nldas2", "mpasa60", "mpasa15", "mpasa3p75" ); my @regional; From 3b048955058e33e1cfed6be5564ae79ed7441efc Mon Sep 17 00:00:00 2001 From: Samuel Levis Date: Thu, 6 Aug 2026 11:40:25 -0600 Subject: [PATCH 12/12] Make Sp/Bgc/BgcCrop acronym formats consistent also in testlist_clm.xml --- cime_config/testdefs/testlist_clm.xml | 148 +++++++++++++------------- 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/cime_config/testdefs/testlist_clm.xml b/cime_config/testdefs/testlist_clm.xml index fdfad13a5e..565396b240 100644 --- a/cime_config/testdefs/testlist_clm.xml +++ b/cime_config/testdefs/testlist_clm.xml @@ -61,7 +61,7 @@ - + @@ -150,7 +150,7 @@ - + @@ -329,7 +329,7 @@ - + @@ -348,7 +348,7 @@ - + @@ -367,7 +367,7 @@ - + @@ -386,7 +386,7 @@ - + @@ -405,7 +405,7 @@ - + @@ -424,7 +424,7 @@ - + @@ -443,7 +443,7 @@ - + @@ -461,7 +461,7 @@ - + @@ -545,7 +545,7 @@ - + @@ -563,7 +563,7 @@ - + @@ -581,8 +581,8 @@ - - + + @@ -600,8 +600,8 @@ - - + + @@ -620,7 +620,7 @@ - + @@ -964,7 +964,7 @@ - + @@ -983,7 +983,7 @@ - + @@ -1001,7 +1001,7 @@ - + @@ -1010,7 +1010,7 @@ - + @@ -1020,7 +1020,7 @@ - + @@ -1039,7 +1039,7 @@ - + @@ -1058,7 +1058,7 @@ - + @@ -1077,7 +1077,7 @@ - + @@ -1096,7 +1096,7 @@ - + @@ -1115,7 +1115,7 @@ - + @@ -1134,7 +1134,7 @@ - + @@ -1153,7 +1153,7 @@ - + @@ -1172,7 +1172,7 @@ - + @@ -1190,7 +1190,7 @@ - + @@ -1209,7 +1209,7 @@ - + @@ -1218,7 +1218,7 @@ - + @@ -1228,7 +1228,7 @@ - + @@ -1246,7 +1246,7 @@ - + @@ -1427,7 +1427,7 @@ - + @@ -2089,7 +2089,7 @@ - + @@ -2270,7 +2270,7 @@ - + @@ -2366,7 +2366,7 @@ - + @@ -2546,7 +2546,7 @@ - + @@ -2575,7 +2575,7 @@ - + @@ -2585,7 +2585,7 @@ - + @@ -2595,7 +2595,7 @@ - + @@ -2605,7 +2605,7 @@ - + @@ -2615,7 +2615,7 @@ - + @@ -2625,7 +2625,7 @@ - + @@ -2636,7 +2636,7 @@ - + @@ -2647,7 +2647,7 @@ - + @@ -2657,7 +2657,7 @@ - + @@ -2677,7 +2677,7 @@ - + @@ -2688,7 +2688,7 @@ - + @@ -2698,7 +2698,7 @@ - + @@ -2736,7 +2736,7 @@ - + @@ -2746,7 +2746,7 @@ - + @@ -2756,7 +2756,7 @@ - + @@ -2775,7 +2775,7 @@ - + @@ -2784,8 +2784,8 @@ - - + + @@ -2795,8 +2795,8 @@ - - + + @@ -2814,8 +2814,8 @@ - - + + @@ -2834,7 +2834,7 @@ - + @@ -2864,7 +2864,7 @@ - + @@ -3038,7 +3038,7 @@ - + @@ -3388,7 +3388,7 @@ - + @@ -3812,7 +3812,7 @@ - + @@ -4120,7 +4120,7 @@ - + @@ -4149,7 +4149,7 @@ - + @@ -4158,7 +4158,7 @@ - + @@ -4320,7 +4320,7 @@ - + @@ -4340,7 +4340,7 @@ - +