Merge pull request #1969 from billsacks/data_model_edits

Data model documentation edits

doc/source/data_models/data-atm.rst

@@ -51,28 +51,29 @@ These variables will appear in ``env_run.xml`` and the resulting values are comp
 datamode values
 --------------------
 
-The xml variable ``DATM_MODE`` is used to set the streams that are associated with DATM and also to set the namelist variable ``datamode`` that specifies what additional operations need to be done by DATM on the streams before returning to the driver.
-One of the variables in ``shr_strdata_nml`` is ``datamode``, whose value is a character string.  Each data model has a unique set of ``datamode`` values that it supports.
-The valid values for ``datamode`` are set in the file ``namelist_definition_datm.xml`` using the xml variable ``DATM_MODE`` in the ``config_component.xml`` file for DATM.
-CIME will generate a value ``datamode`` that is compset dependent.
+The xml variable ``DATM_MODE`` (described in :ref:`datm_mode`) sets the streams that are associated with DATM and also sets the namelist variable ``datamode``.
+``datamode`` (which appears in ``shr_strdata_nml``) specifies what additional operations need to be done by DATM on the streams before returning to the driver.
 
-The following are the supported DATM ``datamode`` values and their relationship to the ``$DATM_MODE`` xml variable value.
+Each data model has its own set of supported ``datamode`` values. The following are the supported DATM ``datamode`` values, as defined in the file ``namelist_definition_datm.xml``.
 
 .. csv-table:: "Valid values for datamode namelist variable"
    :header: "datamode variable", "description"
    :widths: 20, 80
 
    "NULL", "This mode turns off the data model as a provider of data to the coupler. The ``atm_present`` flag will be set to ``false`` and the coupler assumes no exchange of data to or from the data model."
-   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams, if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero except for aerosol deposition fields which will be set to a special value. "
+   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams; if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero except for aerosol deposition fields which will be set to a special value. "
    "CLMNCEP", "In conjunction with NCEP climatological atmosphere data, provides the atmosphere forcing favored by the Land Model Working Group when coupling an active land model with observed atmospheric forcing. This  mode replicates code previously found in CLM (circa 2005), before the LMWG started using the CIME coupling infrastructure and data models to do active-land-only simulations."
    "CORE2_NYF", "Coordinated Ocean-ice Reference Experiments (CORE) Version 2 Normal Year Forcing."
    "CORE2_IAF", "In conjunction with with CORE Version 2 atmospheric forcing data, provides the atmosphere forcing favored by the Ocean Model Working Group when coupling an active ocean model with observed atmospheric forcing. This mode and associated data sets implement the CORE-IAF Version 2 forcing data, as developed by Large and Yeager (2008) at NCAR.  Note that CORE2_NYF and CORE2_IAF work exactly the same way."
 
+.. _datm_mode:
+
 -------------------------------
 DATM_MODE, datamode and streams
 -------------------------------
 
-The following tabe describes the valid values of ``DATM_MODE``, and how it relates to the associated input streams and the ``datamode`` namelist variable.
+The following table 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.
 
 .. csv-table:: "Relationship between DATM_MODE, datamode and streams"
    :header: "DATM_MODE", "description-streams-datamode"

doc/source/data_models/data-lnd.rst

@@ -35,33 +35,34 @@ These variables will appear in ``env_run.xml`` and are used by the DLND ``cime_c
    "DLND_CPLHIST_YR_START", "Coupler history forcing data mode - starting year to loop data over"
    "DLND_CPLHIST_YR_END", "Coupler history forcing data mode - ending year to loop data over"
 
