ctsm5.3.035: b4b-dev merge 2025-03-27

.git-blame-ignore-revs

@@ -59,3 +59,4 @@ bd535c710db78420b8e8b9d71d88d8339e899c59
 cf433215b58ba8776ec5edfb0b0d80c0836ed3a0
 16d57ff37859b34dab005693e3085d64e2bcd95a
 e8fc526e0d7818d45f171488c78392c4ff63902a
+cdf40d265cc82775607a1bf25f5f527bacc97405

cime_config/testdefs/ExpectedTestFails.xml

@@ -178,13 +178,6 @@
     </phase>
   </test>
 
-  <test name="FUNITCTSM_P1x1.f10_f10_mg37.I2000Clm50Sp.izumi_intel">
-    <phase name="RUN">
-      <status>FAIL</status>
-      <issue>#2453</issue>
-    </phase>
-  </test>
-
   <test name="ERS_Ld60.f45_f45_mg37.I2000Clm50FatesCruRsGs.derecho_intel.clm-FatesColdST3">
     <phase name="RUN">
       <status>FAIL</status>
@@ -271,6 +264,10 @@
       <status>FAIL</status>
       <issue>#2310</issue>
     </phase>
+    <phase name="RUN">
+      <status>FAIL</status>
+      <issue>#3038</issue>
+    </phase>
   </test>
 
   <test name="ERS_D_Ld30.f45_f45_mg37.I2000Clm50FatesCruRsGs.derecho_intel.clm-FatesColdLandUse">

doc/ChangeLog

@@ -1,4 +1,69 @@
 ===============================================================
