#

## Data Model Science Modes

When a given data models 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 computed using data read in from input files

- that fields be computed using from 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). 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, and dicn, 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.

`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.

## Data Atmosphere Model

### Namelists

DATM namelists can be separated into two groups, stream-independent namelist variables that are specific to the DATM model and stream-specific namelist variables that are contained in share code and whose names are common to all the data models.

For stream-independent input, the namelist input filename is hardwired in the data model code to "datm_in" (or datm_in_NNNN for multiple instances) and the namelist group is called "datm_nml". The variable formats are character string (char), integer (int), double precision real (r8), or logical (log) or one dimensional arrays of any of those things (array of ...).

For stream-dependent input, the namelist input file is datm_atm_in (or datm_atm_in_NNNN for multiple instances) and the namelist group is "shr_strdata_nml". One of the variables in shr_strdata_nml is the datamode value. The mode is selected by a character string set in the strdata namelist variable dataMode. Each data model has a unique set of datamode values that it supports. Those for DATM are listed in detail in the datamode definition.

### Fields

The pre-defined internal field names in the data atmosphere model are as follows. In general, the stream input file should translate the input variable names into these names for use within the data atmosphere model.

         (/"z               ","u               ","v               ","tbot            ", &
           "ptem            ","shum            ","dens            ","pbot            ", &
           "pslv            ","lwdn            ","rainc           ","rainl           ", &
           "snowc           ","snowl           ","swndr           ","swvdr           ", &
           "swndf           ","swvdf           ","swnet           ","co2prog         ", &
           "co2diag         ","bcphidry        ","bcphodry        ","bcphiwet        ", &
           "ocphidry        ","ocphodry        ","ocphiwet        ","dstwet1         ", &
           "dstwet2         ","dstwet3         ","dstwet4         ","dstdry1         ", &
           "dstdry2         ","dstdry3         ","dstdry4         ",                    &
           "tref            ","qref            ","avsdr           ","anidr           ", &
           "avsdf           ","anidf           ","ts              ","to              ", &
           "snowhl          ","lfrac           ","ifrac           ","ofrac           ", &
           "taux            ","tauy            ","lat             ","sen             ", &
           "lwup            ","evap            ","co2lnd          ","co2ocn          ", &
           "dms             "                                                          /)

## Data Land Model

### Namelists

The land model is unique because it supports land data and snow data (lnd and sno) almost as if they were two separate components, but they are in fact running in one component model through one interface. The lnd (land) data consist of fields sent to the atmosphere. This set of data is used when running dlnd with an active atmosphere. In general this is not a mode that is used or supported in CESM1.1. The sno (snow) data consist of fields sent to the glacier model. This set of data is used when running dlnd with an active glacier model (TG compsets). Both sets of data are assumed to be on the same grid.

DLND namelists can be separated into two groups, stream-independent namelist variables that are specific to the DLND model and stream-specific namelist variables that are contained in share code and whose names are common to all the data models.

For stream-independent input, the namelist input filename is hardwired in the data model code to "dlnd_in" (or dlnd_in_NNNN for multiple instances) and the namelist group is called "dlnd_nml". The variable formats are character string (char), integer (int), double precision real (r8), or logical (log) or one dimensional arrays of any of those things (array of ...).

For stream-dependent input, the namelist input file is `dlnd_lnd_in` and

`dlnd_sno_in` (or `dlnd_lnd_in_NNNN` and `dlnd_sno_in_NNNN` for NNNN multiple instances) and the namelist group is "shr_strdata_nml". One of the variables in shr_strdata_nml is the datamode value. The mode is selected by a character string set in the strdata namelist variable dataMode. Each data model has a unique set of datamode values that it supports. Those for DLND are listed in detail in the datamode definition.

If you want to change the namelist settings in `dlnd_lnd_in` or `dlnd_in` you should edit the file `user_nl_dlnd`. If you want to change the namelist settings in `dsno_lnd_in` or `dsno_in` you should edit the file `user_nl_dsno`.

### Fields

The pre-defined internal field names in the data land model are as follows. In general, the stream input file should translate the input variable names into these names for use within the data land model.

         (/ "t           ","tref        ","qref        ","avsdr       ","anidr       ", &
            "avsdf       ","anidf       ","snowh       ","taux        ","tauy        ", &
            "lat         ","sen         ","lwup        ","evap        ","swnet       ", &
            "lfrac       ","fv          ","ram1        ",                               &
            "flddst1     ","flxdst2     ","flxdst3     ","flxdst4     ",                &
            "tsrf01      ","topo01      ","tsrf02      ","topo02      ","tsrf03      ", &
            "topo03      ","tsrf04      ","topo04      ","tsrf05      ","topo05      ", &
            "tsrf06      ","topo06      ","tsrf07      ","topo07      ","tsrf08      ", &
            "topo08      ","tsrf09      ","topo09      ","tsrf10      ","topo10      ", &
            "qice01      ","qice02      ","qice03      ","qice04      ","qice05      ", &
            "qice06      ","qice07      ","qice08      ","qice09      ","qice10      "  /)

## Data River Runoff Model

### Namelists

The data river runoff model is new and is effectively the runoff part of the dlnd model in CESM1.0 that has been made its own top level component.

DROF namelists can be separated into two groups, stream-independent namelist variables that are specific to the DROF model and stream-specific namelist variables that are contained in share code and whose names are common to all the data models.

For stream-independent input, the namelist input filename is hardwired in the data model code to "drof_in" (or drof_in_NNNN for multiple instances) and the namelist group is called "drof_nml". The variable formats are character string (char), integer (int), double precision real (r8), or logical (log) or one dimensional arrays of any of those things (array of ...).

For stream-dependent input, the namelist input file is "drof_lnd_in" (or drof_rof_in_NNNN for NNNN multiple instances) and the namelist group is "shr_strdata_nml". One of the variables in shr_strdata_nml is the datamode value. The mode is selected by a character string set in the strdata namelist variable dataMode. Each data model has a unique set of datamode values that it supports. Those for DROF are listed in detail in the datamode definition.

### Fields

The pre-defined internal field names in the data river runoff model are as follows. In general, the stream input file should translate the input variable names into these names for use within the data river runoff model.

         (/ "roff        ","ioff        "/)

## Data Ocean Model

### Namelists

DOCN namelists can be separated into two groups, stream-independent namelist variables that are specific to the DATM model and stream-specific namelist variables that are contained in share code and whose names are common to all the data models.

For stream-independent input, the namelist input filename is hardwired in the data model code to "docn_in" (or docn_in_NNNN for multiple instances) and the namelist group is called "docn_nml". The variable formats are character string (char), integer (int), double precision real (r8), or logical (log) or one dimensional arrays of any of those things (array of ...).

For stream-dependent input, the namelist input file is docn_ocn_in (or docn_ocn_in_NNNN for multiple instances) and the namelist group is "shr_strdata_nml". One of the variables in shr_strdata_nml is the datamode value. The mode is selected by a character string set in the strdata namelist variable dataMode. Each data model has a unique set of datamode values that it supports. Those for DOCN are listed in detail in the datamode definition. As part of the stream independent namelist input, DOCN supports two science modes, "SSTDATA" and "SOM". 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 this mode no longer runs out of the box, the default testing 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 or use one of the standard SOM forcing files from the CESM control runs. Some of these are available in the inputdata repository. The user then edits the DOCN_SOM_FILENAME variable in env_run.xml to point to the appropriate SOM forcing dataset. A tool is available to derive valid SOM forcing. More information on creating the SOM forcing is also available.

### Fields

The pre-defined internal field names in the data ocean model are as follows. In general, the stream input file should translate the input variable names into these names for use within the data ocean model.

         (/ "ifrac       ","pslv        ","duu10n      ","taux        ","tauy        ", &
            "swnet       ","lat         ","sen         ","lwup        ","lwdn        ", &
            "melth       ","salt        ","prec        ","snow        ","rain        ", &
            "evap        ","meltw       ","roff        ","ioff        ",                &
            "t           ","u           ","v           ","dhdx        ","dhdy        ", &
            "s           ","q           ","h           ","qbot        "                 /)

## Data Ice Model

### Namelists

DICE namelists can be separated into two groups, stream-independent namelist variables that are specific to the DATM model and stream-specific namelist variables that are contained in share code and whose names are common to all the data models.

For stream-independent input, the namelist input filename is hardwired in the data model code to "dice_in" (or dice_in_NNNN for multiple instances) and the namelist group is called "dice_nml".

Its important to point out that the only currently supported datamode that is not "NULL" or "COPYALL" is "SSTDATA", which is a prognostic mode and therefore requires data be sent to the ice model. Ice fraction (extent) data is read from an input stream, atmosphere state variables are received from the coupler, and then an atmosphere-ice surface flux is computed and sent to the coupler. It is called "SSTDATA" mode because 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.

### Fields

The pre-defined internal field names in the data ice model are as follows. In general, the stream input file should translate the input variable names into these names for use within the data ocean model.

         (/"to              ","s               ","uo              ","vo              ", &
           "dhdx            ","dhdy            ","q               ","z               ", &
           "ua              ","va              ","ptem            ","tbot            ", &
           "shum            ","dens            ","swndr           ","swvdr           ", &
           "swndf           ","swvdf           ","lwdn            ","rain            ", &
           "snow            ","t               ","tref            ","qref            ", &
           "ifrac           ","avsdr           ","anidr           ","avsdf           ", &
           "anidf           ","tauxa           ","tauya           ","lat             ", &
           "sen             ","lwup            ","evap            ","swnet           ", &
           "swpen           ","melth           ","meltw           ","salt            ", &
           "tauxo           ","tauyo           " /)

## Data Land-Ice Model

This model does not yet exist.