-.. note:: If ``DLND_MODE`` is set to ``CPLHIST``, it is normally assumed that the model domain will be identical to **all** of the stream domains. To ensure this, the xml variables ``LND_DOMAIN_PATH`` and ``LND_DOMAIN_FILE`` are ignored and a valid setting **must be given** for ``DLND_CPLHIST_DOMAIN_FILE``. If ``DLND_CPLHIST_DOMAIN_FILE`` is set to ``null``, then the dlnd component 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. This is the default mode that should be used for this mode. Alternatively, ``DLND_CPLHIST_DOMAIN_FILE`` can be set to ``$LND_DOMAIN_PATH/$LND_DOMAIN_FILE`` in a non-default configuration.
+.. note:: If ``DLND_MODE`` is set to ``CPLHIST``, it is normally assumed that the model domain will be identical to **all** of the stream domains. To ensure this, the xml variables ``LND_DOMAIN_PATH`` and ``LND_DOMAIN_FILE`` are ignored and a valid setting **must be given** for ``DLND_CPLHIST_DOMAIN_FILE``. If ``DLND_CPLHIST_DOMAIN_FILE`` is set to ``null``, then the dlnd component 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. Alternatively, ``DLND_CPLHIST_DOMAIN_FILE`` can be set to ``$LND_DOMAIN_PATH/$LND_DOMAIN_FILE``.
 
 .. _dlnd-datamodes:
 
 --------------------
 datamode values
 --------------------
 
-The xml variable ``DLND_MODE`` sets the streams that are associated with DLND and also sets the namelist variable ``datamode`` that specifies what additional operations need to be done by DLND on the streams before returning to the driver.
-One of the variables in ``shr_strdata_nml`` is ``datamode``, whose value is a character string.  Each data model has a unique set of ``datamode`` values that it supports.
-The valid values for ``datamode`` are set in the file ``namelist_definition_dlnd.xml`` using the xml variable ``DLND_MODE`` in the ``config_component.xml`` file for DLND.
-CIME will generate a value ``datamode`` that is compset dependent.
+The xml variable ``DLND_MODE`` (described in :ref:`dlnd_mode`) sets the streams that are associated with DLND and also sets the namelist variable ``datamode``.
+``datamode`` (which appears in ``shr_strdata_nml``) specifies what additional operations need to be done by DLND on the streams before returning to the driver.
 
-The following are the supported DLND datamode values and their relationship to the ``$DLND_MODE`` xml variable value.
+Each data model has its own set of supported ``datamode`` values. The following are the supported DLND ``datamode`` values, as defined in the file ``namelist_definition_dlnd.xml``.
 
 .. csv-table:: "Valid values for datamode namelist variable"
    :header: "datamode variable", "description"
    :widths: 20, 80
 
-   "NULL", "Turns off the data model as a provider of data to the coupler.  The ice_present flag will be set to false and the coupler will assume no exchange of data to or from the data model."
-   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams, if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero."
+   "NULL", "Turns off the data model as a provider of data to the coupler.  The ``lnd_present`` flag will be set to false and the coupler will assume no exchange of data to or from the data model."
+   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams; if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero."
+
+.. _dlnd_mode:
 
 -------------------------------
 DLND_MODE, datamode and streams
 -------------------------------
 
-The following tabe describes the valid values of ``DLND_MODE``, and how it relates to the associated input streams and the ``datamode`` namelist variable.
+The following table 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.
 
 .. csv-table:: "Relationship between DLND_MODE, datamode and streams"
    :header: "DLND_MODE", "description-streams-datamode"
@@ -70,12 +71,12 @@ The following tabe describes the valid values of ``DLND_MODE``, and how it relat
    "NULL", "null mode"
    "", "streams: none"
    "", "datamode: null"
-   "CPLHIST", "land forcing data (e.g. produced by CESM/CLM) from a previous model run is output in coupler history files and read in by the data land model."
+   "CPLHIST", "land forcing data (e.g. produced by CESM/CLM) from a previous model run are read in from coupler history files"
    "", "streams: lnd.cplhist"
-   "", "COPYALL"
-   "GLC_CPLHIST", "glc coupling fields (e.g. produced by CESM/CLM) from a previous model run are read in from a coupler history file."
-   "", "streams: glc.cplhist"
-   "", "COPYALL"
+   "", "datamode: COPYALL"
+   "GLC_CPLHIST", "glc coupling fields (e.g. produced by CESM/CLM) from a previous model run are read in from coupler history files"
+   "", "streams: sno.cplhist"
+   "", "datamode: COPYALL"
 
 ---------
 Namelists
