Revision of User's Guide section 1.6.2.3 - PLUMBER2 Tower Single Point Simulations

doc/source/users_guide/running-single-points/supported-tower-sites.rst

@@ -8,7 +8,7 @@ Supported tower sites for single-point runs
 
 CTSM has functionality within the ``run_tower`` tool for running single-point cases at particular supported tower sites using forcing data from those sites.
 
-This tool was developed as a collaboration between NCAR's modeling capabilities and NEON's measurement network that could drive scientific discovery at the confluence of geosciences and biological sciences. The tool was then expanded to include PLUMBER sites to support a wider variety of ecological research projects.
+This tool was developed as a collaboration between NCAR's modeling capabilities and NEON's measurement network that could drive scientific discovery at the confluence of geosciences and biological sciences. The tool was then expanded to include PLUMBER2 sites to support a wider variety of ecological research projects.
 
 Broadly, this tool can be used to probe questions such as:
 
@@ -21,7 +21,7 @@ Broadly, this tool can be used to probe questions such as:
 General Information on Running Supported Tower Sites
 ====================================================
 
-The ``run_tower`` capability allows users to run Community Land Model (CLM) simulations at NEON and PLUMBER tower sites in a streamlined manner by setting up the appropriate model configurations, datasets, and initial conditions. This script can run for one or more (NEON or PLUMBER) tower sites. It will do the following:
+The ``run_tower`` capability allows users to run Community Land Model (CLM) simulations at NEON and PLUMBER2 tower sites in a streamlined manner by setting up the appropriate model configurations, datasets, and initial conditions. This script can run for one or more (NEON or PLUMBER2) tower sites. It will do the following:
 
     1) Create a generic base case for cloning.
     2) Make the case for the specific neon or plumber site(s).
@@ -65,88 +65,77 @@ The tower simulations generate two types of files:
 2) ``h1a`` Variables that are recorded every 30 minutes. Values are aggregated into one file for each day of the simulation. Each file includes 48 data points for selected variables.
 
 =========================================
-PLUMBER Tower Single Point Simulations
+PLUMBER2 Tower Single Point Simulations
 =========================================
 
-.. note:: A few important notes regarding the PLUMBER tower site simulations are that the default run type is ``ad``; additionally, PLUMBER cases all start in different years.
+.. note:: A few important notes regarding the PLUMBER2 tower site simulations are that the default run type is ``ad``; additionally, PLUMBER2 cases all start in different years; and the atmospheric forcing data is in local time, consequently, the model is started at GMT time corresponding to local midnight.
 
-Currently, the ``run_tower`` tool supports running CTSM at PLUMBER 2 sites using forcing data from the PLUMBER2 projects. Detailed site information is provided in `Ukkola et al. 2022 <https://doi.org/10.5194/essd-14-449-2022>`_ , and the description of the experiment and its results is provided in `Abramowitz et al. 2024 <https://doi.org/10.5194/bg-21-5517-2024>`_.
+Currently, the ``run_tower`` tool supports running CTSM at PLUMBER2 sites using forcing data from the PLUMBER2 project. Detailed site information is provided in `Ukkola et al. 2022 <https://doi.org/10.5194/essd-14-449-2022>`_ , and the description of the experiment and results are provided in `Abramowitz et al. 2024 <https://doi.org/10.5194/bg-21-5517-2024>`_.
 Information on the specific sites can be found `here <https://researchdata.edu.au/plumber2-forcing-evaluation-surface-models/1656048>`_.
 
-Currently supported PLUMBER Sites can be found by running ``run_tower --help``. Keep in mind that the experiment was designed to run 170 sites; however, Abramowitz et al., identified different issues with the sites (e.g., sites with precipitation reported in one unit while the metadata informed of a different unit), and most of the article only uses 156 sites.
+Currently supported PLUMBER2 sites can be found by running ``run_tower --help``. Keep in mind that the experiment was designed to run 170 sites, however, `Abramowitz et al. 2024 <https://doi.org/10.5194/bg-21-5517-2024>`_ identified issues with some of the sites (e.g., sites with precipitation reported in one unit while the metadata reported a different unit), and most of that article only uses 156 sites.
 
