updated documentation for new docn changes and to document env_run.xm…

…l cdeps variables
ESCOMP · Feb 1, 2023 · 0405140 · 0405140
1 parent 1bb6010
commit 0405140
Show file tree

Hide file tree

Showing 7 changed files with 335 additions and 124 deletions.
diff --git a/doc/source/datm.rst b/doc/source/datm.rst
@@ -5,13 +5,13 @@ Data Atmosphere (DATM)
 
 DATM is normally used to provide observational forcing data (or
 forcing data produced by a previous run using active components) to
-drive prognostic components. The various ways of running DATM is 
+drive prognostic components. The various ways of running DATM is
 referred to as its mode.
 
-In the case of CESM, the active model components would be: CTSM, 
-POP2, MOM6, POP2, CICE5-6, WW3 and MOSART. As examples, CORE2_NYF 
-(CORE2 normal year forcing) is the DATM mode used in driving 
-POP2 and MOM6. On the other hand CLM_QIAN, CLMCRUNCEP, CLMGSWP3 
+In the case of CESM, the active model components would be: CTSM,
+POP2, MOM6, POP2, CICE5-6, WW3 and MOSART. As examples, CORE2_NYF
+(CORE2 normal year forcing) is the DATM mode used in driving
+POP2 and MOM6. On the other hand CLM_QIAN, CLMCRUNCEP, CLMGSWP3
 and CLM1PT are DATM modes using observational data for forcing CTSM.
 
 .. _datm-datamodes:
@@ -36,7 +36,7 @@ CLMNCEP (``datm_datamode_clmncep_mod.F90``)
     infrastructure and data models to do active-land-only simulations.
 
 CORE2_NYF (``datm_datamode_core2_mod.F90``)
-  - Coordinated Ocean-ice Reference Experiments (CORE) Version 2 
+  - Coordinated Ocean-ice Reference Experiments (CORE) Version 2
     Normalst_aquap[1-10]Year Forcing.
 
 CORE2_IAF (``datm_datamode_core2_mod.F90``)
@@ -60,88 +60,141 @@ ERA5 (``datm_datamode_era5_mod.F90``)
 
 .. note::
   Due to the high temporal and spatial resoultion of ERA5 dataset, only 2019
-  data is staged on NCAR's Cheyenne platform under 
+  data is staged on NCAR's Cheyenne platform under
   `$CESMDATAROOT/inputdata/atm/datm7/ERA5`
 
 .. note::
-  In addition to the exiting DATM data modes, the `CDEPS fork <https://github.com/NOAA-EMC/CDEPS>`_ 
-  used by `NOAA's UFS Weather Model <https://github.com/ufs-community/ufs-weather-model>`_ 
-  also includes additional data modes such as CFSR, GEFS and GFS. These data modes are not 
+  In addition to the exiting DATM data modes, the `CDEPS fork <https://github.com/NOAA-EMC/CDEPS>`_
+  used by `NOAA's UFS Weather Model <https://github.com/ufs-community/ufs-weather-model>`_
+  also includes additional data modes such as CFSR, GEFS and GFS. These data modes are not
   merged with the NCAR's authoritative repository yet but it is tested under UFS Weather
   model.
- 
+
 .. _datm-cime-vars:
 
 ---------------------------------------
 Configuring DATM from CIME
 ---------------------------------------
 
 If CDEPS is coupled to the CIME-CCS then the CIME ``$CASEROOT`` xml
-variable ``DATM_MODE`` sets the collection of streams that
-are associated with DATM and also sets the datm namelist variable
-``datamode`` in the file ``datm_in``. The following are the supported
-DATM ``datamode`` values, as defined in the file
-``namelist_definition_datm.xml``.
+variable ``DATM_MODE`` will be generated based on the compset
+specification ``DATM%{DATM_MODE}``.  ``DATM_MODE`` will in term be
+used in the ``namelist_definition_datm.xml`` file to determine the
+collection of streams that are associated with DATM and also sets the
+datm namelist variable ``datamode`` in the file ``datm_in``.
 
