Merge pull request #3242 from ekluzek/merge-b4bdev-20250609

Merge b4bdev 20250609

Author: ekluzek

doc/ChangeLog

@@ -1,4 +1,97 @@
 ===============================================================
+Tag name: ctsm5.3.056
+Originator(s): erik (Erik Kluzek,UCAR/TSS,303-497-1326)
+Date: Thu 12 Jun 2025 01:43:46 PM MDT
+One-line Summary: Merge b4b-dev to master
+
+Purpose and description of changes
+----------------------------------
+
+Several updates to documentation, from the documentation hackathon.
+Also remove /glade from paths for mksurfdata_esmf paths
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+  Resolves Improve headings in single-point docs #3008
+  Resolves Docs needed: Supported towers #3175
+  Resolves Docs needed: NEON #3167
+  Documentation part of run_neon base case must be of same run type as a requested clone #1926
+  Resolves run_tower documentation needed #2997
+  Resolves Various subset_data and related docs needed #3000
+  Resolves Docs docs: Inline code rendered as italics #3164
+  Resolves Fix some missing equation references in Snow Hydrology chapter of Tech Note #3202
+  Resolves Fix Equation number label 2.5.119 in technical note #3196
+  Resolves Remove hardcoded /glade/campaign/cesm/cesmdata/inputdata/ paths to support --rawdata-dir flexibility #3031
+
+Notes of particular relevance for users
+---------------------------------------
+
+Changes to documentation: Yes!
+
+Notes of particular relevance for developers: None
+---------------------------------------------
+
+Testing summary: regular
+---------------- 
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
+
+    derecho - OK
+
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
+
+    derecho - I ran it and there were fails but previous versions had this as well
+              One problem was with the NEON server, so outside our control
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+If the tag used for baseline comparisons was NOT the previous tag, note that here:
+
+Answer changes
+--------------
+
+Changes answers relative to baseline: No bit-for-bit
+
+Other details
+-------------
+
+Pull Requests that document the changes (include PR ids):
+(https://github.com/ESCOMP/ctsm/pull)
+
+  Merge b4b-dev to master #3242
+  Updates to run_tower/single point documentation #3194
+  fixed italics to be in-line code #3198
+  Fix some equation references in the Snow Hydrology chapter of the Tech Note #3203
+  Fix typo in Chapter 5 of technical note #3195
+  Remove hardcoded paths in gen_mksurfdata_namelist.xml #3162
+  Merge ctsm5.3.050 to b4b-dev #3200
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.055
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Thu Jun  5 13:59:20 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.056     erik 06/12/2025 Merge b4b-dev to master
        ctsm5.3.055 samrabin 06/05/2025 Remove FTorch
        ctsm5.3.054 samrabin 06/02/2025 CDEPS: Allow anomaly forcings with any DATM
        ctsm5.3.053 samrabin 05/30/2025 Fix and improve anomaly forcings for ISSP cases

doc/source/tech_note/Fluxes/CLM50_Tech_Note_Fluxes.rst

@@ -1215,7 +1215,7 @@ The numerical solution for vegetation temperature and the fluxes of momentum, se
 
 #. Leaf boundary layer resistance :math:`r_{b}` (:eq:`5.122` )
 
-#. Aerodynamic resistances :math:`r_{ah} ^{{'} }` and :math:`r_{aw} ^{{'} }`(:eq:`5.116` )
+#. Aerodynamic resistances :math:`r_{ah} ^{{'} }` and :math:`r_{aw} ^{{'} }` (:eq:`5.116` )
 
 #. Sunlit and shaded stomatal resistances :math:`r_{s}^{sun}` and :math:`r_{s}^{sha}` (Chapter :numref:`rst_Stomatal Resistance and Photosynthesis`)
 

doc/source/tech_note/Snow_Hydrology/CLM50_Tech_Note_Snow_Hydrology.rst

@@ -585,7 +585,7 @@ The maximum snow layer thickness, :math:`\Delta z_{\max }`, depends on the numbe
 Subdivision
 '''''''''''''''''''
 
-The snow layers are subdivided when the layer thickness exceeds the prescribed maximum thickness :math:`\Delta z_{\max }` with lower and upper bounds that depend on the number of snow layers (:numref:`Table snow layer thickness`). For example, if there is only one layer, then the maximum thickness of that layer is 0.03 m, however, if there is more than one layer, then the maximum thickness of the top layer is 0.02 m. Layers are checked sequentially from top to bottom for this limit. If there is only one snow layer and its thickness is greater than 0.03 m (:numref:`Table snow layer thickness`), the layer is subdivided into two layers of equal thickness, liquid water and ice contents, and temperature. If there is an existing layer below the layer to be subdivided, the thickness :math:`\Delta z_{i}`, liquid water and ice contents, :math:`w_{liq,\; i}` and :math:`w_{ice,\; i}`, and temperature :math:`T_{i}` of the excess snow are combined with the underlying layer according to equations -. If there is no underlying layer after adjusting the layer for the excess snow, the layer is subdivided into two layers of equal thickness, liquid water and ice contents. The vertical snow temperature profile is maintained by calculating the slope between the layer above the splitting layer (:math:`T_{1}` ) and the splitting layer (:math:`T_{2}` ) and constraining the new temperatures (:math:`T_{2}^{n+1}`, :math:`T_{3}^{n+1}` ) to lie along this slope. The temperature of the lower layer is first evaluated from
+The snow layers are subdivided when the layer thickness exceeds the prescribed maximum thickness :math:`\Delta z_{\max }` with lower and upper bounds that depend on the number of snow layers (:numref:`Table snow layer thickness`). For example, if there is only one layer, then the maximum thickness of that layer is 0.03 m, however, if there is more than one layer, then the maximum thickness of the top layer is 0.02 m. Layers are checked sequentially from top to bottom for this limit. If there is only one snow layer and its thickness is greater than 0.03 m (:numref:`Table snow layer thickness`), the layer is subdivided into two layers of equal thickness, liquid water and ice contents, and temperature. If there is an existing layer below the layer to be subdivided, the thickness :math:`\Delta z_{i}`, liquid water and ice contents, :math:`w_{liq,\; i}` and :math:`w_{ice,\; i}`, and temperature :math:`T_{i}` of the excess snow are combined with the underlying layer according to equations :eq:`8.55` - :eq:`8.58`. If there is no underlying layer after adjusting the layer for the excess snow, the layer is subdivided into two layers of equal thickness, liquid water and ice contents. The vertical snow temperature profile is maintained by calculating the slope between the layer above the splitting layer (:math:`T_{1}` ) and the splitting layer (:math:`T_{2}` ) and constraining the new temperatures (:math:`T_{2}^{n+1}`, :math:`T_{3}^{n+1}` ) to lie along this slope. The temperature of the lower layer is first evaluated from
 
 .. math::
    :label: 8.62
@@ -602,5 +602,5 @@ then adjusted as,
    T_{2}^{n+1} = T_{2}^{n} +\left(\frac{T_{1}^{n} -T_{2}^{n} }{{\left(\Delta z_{1} +\Delta z_{2}^{n} \right)\mathord{\left/ {\vphantom {\left(\Delta z_{1} +\Delta z_{2}^{n} \right) 2}} \right.} 2} } \right)\left(\frac{\Delta z_{2}^{n+1} }{2} \right) & \qquad T'_{3} <T_{f}
    \end{array}
 
-where here the subscripts 1, 2, and 3 denote three layers numbered from top to bottom. After layer subdivision, the node depths and layer interfaces are recalculated from equations and.
+where here the subscripts 1, 2, and 3 denote three layers numbered from top to bottom. After layer subdivision, the node depths and layer interfaces are recalculated from equations :eq:`8.60` and :eq:`8.61`.
 

doc/source/users_guide/overview/introduction.rst

@@ -62,8 +62,6 @@ In :ref:`running-special-cases-section`, again for the expert user, we give deta
 
 :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.
 
-There is also :ref:`pts_mode`, which is useful for running single points as part of the Single Column Atmospheric Model (SCAM).
-
 :ref:`troubleshooting-index` gives some guidance on trouble-shooting problems when using |version|. It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems.
 
 :ref:`testing_section` goes over the automated testing scripts for validating that the CLM is working correctly. The test scripts run many different configurations and options with CLM4.0 physics as well and |version| physics making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. In general this is an activity important only for a developer of |version|, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly.

doc/source/users_guide/running-single-points/running-single-point-subset-data.rst renamed to doc/source/users_guide/running-single-points/generic-single-point-regional.rst

@@ -1,15 +1,18 @@
 .. include:: ../substitutions.rst
 
-.. _single_point_subset_data:
+.. _generic_single_point_runs:
 
 ****************************************
-Running a single point using global data
+Generic single-point runs
 ****************************************
 
-``subset_data`` enables you to run the model using global datasets, but just picking a single point from those datasets and operating on it. It can be a very quick way to do fast simulations and get a quick turnaround.
+While there are capabilities to run single-point cases at specific tower sites with forcing data from those observations (see :ref:`supported-tower-sites`), users can also run CTSM at a single lat/lon point of their choosing using the instructions below.
 
-Subset the data
-------------------
+============
+subset_data:
+============
+
+``subset_data`` enables you to run the model using global datasets, but just picking a single point from those datasets and operating on it. It can be a very quick way to do fast simulations and get a quick turnaround. This can also be done for regional simulations in the next section but first we will describe how to use subset_data for a single point. 
 
 For single-point cases, you need to subset a surface dataset and (optionally) DATM data. The Python script to subset this data can be found in the CTSM repository at ``tools/site_and_regional/subset_data``.
 
@@ -30,18 +33,23 @@ To subset surface data and climate forcings (DATM) for a single point, use the c
 -  ``$my_lon_type``: 180 if your longitude is in the [-180, 180] format (i.e., centered at the Prime/0th Meridian); 360 if it's in the [0, 360] format (i.e., centered at the 180th Meridian). Note that ``--lon-type $my_lon_type`` is not necessary if your longitude is unambiguous---i.e., it's only needed if your longitude is in the range [0, 180].
 -  ``$my_site_name``: name of site, *used for file naming*
 -  ``$my_start_year``: start year for DATM data to subset, *default between 1901 and 2014*
--  ``$my_end_year``: end year for DATM data to subset, *default between 1901 and 2014; the default CRUJRA2024 DATM data ends in 2023, while the old default GSWP3 ends in 2015; see note below about switching the default DATM data*
+-  ``$my_end_year``: end year for DATM data to subset, *default between 1901 and 2014; the default CRUJRA2024 DATM data ends in 2023, while the old default GSWP3 ends in 2014; see note below about switching the default DATM data*
 -  ``$my_output_dir``: output directory to place the subset data and user_mods directory. This should be something specific to *just* your data for ``$my_site_name``.
 
-You can also have the script subset land-use data. See the help (``tools/site_and_regional/subset_data --help``) for all argument options.
+You can also have the script subset land-use data. See the help (``tools/site_and_regional/subset_data --help``) for all argument options. For example, depending on your application, it may be helpful to specify a dominant PFT using ``--dompft`` and ``--pctpft`` flags. This allows you to control the PFTs that are present on your surface dataset
 
 .. note::
-   This script defaults to subsetting specific surface, domain, and land-use files and the CRUJRA2024 DATM data, and can currently only be run as-is on Derecho. If you're not on Derecho, use ``--inputdata-dir`` to specify where the top level of your CESM input data is. Also, to subset GSWP3 instead of CRUJRA2024 DATM data, you currently need to hardwire ``datm_type = "datm_gswp3"`` (instead of the default ``"datm_crujra"``) in ``python/ctsm/subset_data.py``.
+   This script defaults to subsetting specific surface data, land-use timeseries, and the CRUJRA2024 DATM data. It can currently only be run as-is on Derecho. If you're not on Derecho, use ``--inputdata-dir`` to specify where the top level of your CESM input data is. 
+   
+   Also, to subset GSWP3 instead of CRUJRA2024 DATM data, you currently need to hardwire ``datm_type = "datm_gswp3"`` (instead of the default ``"datm_crujra"``) in ``python/ctsm/subset_data.py``.
+
+
 
-The ``--create-user-mods`` command tells the script to set up a user mods directory in your specified ``$my_output_dir`` and to specify the required ``PTS_LAT`` and ``PTS_LON`` settings. You can then use this user mods directory to set up your CTSM case, as described below.
+The ``--create-user-mods`` command tells the script to set up a user mods directory in your specified ``$my_output_dir`` and to specify the required ``PTS_LAT`` and ``PTS_LON`` settings. You can then use this user mods directory to set up your CTSM case, as described below. ``subset_data`` will default to subsetting surface data and land-use timeseries from the default, nominal one-degree resolution (f09) datasets.
 
+================
 Create the case
-------------------
+================
 
 You can use the user mods directory set up in the previous subset data step to tell CIME/CTSM where your subset files are located.
 

doc/source/users_guide/running-single-points/index.rst

@@ -14,8 +14,8 @@ Running Single Point and Regional Cases
 .. toctree::
    :maxdepth: 2
 
-   single-point-and-regional-grid-configurations.rst
-   running-single-point-subset-data.rst
-   running-single-point-configurations.rst
-   running-pts_mode-configurations.rst
+   intro-to-single-pt-regional.rst
+   supported-tower-sites.rst
+   generic-single-point-regional.rst
+   predefined-single-point-regional-resolutions.rst