Merge pull request #1950 from ESMCI/mvertens/cplhist_topo

refactor CPLHIST mode and add DATM CPLHIST topo capability

This PR has several features:
1) unifies the CPLHIST naming convention across the components by
   adding the following new xml variables in DATM, DLND and DOCN
      `DATM_CPLHIST_DOMAIN_FILE, DLND_CPLHIST_DOMAIN_FILE, DROF_CPLHIST_DOMAIN_FILE`
   These new xml variables are the full pathname for domain file
   for datm, dlnd and drof when the corresponding data model mode
   is set to CPLHIST.
   NOTE: if any of these xml variables set to 'null',
   then domain information is read in from the first coupler
   history file in the target stream.
   NOTE: it is assumed that when `DXXX_CPLHIST_DOMAIN_FILE='null'`
   that the first coupler stream file that is pointed
   to contains the domain information for that stream.
   NOTE: This is the default mode that should be used when the data model
   `DXXX_MODE is CPLHIST`.
2) puts in new capability for DATM CPLHIST mode to read in topo data
3) replaces % formatting in the data models with new .format()
4) address issue #1877
5) replaced `xxx_mode (e.g. atm_mode) `variables in dxxx_comp_mod.F90 and dxxx_shr_mod.F90 with `datamode `- to reduce confusion.

Additional testing:
Verified that using this CIME branch to replace cime/ in cesm2_0_alpha07d,
the following cases ran successfully on cheyenne with data that was already there:

```
1850_DATM%CPLHIST_CLM50%BGC_SICE_SOCN_MOSART_CISM2%NOEVOLVE_SWAV (f09_f09_mg17)
   the following xmlchanges neededed to be made:
   ./xmlchange DATM_CPLHIST_DOMAIN_FILE=null
   ./xmlchange DATM_CPLHIST_DIR=/glade/p/cesm/bgcwg_dev/forcing/b.e20.B1850.f09_g17.pi_control.all.179.cplhist/cpl/hist.mon
   ./xmlchange DATM_CPLHIST_CASE=b.e20.B1850.f09_g17.pi_control.all.179.cplhist
   ./xmlchange DATM_CPLHIST_YR_ALIGN=1
   ./xmlchange DATM_CPLHIST_YR_START=37
   ./xmlchange DATM_CPLHIST_YR_END=37
```
```
1850_DATM%CPLHIST_SLND_CICE_POP2%ECO_DROF%CPLHIST_SGLC_WW3 (f09_g17)
   the following xmlchange commands needed to be run:
   ./xmlchange DATM_CPLHIST_DOMAIN_FILE=null
   ./xmlchange DATM_CPLHIST_DIR=/glade/p/cesm/bgcwg_dev/forcing/b.e20.B1850.f09_g17.pi_control.all.179.cplhist/cpl/hist.mon
   ./xmlchange DATM_CPLHIST_CASE=b.e20.B1850.f09_g17.pi_control.all.179.cplhist
   ./xmlchange DATM_CPLHIST_YR_ALIGN=1
   ./xmlchange DATM_CPLHIST_YR_START=37
   ./xmlchange DATM_CPLHIST_YR_END=37
   ./xmlchange DROF_CPLHIST_DOMAIN_FILE=null
   ./xmlchange DROF_CPLHIST_DIR=/glade/p/cesm/bgcwg_dev/forcing/b.e20.B1850.f09_g17.pi_control.all.179.cplhist/cpl/hist.mon
   ./xmlchange DROF_CPLHIST_CASE=b.e20.B1850.f09_g17.pi_control.all.179.cplhist
   ./xmlchange DROF_CPLHIST_YR_ALIGN=1
   ./xmlchange DROF_CPLHIST_YR_START=37
   ./xmlchange DROF_CPLHIST_YR_END=37

```
```
1850_SATM_DLND%SCPL_SICE_SOCN_SROF_CISM2%EVOLVE_SWAV (f09_g16_gl20)
    no xmlchange commands were needed since in this case we have
      DLND_CPLHIST_DOMAIN_FILE" value="$LND_DOMAIN_PATH/$LND_DOMAIN_FILE"
    which is obtained from the config_grids.xml file

```
Test suite: scripts_regression_tests
Test baseline: did not compare against baselines
Test namelist changes: None
Test status: should be bfb

Fixes #1877 
Fixes #1407 

User interface changes?: added new xml variables discussed above
Update gh-pages html (Y/N)?: Y
Code review: Jim Edwards, Bill Sacks

doc/source/data_models/data-atm.rst

@@ -4,17 +4,17 @@ 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.
-In the case of CESM, these would be: CLM (I compset), POP2 (C compset), and POP2/CICE (G compset). 
+In the case of CESM, these would be: CLM (I compset), POP2 (C compset), and POP2/CICE (G compset).
 As a result, DATM variable settings are specific to the compset that will be targeted.