-The following table describes the valid values of ``DATM_MODE``
+The following list describes the valid values of ``DATM_MODE``
 (defined in the ``config_component.xml`` file for DATM), and how they
 relate to the associated input streams and the ``datamode`` namelist
-variable. CIME will generate a value of ``DATM_MODE`` based on the
-compset.
+variable.
 
-CORE2_NYF
+DATM%CORE2_NYF,
    - CORE2 normal year forcing (CESM C ang G compsets)
+   - datm_mode: CORE2_NYF
    - streams: CORE2_NYF.GISS,CORE2_NYF.GXGXS,CORE2_NYF.NCEP
    - datamode: CORE2_NYF
 
-CORE2_IAF
+DATM%CORE2_IAF,
    - CORE2 interannual year forcing (CESM C ang G compsets)
+   - datm_mode: CORE2_IAF
    - streams: CORE2_IAF.GCGCS.PREC,CORE2_IAF.GISS.LWDN,
      CORE2_IAF.GISS.SWDN,CORE2_IAF.GISS.SWUP,
      CORE2_IAF.NCEP.DN10,CORE2_IAF.NCEP.Q_10,
      CORE2_IAF.NCEP.SLP\_,CORE2_IAF.NCEP.T_10,CORE2_IAF.NCEP.U_10,
      CORE2_IAF.NCEP.V_10,CORE2_IAF.CORE2.ArcFactor
    - datamode: CORE2_IAF
 
-CORE_IAF_JRA
+DATM%CORE_IAF_JRA
    - JRA-55 intra-annual year forcing (CESM C ang G compsets)
    - streams: CORE_IAF_JRA.PREC,CORE_IAF_JRA.LWDN,CORE_IAF_JRA.SWDN,
      CORE_IAF_JRA.Q_10,CORE_IAF_JRA.SLP\_,CORE_IAF_JRA.T_10,CORE_IAF_JRA.U_10,
      CORE_IAF_JRA.V_10,CORE_IAF_JRA.CORE2.ArcFactor
    - datamode: CORE_IAF_JRA
 
-CLM_QIAN_WISO
+DATM%CLM_QIAN_WISO
    - QIAN atm input data with water isotopes (CESM I compsets)
+   - datm_mode: CLMNCEP
    - streams: CLM_QIAN_WISO.Solar,CLM_QIAN_WISO.Precip,CLM_QIAN_WISO.TPQW
    - datamode: CLMNCEP
 
-CLM_QIAN
+DATM%CLM_QIAN
    - QIAN atm input data (CESM I compsets)
+   - datm_mode: CLMNCEP
    - streams: CLM_QIAN.Solar,CLM_QIAN.Precip,CLM_QIAN.TPQW
    - datamode: CLMNCEP
 
-CLMCRUNCEPv7
+DATM%CLMCRUNCEPv7
    - CRUNCEP atm input data (CESM I compsets)
+   - datm_mode: CLMNCEP
    - streams: CLMCRUNCEP.Solar,CLMCRUNCEP.Precip,CLMCRUNCEP.TPQW
    - datamode: CLMNCEP
 
-CLMGSWP3
+DATM%CLMGSWP3
    - GSWP3 atm input data (I compsets)
+   - datm_mode: CLMNCEP
    - streams: CLMGSWP3.Solar,CLMGSWP3.Precip,CLMGSWP3.TPQW
    - datamode: CLMNCEP
 
-CLM1PT
+DATM%CLM1PT
    - single point tower site atm input data
+   - datm_mode: CLMNCEP
    - streams: CLM1PT.$ATM_GRID
    - datamode: CLMNCEP
 
-ERA5
+DATM%ERA5
    - ERA5 atm input data (not used any compset)
+   - datm_mode: ERA5
    - streams: ERA5_HOURLY
    - datamode: ERA5
 
-CPLHIST
+DATM%CPLHIST
    - user generated forcing data from using coupler history files
      used to spinup relevant prognostic components (for CESM this is CLM, POP and CISM)
