6. 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). 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. CLM_QIAN, CLMCRUNCEP, CLMGSWP3 and CLM1PT are DATM modes using observational data for forcing CLM in I compsets.
6.1. xml variables¶
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.
Note
These xml variables are used by the the datm’s cime_config/buildnml script in conjunction with datm’s cime_config/namelist_definition_datm.xml file to generate the namelist file datm_in
.
xml variable |
description |
---|---|
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,CORE_IAF_JRA |
|
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.
6.2. datamode values¶
The xml variable DATM_MODE
(described in DATM_MODE, datamode and streams) 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.
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
.
datamode variable |
description |
---|---|
NULL |
This mode turns off the data model as a provider of data to the coupler. The |
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 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. |
CORE_IAF_JRA |
In conjunction with JRA-55 Project, provides the atmosphere forcing when coupling an active ocean model with observed atmospheric forcing. This mode and associated data sets implement the JRA-55 v1.3 forcing data. |
6.3. DATM_MODE, datamode and streams¶
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.
DATM_MODE |
description-streams-datamode |
---|---|
NULL |
null mode |
streams: none |
|
datamode: NULL |
|
CORE2_NYF |
CORE2 normal year forcing (C ang G compsets) |
streams: CORE2_NYF.GISS,CORE2_NYF.GXGXS,CORE2_NYF.NCEP |
|
datamode: CORE2_NYF |
|
CORE2_IAF |
CORE2 interannual year forcing (C ang G compsets) |
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 |
JRA-55 intra-annual year forcing(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 |
QIAN atm input data with water isotopes (I compsets) |
streams: CLM_QIAN_WISO.Solar,CLM_QIAN_WISO.Precip,CLM_QIAN_WISO.TPQW |
|
datamode: CLMNCEP |
|
CLM_QIAN |
QIAN atm input data (I compsets) |
streams: CLM_QIAN.Solar,CLM_QIAN.Precip,CLM_QIAN.TPQW |
|
datamode: CLMNCEP |
|
CLMCRUNCEP |
CRUNCEP atm input data (I compsets) |
streams: CLMCRUNCEP.Solar,CLMCRUNCEP.Precip,CLMCRUNCEP.TPQW |
|
datamode: CLMNCEP |
|
CLMCRUNCEP_V5 |
CRUNCEP atm input data (I compsets) |
streams: CLMCRUNCEP_V5.Solar,CLMCRUNCEP_V5.Precip,CLMCRUNCEP_V5.TPQW |
|
datamode: CLMNCEP |
|
CLMGSWP3 |
GSWP3 atm input data (I compsets) |
streams: CLMGSWP3.Solar,CLMGSWP3.Precip,CLMGSWP3.TPQW |
|
datamode: CLMNCEP |
|
CLM1PT |
single point tower site atm input data |
streams: CLM1PT.$ATM_GRID |
|
datamode: CLMNCEP |
|
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 |
|
datamode: COPYALL |
6.4. 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.
Stream dependent input is in the namelist group "shr_strdata_nml
which is discussed in input streams and is the same for all data models.
The stream-independent group is datm_nml
and the DATM stream-independent namelist variables are:
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 |
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 |
iradsw |
frequency to update radiation in number of time steps (of hours if negative) |
wiso_datm |
if true, turn on water isotopes |
6.5. Streams independent of DATM_MODE value¶
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 thannone
.co2 time series stream
: To add this stream, set$DATM_CO2_TSERIES
to a supported value other thannone
.topo stream
: To add this stream, set$DATM_TOPO
to a supported value other thannone
.anomaly forcing stream:
To add this stream, you need to add any of the following keywword/value pair to the end ofuser_nl_datm
:Anomaly.Forcing.Precip = <filename> Anomaly.Forcing.Temperature = <filename> Anomaly.Forcing.Pressure = <filename> Anomaly.Forcing.Humidity = <filename> Anomaly.Forcing.Uwind = <filename> Anomaly.Forcing.Vwind = <filename> Anomaly.Forcing.Shortwave = <filename> Anomaly.Forcing.Longwave = <filename>
bias_correct stream:
To add this stream, you need to add any of the following keywword/value pair to the end ofuser_nl_datm
:BC.QIAN.CMAP.Precip = <filename> BC.QIAN.GPCP.Precip = <filename> BC.CRUNCEP.CMAP.Precip = <filename> BC.CRUNCEP.GPCP.Precip = <filename>
6.6. DATM Field names¶
DATM defines a set of pre-defined internal field names as well as mappings for how those field names map to the fields sent to the coupler.
In general, the stream input file should translate the stream input variable names into the datm_fld
names for use within the data atmosphere model.
datm_fld (avifld) |
driver_fld (avofld) |
---|---|
z |
Sa_z |
topo |
Sa_topo |
u |
Sa_u |
v |
Sa_v |
tbot |
Sa_tbot |
ptem |
Sa_ptem |
shum |
Sa_shum |
dens |
Sa_dens |
pbot |
Sa_pbot |
pslv |
Sa_pslv |
lwdn |
Faxa_lwdn |
rainc |
Faxa_rainc |
rainl |
Faxa_rainl |
snowc |
Faxa_snowc |
snowl |
Faxa_snowl |
swndr |
Faxa_swndr |
swvdr |
Faxa_swvdr |
swndf |
Faxa_swndf |
swvdf |
Faxa_swvdf |
swnet |
Faxa_swnet |
co2prog |
Sa_co2prog |
co2diag |
Sa_co2diag |
bcphidry |
Faxa_bcphidry |
bcphodry |
Faxa_bcphodry |
bcphiwet |
Faxa_bcphiwet |
ocphidry |
Faxa_ocphidry |
ocphodry |
Faxa_ocphodry |
ocphiwet |
Faxa_ocphiwet |
dstwet1 |
Faxa_dstwet1 |
dstwet2 |
Faxa_dstwet2 |
dstwet3 |
Faxa_dstwet3 |
dstwet4 |
Faxa_dstwet4 |
dstdry1 |
Faxa_dstdry1 |
dstdry2 |
Faxa_dstdry2 |
dstdry3 |
Faxa_dstdry3 |
dstdry4 |
Faxa_dstdry4 |
tref |
Sx_tref |
qref |
Sx_qref |
avsdr |
Sx_avsdr |
anidr |
Sx_anidr |
avsdf |
Sx_avsdf |
anidf |
Sx_anidf |
ts |
Sx_t |
to |
So_t |
snowhl |
Sl_snowh |
lfrac |
Sf_lfrac |
ifrac |
Sf_ifrac |
ofrac |
Sf_ofrac |
taux |
Faxx_taux |
tauy |
Faxx_tauy |
lat |
Faxx_lat |
sen |
Faxx_sen |
lwup |
Faxx_lwup |
evap |
Faxx_evap |
co2lnd |
Fall_fco2_lnd |
co2ocn |
Faoo_fco2_ocn |
dms |
Faoo_fdms_ocn |
precsf |
Sa_precsf |
prec_af |
Sa_prec_af |
u_af |
Sa_u_af |
v_af |
Sa_v_af |
tbot_af |
Sa_tbot_af |
pbot_af |
Sa_pbot_af |
shum_af |
Sa_shum_af |
swdn_af |
Sa_swdn_af |
lwdn_af |
Sa_lwdn_af |
rainc_18O |
Faxa_rainc_18O |
rainc_HDO |
Faxa_rainc_HDO |
rainl_18O |
Faxa_rainl_18O |
rainl_HDO |
Faxa_rainl_HDO |
snowc_18O |
Faxa_snowc_18O |
snowc_HDO |
Faxa_snowc_HDO |
snowl_18O |
Faxa_snowl_18O |
snowl_HDO |
Faxa_snowl_HDO |
shum_16O |
Sa_shum_16O |
shum_18O |
Sa_shum_18O |