-As examples, CORE2_NYF (CORE2 normal year forcing) is the DATM mode used in C and G compsets. 
+As examples, CORE2_NYF (CORE2 normal year forcing) is the DATM mode used in C and G compsets.
 CLM_QIAN, CLMCRUNCEP, CLMGSWP3 and CLM1PT are DATM modes using observational data for forcing CLM in I compsets.
 
 .. _datm-xml-vars:
 
 ------------------
 xml variables
 ------------------
-The following are ``$CASEROOT`` xml variables that CIME supports for DATM.  
+The following are ``$CASEROOT`` xml variables that CIME supports for DATM.
 These variables are defined in ``$CIMEROOT/src/components/data_comps/datm/cime_config/config_component.xml``.
 These variables will appear in ``env_run.xml`` and the resulting values are compset dependent.
 
@@ -24,42 +24,47 @@ These variables will appear in ``env_run.xml`` and the resulting values are comp
    :header: "xml variable", "description"
    :widths: 20, 80
 
-   "DATM_MODE",             "Mode for atmospheric component" 
-   "",                      "Valid values are: CORE2_NYF,CORE2_IAF,CLM_QIAN,CLM_QIAN_WISO,CLM1PT,CLMCRUNCEP,"
-   "",                      "CLMCRUNCEP_V5,CLMGSWP3,WW3,CPLHISTForcing"       
-   "DATM_PRESAERO",         "Prescribed aerosol forcing, if any"
-   "DATM_TOPO",             "Surface topography"
-   "DATM_CO2_TSERIES",      "CO2 time series type"
-   "DATM_CPLHIST_CASE",     "Coupler history data mode case name" 
-   "DATM_CPLHIST_DIR",      "Coupler history data mode directory containing coupler history data" 
-   "DATM_CPLHIST_YR_ALIGN", "Coupler history data model simulation year corresponding to data starting year" 
-   "DATM_CPLHIST_YR_START", "Coupler history data model starting year to loop data over" 
-   "DATM_CPLHIST_YR_END",   "Coupler history data model ending year to loop data over" 
-   "DATM_CLMNCEP_YR_ALIGN", "I compsets only - simulation year corresponding to data starting year" 
-   "DATM_CPLHIST_YR_START", "I compsets only - data model starting year to loop data over" 
-   "DATM_CPLHIST_YR_END",   "I compsets only - data model ending year to loop data over" 
+   "DATM_MODE",                "Mode for atmospheric component"
+   "",                         "Valid values are: CORE2_NYF,CORE2_IAF,CLM_QIAN,CLM_QIAN_WISO,CLM1PT,CLMCRUNCEP,"
+   "",                         "CLMCRUNCEP_V5,CLMGSWP3,WW3,CPLHIST"
+
+   "DATM_PRESAERO",            "Optional prescribed aerosol forcing"
+   "DATM_TOPO",                "Optional Surface topography"
+   "DATM_CO2_TSERIES",         "Optional CO2 time series type"
+
+   "DATM_CPLHIST_DOMAIN_FILE", "Coupler history forcing data mode - full pathname of model domain file "
+   "DATM_CPLHIST_CASE",        "Coupler history forcing data mode - case name"
+   "DATM_CPLHIST_DIR",         "Coupler history forcing data mode - directory containing coupler history data"
+   "DATM_CPLHIST_YR_ALIGN",    "Coupler history forcing data mode - simulation year corresponding to DATM_CPLHIST_YR_START"
+   "DATM_CPLHIST_YR_START",    "Coupler history forcing data mode - starting year to loop data over"
+   "DATM_CPLHIST_YR_END",      "Coupler history forcing data mode - ending year to loop data over"
+
+   "DATM_CLMNCEP_YR_ALIGN",    "I compsets only - simulation year corresponding to data starting year"
+   "DATM_CLMNCEP_YR_START",    "I compsets only - data model starting year to loop data over"
+   "DATM_CLMNCEP_YR_END",      "I compsets only - data model ending year to loop data over"
+
+.. note:: If ``DATM_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 ``ATM_DOMAIN_PATH`` and ``ATM_DOMAIN_FILE`` are ignored and a valid setting **must be given** for ``DATM_CPLHIST_DOMAIN_FILE``. If ``DATM_CPLHIST_DOMAIN_FILE`` is set to ``null``, then the datm 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 that should be used for this mode. Alternatively, ``DATM_CPLHIST_DOMAIN_FILE`` can be set to ``$ATM_DOMAIN_PATH/$ATM_DOMAIN_FILE`` in a non-default configuration.
 
 .. _datm-datamodes:
 
 --------------------
 datamode values
 --------------------
 
-The xml variable ``DATM_MODE`` sets the streams that are associated with DATM and also sets 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`` 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 following are the supported DATM datamode values and their relationship to the ``$DATM_MODE`` xml variable value.
+The following are the supported DATM ``datamode`` values and their relationship to the ``$DATM_MODE`` xml variable value.
 
 .. 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. " 
-   "CPLHIST","Uilize user-generated coupler history data to spin up prognostic component. Works exactly like COPYALL."
-   "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 CCSM flux coupler and data models to do active-land-only simulations."
+   "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."
 