@@ -100,7 +101,7 @@ restfils               stream restart filename
 force_prognostic_true  TRUE => force prognostic behavior
 =====================  ======================================================
 
-To change the namelist settings in dlnd_in, edit the file user_nl_dlnd.
+To change the namelist settings in ``dlnd_in``, edit the file ``user_nl_dlnd``.
 
 .. _dlnd-mode-independent-streams:
 
@@ -145,8 +146,9 @@ In general, the stream input file should translate the stream input variable nam
    "flxdst2", "Fall_flxdst2"
    "flxdst3", "Fall_flxdst3"
    "flxdst4", "Fall_flxdst4"
-   "tsrfNN", "Sl_tsrf"
-   "topoNN", "Sl_topo"
-   "qiceNN",  "Flgl_qice"
+   "tsrfNN", "Sl_tsrfNN"
+   "topoNN", "Sl_topoNN"
+   "qiceNN",  "Flgl_qiceNN"
 
-where NN = (01,02,...,``nflds_snow * glc_nec)``, and ``nflds_snow`` is the number of snow fields in each elevation class and ``glc_nec`` is the number of elevation classes.
+where NN = (01,02,..., ``glc_nec``), and ``glc_nec`` is the number of glacier elevation classes.
+Note that the number of elevation classes on the input files must be the same as in the run.

doc/source/data_models/data-model-science.rst

@@ -3,27 +3,27 @@
 Data Model Science
 ==================
 
-When a given data models run, the user must specify which *science mode* it will run in. 
+When a given data model is run, the user must specify which *science mode* it will run in.
 Each data model has a fixed set of fields that it must send to the coupler, but it is the choice of mode that specifies how that set of fields is to be computed. 
 Each mode activates various assumptions about what input fields are available from the input data streams, what input fields are available from the the coupler, and how to use this input data to compute the output fields sent to the coupler.
 
 In general, a mode might specify...
 
 - that fields be set to a time invariant constant (so that no input data is needed)
-- that fields be taken directly from a input data files (the input streams)
+- that fields be taken directly from input data files (the input streams)
 - that fields be computed using data read in from input files
-- that fields be computed using from data received from the coupler
+- that fields be computed using data received from the coupler
 - some combination of the above.
 
-If a science mode is chosen that is not consistent with the input data provided, the model may abort (perhaps with a "missing data" error message), or the model may send erroneous data to the coupler (for example, if a mode assumes an input stream has temperature in Kelvin on it, but it really has temperature in Celsius). 
+If a science mode is chosen that is not consistent with the input data provided, the model may abort (perhaps with a "missing data" error message), or the model may send erroneous data to the coupler (for example, if a mode assumes an input stream has temperature in Kelvin, but it really has temperature in Celsius).
 Such an error is unlikely unless a user has edited the run scripts to specify either non-standard input data or a non-standard science mode. 
 When editing the run scripts to use non-standard stream data or modes, users must be careful that the input data is consistent with the science mode and should verify that the data model is providing data to the coupler as expected.
 
 The data model mode is a character string that is set in the namelist variable ``datamode`` in the namelist group ``shr_strdata_nml``. Although each data model, 
 ``datm``, ``dlnd``, ``drof``, ``docn``, ``dice`` and ``dwav`` has its own set of valid datamode values, two modes are common to all data models: ``COPYALL`` and ``NULL``.
 
 ``dataMode = "COPYALL"``
-  The default mode is COPYALL -- the model will assume *all* the data that must be sent to the coupler will be found in the input data streams, and that this data can be sent to the coupler, unaltered, except for spatial and temporal interpolation.
+  The default mode is ``COPYALL`` -- the model will assume *all* the data that must be sent to the coupler will be found in the input data streams, and that this data can be sent to the coupler, unaltered, except for spatial and temporal interpolation.
 
 ``dataMode = "NULL"``