-To run CTSM at a PLUMBER site, change directories to where the run_tower tool is located, and then run the ``run_tower`` command. You can also add any additional arguments as described by the ``help`` options. These steps will look something like this:
+To run CTSM at a PLUMBER2 site, change directories to where the ``run_tower`` tool is located, and then run the ``run_tower`` command. You can also add any additional arguments as described by the ``--help`` option. In the simplest form, these steps will look like this:
 ::
 
-    > cd CTSM/tools/site_and_regional
-    > run_tower --plumber-sites AR-SLu
+    conda activate ctsm_pylib
+    cd CTSM/tools/site_and_regional
+    run_tower --plumber-sites AR-SLu
 
+The history output for a PLUMBER2 case will be set up and archived similarly to the output for a NEON case, as described above.
 
-The output for a PLUMBER case will be set up similarly to the output for a NEON case, as described above.
+--------------------
+General Notes
+--------------------
 
-## Notes 
+A few points regarding the PLUMBER2 simulations using the ``run_tower`` tool:
 
-A few points regarding the PLUMBER 2 simulations using the ``run_tower`` tool:
+#. The PLUMBER2 simulations make extensive use of usermods (located at ``cime_config/usermods_dirs/clm/PLUMBER2``) to configure the simulation for each site and type of simulation. This is accomplished by shell commands (``shell_commands``) and user_nl_* files (e.g., ``user_nl_clm`` and ``user_nl_datm_streams``).  The usermods have already been generated by default using the ``tools/site_and_regional/plumber2_usermods`` script which reads a csv file (``tools/site_and_regional/PLUMBER2_sites.csv``) and generates the usermods.
 
-1) By default, the tools call for surfdata files in a default location. These might not be available for all sites or all machines. Users can create their own surfdata files, using tools/site_and_regional/plumber2_usermods. 
-2) It is suggested to use the flags related to setup-only to examine how the site files are being configured before running the simulations.
+#. The surface datasets have already been generated for all sites and are available in the local inputdata directory. If desired, users can create their own surface datasets by first modifying the csv file (``tools/site_and_regional/PLUMBER2_sites.csv``) and then using the ``python/ctsm/site_and_regional/plumber2_surf_wrapper.py`` tool which makes use of ``subset_data`` to generate the surface dataset.
 
-:: 
+#. When first becoming familiar with the PLUMBER2 simulations, we suggest using the ``--setup-only`` flag to examine how the site files are being configured before running the simulations. Keep in mind that if you use this option you will then need to build the base case manually (using ``./case.build``) because the cloned case uses the build from the base case, and submit the cloned case (``ad``, ``postad``, or ``transient``) manually (using ``./case.submit``).
+   ::
 
-    > ./run_tower --plumber-sites ${site} --setup-only 
+       ./run_tower --plumber-sites AR-SLu --setup-only
 
-3) It is suggested to change `baseflow_scalar` to 0" in the user's paramfile to avoid issues with the baseflow at the wetland sites.
-4) Currently, the tool is designed only for cases with active biochemistry. For SP simulations, it is recommended to review the usermods in detail and adjust them as needed. Key items to be considered include the variables to save. 
-5) Combining these notes, an example of running a PLUMBER site would look like this:
+#. By default, ``baseflow_scalar=0`` is modified in the parameter file for the wetland sites to prevent them from drying out.
 
-:: 
+#. Currently, the tool is designed only for cases with active biogeochemistry (BGC). Implementing capability for SP simulations is in progress.
 
-    > ./run_tower --plumber-sites ${site} --output-root {folder-to-save-results} --overwrite --run-type {ad | postad | transient} --setup-only
+--------------------
+Spin-up notes
+--------------------
 
+#. By default, all simulations (e.g., ad, postad, transient) are setup to run for 1 hour of wall clock time. For the spin-up simulations, it may be necessary to extend the time to match the desired length of the simulations. For example, `Lombardozzi et al. 2023 <https://doi.org/10.5194/gmd-16-5979-2023>`_ used 300 years for ad and 100 years for postad. Users should keep in mind that colder areas might need longer spin-up times. For example, the following will setup and run the AR-SLu site for three 100-year segments in ``ad`` spinup mode for a total of 300 years:
+   ::
 
-### Spin-up notes
+       cd  CTSM/tools/site_and_regional
+       ./run_tower --plumber-sites AR-SLu --run-type ad --xmlchange STOP_OPTION=nyears,STOP_N=100,RESUBMIT=2,JOB_WALLCLOCK_TIME=06:00:00
 
