Merge pull request #3194 from TeaganKing/tower_docs

Updates to run_tower/single point documentation

Author: samsrabin

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
 

doc/source/users_guide/running-single-points/intro-to-single-pt-regional.rst

@@ -0,0 +1,54 @@
+.. include:: ../substitutions.rst
+
+.. _single-point-regional-configurations:
+
+*****************************************************
+Introduction to Single-Point and Regional Grid Setups
+*****************************************************
+
+CTSM is designed to support a wide range of spatial scales, ranging from global simulations to regional runs to highly resolved single-point cases. Setting up and running single-point and regional simulations is useful for a variety of purposes including: running quick cases for testing, evaluating specific vegetation types, or running with observed data from a specific site to generate and test hypotheses.
+
+Single-point cases allow users to run CTSM at a specific location such as a flux tower or ecological field site. Single-point runs are especially useful where high-resolution meteorological forcing data and site-specific observations are available and require minimal computational resources.
+
+Regional configurations support simulations over broader geographic areas defined by a user-specified domain. Regional runs require additional input data such as meteorological forcing for the region. You can either extract regional subsets from global datasets or create custom datasets for your region of interest.
+
+.. _options-for-single-points:
+
+=========================================
+ Choosing the right single point options
+=========================================
+
+There are several different ways to set up single-point and regional cases.
+
+For supported tower sites:
+--------------------------
+
+You can run at a supported tower site if one of the supported single-point/regional datasets is your site of interest (see :ref:`supported-tower-sites`). All the datasets are created for you, and you can easily select one and run it out of the box using a supported resolution from the top level of the CESM scripts. 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.
+
+Next, using ``subset_data`` is the best way to setup cases quickly where you can use a simple tool to create your own datasets (see :ref:`generic_single_point_runs`). 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.
+
+For unsupported tower sites:
+----------------------------
+
+If you have meteorology data that you want to force your CLM simulations with, you'll need to setup cases as described in :ref:`pre-defined-single-pt-regional-resolutions`. 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.
+
+================
+Spinning up CTSM
+================
+
+We make steady state assumptions about the initial state of ecosystem properties including temperature water, snow, ice, carbon & nitrogen. This is the equilibrium state of the model, given the forcing data. Spinning up the model brings internal state variables into equilibrium with environmental forcing conditions so that the results are not influenced by the initial conditions of state variables (such as soil C). In runs with active biogoechemistry, we need to get the ecosystem carbon and nitrogen pools with long turnover times into steady state.
+
+Specifically, spinning up CTSM consists of 3 parts including:
+
+1. AD, or accelerated decomposition: The turnover and decomposition of the slow pools of C and N that normally have a long residence time in ecosystems is mathematically accelerated, where we make the slow pools spin up more quickly by increasing their turnover time. This includes:
+-Accelerating turnover of wood, litter and soil pools
+-Accelerating advection and diffusion terms
+-Calculating this as a function of latitude so that spinup is more accelerated in high latitude regions.
+
+2. postAD, which occurs after AD spinup: During postAD runs we take away accelerated decomposition and let the ecosystem settle into its equilibrium, or steady-state under 'normal conditions'. Pools are increased by the same degree their turnover was increased (e.g., turnover 10x faster means the pool must be 10x larger). During AD and postAD spinup we cycle over several years of input data and hold other inputs constant (e.g., atmospheric CO2 concentrations, N deposition, etc.). For transient runs these inputs also change over time.
+
+3. transient: Transient runs are used to compare with observations, and include high frequency output that we can compare with flux tower measurements. The end of the spinup simulation is used as the initial conditions for a transient simulation, set in the user_nl_clm file.
+
+
+
+

doc/source/users_guide/running-single-points/running-pts_mode-configurations.rst renamed to doc/source/users_guide/running-single-points/predefined-single-point-regional-resolutions.rst

@@ -1,13 +1,13 @@
 .. include:: ../substitutions.rst
 
-.. _pts_mode:
+.. _pre-defined-single-pt-regional-resolutions:
 
 ****************************************************
-Running a single point using global data - PTS_MODE
+Pre-defined single-point and regional resolutions
 ****************************************************
 
 .. 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`` has been mostly deprecated in favor of ``subset_data`` (Sect. :numref:`generic_single_point_runs`). 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.