-  NULL mode turns off the data model as a provider of data to the coupler. The model_present flag (eg. atm_present) will be set to false and the coupler will assume no exchange of data to or from the data model.
+  ``NULL`` mode turns off the data model as a provider of data to the coupler. The ``model_present`` flag (eg. ``atm_present``) will be set to false and the coupler will assume no exchange of data to or from the data model.

doc/source/data_models/data-ocean.rst

@@ -78,28 +78,29 @@ These variables will appear in ``env_run.xml`` and are used by the DOCN ``cime_c
 datamode values
 ---------------
 
-The xml variable ``DOCN_MODE`` sets the streams that are associated with DOCN and also sets the namelist variable ``datamode`` that specifies what additional operations need to be done by DOCN on the streams before returning to the driver.
-One of the variables in ``shr_strdata_nml`` is ``datamode``, whose value is a character string.  Each data model has a unique set of ``datamode`` values that it supports. 
-The valid values for ``datamode`` are set in the file ``namelist_definition_docn.xml`` using the xml variable ``DOCN_MODE`` in the ``config_component.xml`` file for DOCN. 
-CIME will generate a value ``datamode`` that is compset dependent. 
+The xml variable ``DOCN_MODE`` (described in :ref:`docn_mode`) sets the streams that are associated with DOCN and also sets the namelist variable ``datamode``.
+``datamode`` (which appears in ``shr_strdata_nml``) specifies what additional operations need to be done by DOCN on the streams before returning to the driver.
 
-The following are the supported DOCN datamode values and their relationship to the ``DOCN_MODE`` xml variable value.
+Each data model has its own set of supported ``datamode`` values. The following are the supported DOCN ``datamode`` values, as defined in the file ``namelist_definition_docn.xml``.
 
 .. csv-table:: "Valid values for datamode namelist variable"
    :header: "datamode variable", "description"
    :widths: 20, 80
 
    "NULL", "Turns off the data model as a provider of data to the coupler.  The ocn_present flag will be set to false and the coupler will assume no exchange of data to or from the data model."
-   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams, if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero."
+   "COPYALL", "The default science mode of the data model is the COPYALL mode. This mode will examine the fields found in all input data streams; if any input field names match the field names used internally, they are copied into the export array and passed directly to the coupler without any special user code.  Any required fields not found on an input stream will be set to zero."
    "SSTDATA", "assumes the only field in the input stream is SST. It also assumes the SST is in Celsius and must be converted to Kelvin.  All other fields are set to zero except for ocean salinity, which is set to a constant reference salinity value. Normally the ice fraction data is found in the same data files that provide SST data to the data ocean model. They are normally found in the same file because the SST and ice fraction data are derived from the same observational data sets and are consistent with each other. They are normally found in the same file because the SST and ice fraction data are derived from the same observational data sets and are consistent with each other."
    "IAF", "is the interannually varying version of SSTDATA"
    "SOM", "(slab ocean model) mode is a prognostic mode.  This mode computes a prognostic sea surface temperature and a freeze/melt potential (surface Q-flux) used by the sea ice model.  This calculation requires an external SOM forcing data file that includes ocean mixed layer depths and bottom-of-the-slab Q-fluxes. Scientifically appropriate bottom-of-the-slab Q-fluxes are normally ocean resolution dependent and are derived from the ocean model output of a fully coupled CCSM run.  Note that while this mode runs out of the box, the default SOM forcing file is not scientifically appropriate and is provided for testing and development purposes only. Users must create scientifically appropriate data for their particular application.  A tool is available to derive valid SOM forcing."
 
+.. _docn_mode:
+
 -------------------------------
 DOCN_MODE, datamode and streams
 -------------------------------
 
-The following tabe describes the valid values of ``DOCN_MODE``, and how it relates to the associated input streams and the ``datamode`` namelist variable.
+The following table describes the valid values of ``DOCN_MODE`` (defined in the ``config_component.xml`` file for DOCN), and how they relate to the associated input streams and the ``datamode`` namelist variable.
+CIME will generate a value of ``DOCN_MODE`` based on the compset.
 
 .. csv-table:: "Relationship between DOCN_MODE, datamode and streams"
    :header: "DOCN_MODE, "description-streams-datamode"