+   - datm_mode:CPLHIST
    - streams: CPLHISTForcing.Solar,CPLHISTForcing.nonSolarFlux,
    - datamode: CPLHIST
+
+In addition, the following DATM specific CIME-CCS xml variables will appear in ``$CASEROOT/env_run.xml``:
+
+DATM_PRESAERO
+   - DATM prescribed aerosol forcing mode
+
+DATM_TOPO
+   - DATM surface topography forcing (only needed for compsets with active land)
+
+DATM_CO2_TSERIES
+   - Full pathname for domain file for datm when DATM_MODE is
+     CPLHIST, NOTE: if this is set to 'null' (the default), then
+     domain information is read in from the first coupler history
+     file in the target stream and it is assumed that the first
+     coupler stream file that is pointed to contains the domain
+     information for that stream.
+
+DATM_CPLHIST_CASE
+   - Case name used to determine stream filenames when DATM_MODE is CPLHIST
+
+DATM_YR_START
+   -  Starting year to loop data over
+
+DATM_YR_END
+   -  Ending year to loop data over
+
+DATM_YR_ALIGN
+   - Simulation year corresponding to DATM_YR_START. A common usage
+     is to set this to RUN_STARTDATE. With this setting, the forcing
+     in the first year of the run will be the forcing of year
+     DATM_YR_START. Another use case is to align the calendar
+     of transient forcing with the model calendar. For example,
+     setting DATM_YR_ALIGN=DATM_YR_START will lead to
+     the forcing calendar being the same as the model calendar. The
+     forcing for a given model year would be the forcing of the same
+     year. This would be appropriate in transient runs where the
+     model calendar is setup to span the same year range as the
+     forcing data.
+
+DATM_SKIP_RESTART_READ
+   -  If set to true, than datm restarts will not be read on a continuation run.
+      This capability is used, for example, in CTSM spinup runs.
+
+
+
diff --git a/doc/source/dice.rst b/doc/source/dice.rst
@@ -4,7 +4,7 @@ Data Ice (DICE)
 ===============
 
 DICE is normally used to provide observational forcing data to
-drive prognostic components. The various ways of running DICE is 
+drive prognostic components. The various ways of running DICE is
 referred to as its mode.
 
 .. _dice-datamodes:
@@ -34,24 +34,27 @@ Configuring DICE from CIME
 ---------------------------------------
 
 If CDEPS is coupled to the CIME-CCS then the CIME ``$CASEROOT`` xml
-variable ``DICE_MODE`` sets the collection of streams that
-are associated with DICE and also sets the dice namelist variable
-``datamode`` in the file ``dice_in``. The following are the supported
-DICE ``datamode`` values, as defined in the file
-``namelist_definition_dice.xml``.
+variable ``DICE_MODE`` will be generated based on the compset
+specification ``DICE%{DICE_MODE}``.  ``DICE_MODE`` will in term be
+used in the ``namelist_definition_dice.xml`` file to determine the
+collection of streams that are associated with DICE and also sets the
+dice namelist variable ``datamode`` in the file ``dice_in``.
 
-The following table describes the valid values of ``DICE_MODE``
+The following list describes the valid values of ``DICE_MODE``
 (defined in the ``config_component.xml`` file for DICE), and how they
 relate to the associated input streams and the ``datamode`` namelist
-variable. CIME will generate a value of ``DICE_MODE`` based on the
-compset.
+variable.
 
-ssmi
+DICE%SSMI
    - Reads data from file
+   - dice_mode: ssmi
    - streams: ssmi_nyf
-   - datamode: ssmi 
+   - datamode: ssmi
 
-ssmi_iaf
-   - Reads data from file 
+DICE%IAF
+   - Reads data from file
+   - dice_mode: ssmi_iaf
    - streams: ssmi_iaf