-1) By default, all simulations (e.g., ad, post-ad, transient) are designed to run for 1 hour of wall clock time. For the spin-up simulations, we recommend extending the time to match the length of the simulations. `Lombardozzi et al. 2023 <https://doi.org/10.5194/gmd-16-5979-2023>`_ used 300 years for AD and 100 years for post-ad. Users should keep in mind that colder areas might need longer spin-up times. 
-2) By default, the initial period of the simulations differs for the spin-up (e.g., ad and post-ad) and transient simulations. It is important to revisit for each site the best period to use for the spin-up simulations.
-3) We recommended spinning up with the no_leap calendar to avoid issues with Feb 28th and 29th on leap years. See below.
+#. The initial and final years of the simulations may differ for the spin-up (e.g., ad and postad) and transient simulations. This is to avoid calendar errors encountered when the start time is local midnight.
 
-:: 
-    >  ./xmlchange CALENDAR=NO_LEAP
+#. By default, the NO_LEAP calendar is used for the ad and postad cases to avoid issues with the transition between Feb 28th and 29th on leap years, this is accomplished in the usermods via
+   ::
 
-4) In AD and post-ad simulations, we recommend setting dtlimit=50 in the user_nl_datm_streams files to avoid time step issues. 
+       ./xmlchange CALENDAR=NO_LEAP
 
+#. In ad and postad simulations, ``dtlimit`` is set to ``50`` in the user_nl_datm_streams files to avoid issues encountered when cycling over the datm forcing data.
 
-### MPI related notes
+-----------------------
+A practical example
+-----------------------
 
-We recommend running the following lines to avoid MPI related issues. By default, these lines are included in the usermods; however, sometimes is needed to include them again. 
+Here is an example of setting up and running a PLUMBER2 site with the ``run_tower`` tool, from ad through transient mode.
 
 :: 
-    > ./xmlchange --force MPILIB=mpi-serial
-    > ./xmlchange --force PIO_TYPENAME=netcdf
-    > ./xmlchange --force MAX_MPITASKS_PER_NODE=1
-
 
-### Potential modifications 
+    cd CTSM/tools/site_and_regional
+    setenv tower AR-SLu  # (tcsh) or export tower=AR-SLu (bash)
+    ./run_tower --plumber-sites ${tower} --run-type ad --xmlchange STOP_OPTION=nyears,STOP_N=100,RESUBMIT=2,JOB_WALLCLOCK_TIME=06:00:00
+    # CHECK FOR SUCCESSFUL COMPLETION of ad MODE
+    ./run_tower --plumber-sites ${tower} --run-type postad --xmlchange STOP_OPTION=nyears,STOP_N=100,JOB_WALLCLOCK_TIME=06:00:00
+    # CHECK FOR SUCCESSFUL COMPLETION of postad MODE
+    ./run_tower --plumber-sites ${tower} --run-type transient
 
-The ``run_tower``  tool is designed to provided a streamlined way to run single point simulations at supported tower sites. In that way, it can be quickly modified to accommodate different needs. A few potential modifications include:
-1) Running FATES enabled simulations. 
-2) Running satellite phenology enabled simulations.
 
-At the moment, these modifications are not included in the tool; however, users can modify the usermods files to accommodate these needs.
-
-### A practical example
-
-Here is an example of running a PLUMBER site with the ``run_tower`` tool, including the notes mentioned above
-
-:: 
-    > cd CTSM/tools/site_and_regional
-    > tower="AU-ASM"
-    >  ./run_tower --plumber-sites ${tower} --output-root /path/to/save/results --overwrite --run-type ad --setup-only # first ad, then post-ad, then transient
-    >  cd case_name
-    >  echo "baseflow_scalar = 0" >> user_nl_clm
-    >  ./xmlchange CALENDAR=NO_LEAP
-    >  ./xmlchange --force MPILIB=mpi-serial
-    >  ./xmlchange --force PIO_TYPENAME=netcdf
-    >  ./xmlchange --force MAX_MPITASKS_PER_NODE=1
-
-Once these instructions are followed, it is key to check (a) the user_nl_data_streams to ensure that the right dt_limit is set and the right forcing files are being used, (b) the user_nl_clm to ensure that the right variables are being saved. Then, the case can be setup, built and submitted.