@@ -102,9 +107,9 @@ The following tabe describes the valid values of ``DATM_MODE``, and how it relat
    "CLM1PT", "single point tower site atm input data"
    "","streams: CLM1PT.$ATM_GRID"
    "","datamode: CLMNCEP"
-   "CPLHISTForcing","user generated forcing data to spinup for I and G compsets"
-   "","streams: CPLHISTForcingForOcnIce.Solar,CPLHISTForcingForOcnIce.nonSolarFlux,"
-   "","CPLHISTForcingForOcnIce.State3hr,CPLHISTForcingForOcnIce.State1hr"
+   "CPLHIST","user generated forcing data from using coupler history files used to spinup relevant prognostic components (for CESM this is CLM, POP and CISM)"
+   "","streams: CPLHISTForcing.Solar,CPLHISTForcing.nonSolarFlux,"
+   "","CPLHISTForcing.State3hr,CPLHISTForcing.State1hr"
    "","datamode: CPLHIST"
    "WW3","WW3 wave watch data from a short period of hi WW3 wave watch data from a short period of hi temporal frequency COREv2 data"
    "","streams: WW3"
@@ -114,7 +119,7 @@ The following tabe describes the valid values of ``DATM_MODE``, and how it relat
 Namelists
 --------------
 
-The DATM namelist file is ``datm_in`` (or ``datm_in_NNN`` for multiple instances). DATM namelists can be separated into two groups: *stream-independent* namelist variables that are specific to the DATM model and *stream-specific* namelist variables whose names are common to all the data models. 
+The DATM namelist file is ``datm_in`` (or ``datm_in_NNN`` for multiple instances). DATM namelists can be separated into two groups: *stream-independent* namelist variables that are specific to the DATM model and *stream-specific* namelist variables whose names are common to all the data models.
 
 Stream dependent input is in the namelist group ``"shr_strdata_nml`` which is discussed in :ref:`input streams <input-streams>` and is the same for all data models.
 
@@ -126,17 +131,17 @@ The stream-independent group is ``datm_nml`` and the DATM stream-independent nam
 datm_nml vars          description
 =====================  =============================================================================================
 decomp                 decomposition strategy (1d, root)
-    
+
                        1d => vector decomposition, root => run on master task
-restfilm               master restart filename 
-restfils               stream restart filename 
+restfilm               master restart filename
+restfils               stream restart filename
 force_prognostic_true  TRUE => force prognostic behavior
 bias_correct           if set, include bias correction streams in namelist
 anomaly_forcing        if set, includ anomaly forcing streams in namelist
-factorfn               filename containing correction factors for use in CORE2 modes (CORE2_IAF and CORE2_NYF) 
-presaero               if true, prescribed aerosols are sent from datm 
+factorfn               filename containing correction factors for use in CORE2 modes (CORE2_IAF and CORE2_NYF)
+presaero               if true, prescribed aerosols are sent from datm
 iradsw                 frequency to update radiation in number of time steps (of hours if negative)
-wiso_datm              if true, turn on water isotopes   
+wiso_datm              if true, turn on water isotopes
 =====================  =============================================================================================
 
 .. _datm-mode-independent-streams:
@@ -145,23 +150,23 @@ wiso_datm              if true, turn on water isotopes
 Streams independent of DATM_MODE value
 ------------------------------------------
 
-In general, each ``DATM_MODE`` xml variable is identified with a unique set of streams. 
+In general, each ``DATM_MODE`` xml variable is identified with a unique set of streams.
 However, there are several streams in DATM that can accompany any ``DATM_MODE`` setting.
 Currently, these are streams associated with prescribed aerosols, co2 time series, topography, anomoly forcing and bias correction.
 These mode-independent streams are activated different, depending on the stream.
 
 - ``prescribed aerosol stream:``
-  To add this stream, set ``$DATM_PRESAERO`` to a supported value other than ``none``. 
+  To add this stream, set ``$DATM_PRESAERO`` to a supported value other than ``none``.
 
 - ``co2 time series stream``:
   To add this stream, set ``$DATM_CO2_TSERIES`` to a supported value other than ``none``.
-  
+
 - ``topo stream``:
   To add this stream, set ``$DATM_TOPO`` to a supported value other than ``none``.
 
 - ``anomaly forcing stream:``
   To add this stream, you need to add any of the following keywword/value pair to the end of ``user_nl_datm``:
-  ::  
+  ::
 
     Anomaly.Forcing.Precip = <filename>
     Anomaly.Forcing.Temperature = <filename>
@@ -174,7 +179,7 @@ These mode-independent streams are activated different, depending on the stream.
 
 - ``bias_correct stream:``
   To add this stream, you need to add any of the following keywword/value pair to the end of ``user_nl_datm``:
-  ::  
+  ::
 
    BC.QIAN.CMAP.Precip = <filename>
    BC.QIAN.GPCP.Precip = <filename>
@@ -270,7 +275,3 @@ In general, the stream input file should translate the stream input variable nam
     "snowl_HDO", "Faxa_snowl_HDO"
     "shum_16O",  "Sa_shum_16O"
     "shum_18O",  "Sa_shum_18O"
-
-
-
-