-   - datamode: ssmi_iaf 
+   - datamode: ssmi_iaf
+
+There are currently no DICE other specific xml variables in ``$CASEROOT/env_run.xml``.
diff --git a/doc/source/dlnd.rst b/doc/source/dlnd.rst
@@ -4,7 +4,7 @@ Data Land (DLND)
 ================
 
 DLND is normally used to provide forcing data produced by a previous run
-using active components to drive prognostic components. Currently, there 
+using active components to drive prognostic components. Currently, there
 is one way of running DLND is referred to as its mode.
 
 .. _dlnd-datamodes:
@@ -21,38 +21,66 @@ with a DLND source file that carries out these operations and these are
 listed in parentheses next to the mode name.
 
 copyall (``lnd_comp_nuopc.F90``)
-  - This mode assumes that the data file has following variables: 
+  - This mode assumes that the data file has following variables:
     1. Surface temperature (`Sl_tsrf_elev`) in each elevation class
     2. Surface topography (`Sl_topo_elev`) in each elevation class
     3. SMB flux (`Flgl_qice_elev`) in each elevation class
 
 .. _dlnd-cime-vars:
 
 ---------------------------------------
-Configuring DLND from CIME
+Configuring DLND using the CIME-CCS
 ---------------------------------------
 
 If CDEPS is coupled to the CIME-CCS then the CIME ``$CASEROOT`` xml
-variable ``DLND_MODE`` sets the collection of streams that
-are associated with DLND and also sets the dlnd namelist variable
-``datamode`` in the file ``dlnd_in``. The following are the supported
-DLND ``datamode`` values, as defined in the file
-``namelist_definition_dlnd.xml``.
+variable ``DLND_MODE`` will be generated based on the compset
+specification ``DLND%{DLND_MODE}``.  ``DLND_MODE`` will in term be
+used in the ``namelist_definition_dlnd.xml`` file to determine the
+collection of streams that are associated with DLND and also sets the
+dlnd namelist variable ``datamode`` in the file ``dlnd_in``.
 
-The following table describes the valid values of ``DLND_MODE``
+The following list describes the valid values of ``DLND_MODE``
 (defined in the ``config_component.xml`` file for DLND), and how they
 relate to the associated input streams and the ``datamode`` namelist
-variable. CIME will generate a value of ``DLND_MODE`` based on the
-compset.
+variable.
 
-LCPL
+DLND%LCPL
    - Non-snow coupling mode. Land forcing data (produced by CLM) from a previous
-      model run is read in from a coupler history file.
+     model run is read in from a coupler history file.
+   - dlnd_mode: SCPL
    - streams: lnd.cplhist
    - datamode: copyall
 
-SCPL
+DLND%SCPL
    - Snow coupling mode. Glacier coupling data (produced by CISM) from a previous
      model run is read in from a coupler history file.
+   - dlnd_mode: LCPL
    - streams: sno.cplhist
    - datamode: copyall
+
+In addition, the following DLND specific CIME-CCS xml variables will appear in ``$CASEROOT/env_run.xml``:
+
+DLND_CPLHIST_DIR
+   - directory for coupler history data mode
+
+DLND_CPLHIST_CASE
+   - case name for coupler history data mode
+
+DLND_CPLHIST_YR_START
+    - starting year to loop data over
+
+DLND_CPLHIST_YR_ALIGN
+   - Simulation year corresponding to DLND_CPLHIST_YR_START (only used
+     when DLND_MODE is CPLHIST or GLC_CPLHIST). A common usage is to
+     set this to RUN_STARTDATE. With this setting, the forcing in the
+     first year of the run will be the forcing of year
+     DLND_CPLHIST_YR_START. Another use case is to align the calendar
+     of transient forcing with the model calendar. For example, setting
+     DLND_CPLHIST_YR_ALIGN=DLND_CPLHIST_YR_START will lead to the
+     forcing calendar being the same as the model calendar. The forcing
+     for a given model year would be the forcing of the same year. This
+     would be appropriate in transient runs where the model calendar is
+     setup to span the same year range as the forcing data.
+
+DLND_SKIP_RESTART_READ
+   - If set to true, than dlnd restarts will not be read on a continuation run.