+Tag name: ctsm5.3.035
+Originator(s): samrabin (Sam Rabin, UCAR/TSS)
+Date: Fri Mar 28 14:31:29 MDT 2025
+One-line Summary: Merge b4b-dev
+
+Purpose and description of changes
+----------------------------------
+
+Merging b4b-dev and ctsm5.3.034.
+
+
+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):
+- [Issue #1565: Documentation need for generic single point with nuopc](https://github.com/ESCOMP/CTSM/issues/1565)
+- [Issue #2453: FUNIT test not working on izumi](https://github.com/ESCOMP/CTSM/issues/2453)
+- [Issue #2847: Pitfall using mksurdata_esmf options --model-mesh-nx NX --model-mesh-ny NY when using unstructured meshes](https://github.com/ESCOMP/CTSM/issues/2847)
+- [Issue #2892: Convert "How do I create a single-point run with the NUOPC (default) coupler?" to real docs](https://github.com/ESCOMP/CTSM/issues/2892)
+- [Issue #2999: Throw errors in subset_data for known buggy setups](https://github.com/ESCOMP/CTSM/issues/2999)
+
+
+Testing summary:
+----------------
+
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
+
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
+
+    derecho - PASS
+
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
+
+    derecho ----- OK
+    izumi ------- OK
+
+
+Other details
+-------------
+
+Pull Requests that document the changes:
+- [Pull Request #3002: Update single point docs (and improve subset_data etc. erroring) by samsrabin](https://github.com/ESCOMP/CTSM/pull/3002)
+- [Pull Request #3023: Get pFUnit-based unit tests working on my Mac by billsacks](https://github.com/ESCOMP/CTSM/pull/3023)
+- [Pull Request #3030: Avoid mksurfdata_esmf pitfall with --model-mesh-nx, ny by slevis-lmwg](https://github.com/ESCOMP/CTSM/pull/3030)
+- [Pull Request #3037: ctsm5.3.035: b4b-dev merge 2025-03-27 by samsrabin](https://github.com/ESCOMP/CTSM/pull/3037)
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.034
 Originator(s): rgknox (Ryan Knox)
 Date: Thu Mar 27 16:03:56 MDT 2025

doc/ChangeSum

@@ -1,5 +1,6 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.035 samrabin 03/28/2025 Merge b4b-dev
        ctsm5.3.034   rgknox 03/27/2025 Fixes to enable passing FATES two-stream ERS and ERI restart tests.
        ctsm5.3.033 multiple 03/19/2025 Add new mimics_fi param = frac of litter inputs bypassing litter pools
        ctsm5.3.032   slevis 03/17/2025 Add option to use CRUJRA2024 with clm6 and clm5

doc/source/users_guide/overview/introduction.rst

@@ -60,7 +60,9 @@ As a followup to the tools chapter, :ref:`adding-new-resolutions-section` tells
 
 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.
 
-: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 PTS_MODE 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.
+: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.
 

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

@@ -15,6 +15,7 @@ Running Single Point Regional Cases
    :maxdepth: 2
 
    single-point-and-regional-grid-configurations.rst
-   running-pts_mode-configurations.rst
+   running-single-point-subset-data.rst
    running-single-point-configurations.rst
+   running-pts_mode-configurations.rst
 

doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst

@@ -6,6 +6,9 @@
 Running a single point using global data - PTS_MODE
 ****************************************************
 
+.. warning::
+   ``PTS_MODE`` has been mostly deprecated in favor of ``subset_data`` (Sect. :numref:`single_point_subset_data`). You should only consider using it if you are using the Single Column Atmospheric Model (SCAM).
+
 ``PTS_MODE`` 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.
 
 To setup a ``PTS_MODE`` simulation you use the ``-pts_lat`` and ``-pts_lon`` arguments to ``cime/scripts/create_newcase`` to give the latitude and longitude of the point you want to simulate for (the code will pick the point on the global grid nearest to the point you give. Here's an example to setup a simulation for the nearest point at 2-degree resolution to Boulder Colorado.

doc/source/users_guide/running-single-points/running-single-point-configurations.rst

@@ -6,7 +6,7 @@
  Running Single Point Configurations
 ******************************************
 
-In addition to ``PTS_MODE`` (Sect. :numref:`pts_mode`), CLM supports running using single-point or regional datasets that are customized to a particular region. CLM supports a a small number of out-of-the-box single-point and regional datasets. However, users can create their own dataset.
+In addition to running with the outputs of ``subset_data`` (Sect. :numref:`single_point_subset_data`), CLM supports running using single-point or regional datasets that are customized to a particular region. CLM supports a a small number of out-of-the-box single-point and regional datasets. However, users can create their own dataset.
 
 To get the list of supported dataset resolutions do this:
 ::
@@ -32,7 +32,7 @@ The resolution names that have an underscore in them ("_") are all single-point
 .. note:: When running a single point, the number of processors is automatically set to one, which is the only value allowed.
 
 .. warning::
-   Just like ``PTS_MODE`` (Sect. :numref:`pts_mode`), by default these setups sometimes run with ``MPILIB=mpi-serial`` (in the ``env_build.xml`` file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build.
+   Just like running with the outputs from ``subset_data`` (Sect. :numref:`single_point_subset_data`), by default these setups sometimes run with ``MPILIB=mpi-serial`` (in the ``env_build.xml`` file) turned on, which allows you to run the model interactively. On some machines this mode is NOT supported and you may need to change it to FALSE before you are able to build.
 
 .. _single-point-global-climate:
 

doc/source/users_guide/running-single-points/running-single-point-subset-data.rst

@@ -0,0 +1,60 @@
+.. include:: ../substitutions.rst
+
+.. _single_point_subset_data:
+
+****************************************
+Running a single point using global 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.
+
+Subset the data
+------------------
+
+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``.
+
+Note that you will need to have a python environment set up that includes the packages ``scipy``, ``xarray``, and ``numpy``. If you have conda or miniconda installed, you can create a conda environment for this and other CTSM python tools using the script ``py_env_create`` at the top level of your CTSM checkout.
+
+To subset surface data and climate forcings (DATM) for a single point, use the command:
+
+.. code:: shell
+
+   tools/site_and_regional/subset_data point \
+      --lat $my_lat --lon $my_lon --site $my_site_name \
+      --create-surface --create-datm \
+      --datm-syr $my_start_year --datm-eyr $my_end_year \
+      --create-user-mods --outdir $my_output_dir
+
+-  ``$my_lat``: latitude of point, *must be between -90 and 90 degrees*. E.g., Boulder, CO, USA: 40.
+-  ``$my_lon``: longitude of point, *must be between 0 and 360 degrees*. E.g., Boulder, CO, USA: 55.
+-  ``$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_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.
+
+**Note that 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 the ``--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.
+
+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.
+
+.. code:: shell
+
+   cime/scripts/create_newcase --case $my_case_name --res CLM_USRDAT \
+      --compset $compset --run-unsupported \
+      --user-mods-dirs $my_output_dir/user_mods
+
+-  ``$my_case_name``: the path of the case directory you want to create
+-  ``$compset``: the compset you would like to use (for example, ``I2000Clm60Bgc``)
+-  Note the use of ``$my_output_dir/user_mods`` which is the ``user_mods/`` directory that the subset data script set up within your specified ``$my_output_dir``.
+
+Note that ``./case.setup`` on Derecho will automatically set queue to ``develop`` and walltime to one hour. You might need a longer walltime, but the maximum walltime for ``develop`` is one hour. To change it to two hours on Derecho:
+
+.. code:: shell
+
+   ./xmlchange --subgroup case.run JOB_QUEUE=main,JOB_WALLCLOCK_TIME=2:00:00

doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst

@@ -10,7 +10,7 @@ CLM allows you to set up and run cases with a single-point or a local region as
 
 There are two different ways to do this for normal-supported site
 
-``PTS_MODE``
+``subset_data``
   runs for a single point using global datasets.
 
 ``CLM_USRDAT_NAME``
@@ -24,9 +24,9 @@ There are two different ways to do this for normal-supported site
 
 Running for a *normal supported site* is a great solution, if one of the supported single-point/regional datasets, is your region of interest (see :ref:`running-single-point-datasets`). All the datasets are created for you, and you can easily select one and run, out of the box with it using a supported resolution from the top level of the CESM scripts. The problem is that there is a very limited set of supported datasets. You can also use this method for your own datasets, but you have to create the datasets, and add them to the XML database in scripts, CLM and to the DATM. This is worthwhile if you want to repeat many multiple cases for a given point or region.
 
-In general :ref:`pts_mode` is the quick and dirty method that gets you started without having to create datasets -- but has limitations. It's good for an initial attempt at seeing results for a point of interest, but since you can NOT restart with it, it's usage is limited. It is the quickest method as you can create a case for it directly from ``cime/scripts/create_newcase``. Although you can't restart, running a single point is very fast, and you can run for long simulation times even without restarts.
+In general :ref:`single_point_subset_data` is the quick and dirty method that gets you started, but it has limitations. It's good for an initial attempt at seeing results for a point of interest, but since you can NOT restart with it, its usage is limited. It is the quickest method as you can create a case for it directly from ``cime/scripts/create_newcase``. Although you can't restart, running a single point is very fast, and you can run for long simulation times even without restarts.
 
-Next, ``CLM_USRDAT_NAME`` is the best way to setup cases quickly where you have to create your own datasets (see :ref:`running-single-point-datasets`). With this method you don't have to change DATM or add files to the XML database -- but you have to follow a strict naming convention for files. However, once the files are named and in the proper location, you can easily setup new cases that use these datasets. This is good for treating all the required datasets as a "group" and for a particular model version. For advanced CLM developers who need to track dataset changes with different model versions you would be best off adding these datasets as supported datasets with the "normal supported datasets" method.
+Next, ``CLM_USRDAT_NAME`` using ``subset_data`` is the best way to setup cases quickly where you have a simple tool to create your own datasets (see :ref:`single_point_subset_data`). With this method you don't have to change DATM or add files to the XML database. ``subset_data`` will create a usermod directory where you can store your files and the files needed to directly run a case.
 
 Finally, if you also have meteorology data that you want to force your CLM simulations with you'll need to setup cases as described in :ref:`creating-your-own-singlepoint-dataset`. You'll need to create CLM datasets either according to ``CLM_USRDAT_NAME``. You may also need to modify DATM to use your forcing data. And you'll need to change your forcing data to be in a format that DATM can use.
 

python/ctsm/config_utils.py

@@ -25,17 +25,15 @@ def lon_range_0_to_360(lon_in):
     Restrict longitude to 0 to 360 when given as -180 to 180.
     """
     if -180 <= lon_in < 0:
-        lon_out = lon_in % 360
-        logger.info(
-            "Resetting longitude from %s to %s to keep in the range " " 0 to 360",
-            str(lon_in),
-            str(lon_out),
+        raise NotImplementedError(
+            "A negative longitude suggests you input longitudes in the range [-180, 0)---"
+            "i.e., centered around the Prime Meridian. This code requires longitudes in the "
+            "range [0, 360)---i.e., starting at the International Date Line."
         )
-    elif 0 <= lon_in <= 360 or lon_in is None:
-        lon_out = lon_in
-    else:
+    if not (0 <= lon_in <= 360 or lon_in is None):
         errmsg = "lon_in needs to be in the range 0 to 360"
         abort(errmsg)
+    lon_out = lon_in
 
     return lon_out
 

python/ctsm/site_and_regional/single_point_case.py

@@ -608,7 +608,7 @@ def extract_datm_at(self, file_in, file_out):
         f_in.close()
         f_out.close()
 
-    def write_shell_commands(self, file):
+    def write_shell_commands(self, file, datm_syr, datm_eyr):
         """
         writes out xml commands commands to a file (i.e. shell_commands) for single-point runs
         """
@@ -619,6 +619,10 @@ def write_shell_commands(self, file):
             self.write_to_file("./xmlchange PTS_LON={}".format(str(self.plon)), nl_file)
             self.write_to_file("./xmlchange PTS_LAT={}".format(str(self.plat)), nl_file)
             self.write_to_file("./xmlchange MPILIB=mpi-serial", nl_file)
+            if self.create_datm:
+                self.write_to_file(f"./xmlchange DATM_YR_ALIGN={datm_syr}", nl_file)
+                self.write_to_file(f"./xmlchange DATM_YR_START={datm_syr}", nl_file)
+                self.write_to_file(f"./xmlchange DATM_YR_END={datm_eyr}", nl_file)
 
     def write_datm_streams_lines(self, streamname, datmfiles, file):
         """