To some extent, the behavior of the Coupler can be specified or modified at run time. This is done almost exclusively through the use of an F90 namelist. This section contains a list and description of available namelist input parameters. The Coupler reads an input namelist, called inparm, from stdin, at runtime.
Coupler input variables follow a naming convention in which the first few
letters of the variable identify a basic functionality group:
* case_xxx selects options with respect to specifying a case name and
description
* rest_xxx selects options with respect to the creation or retrieval of
restart files and to specify related initial conditions.
* stop_xxx selects options with respect to when a simulation will stop
* hist_xxx selects options with respect to when and what type of
history data is created
* diag_xxx selects options with respect to run-time diagnostics of the
physical simulation,
* flx_xxx selects options with respect to flux calculation specifics
* orb_xxx selects options with respect to solar orbit calculations
* mss_xxx selects options with respect to data file archival (in the past
this meant using NCAR's Mass Storage System, the "MSS")
* info_xxx selects options with respect to monitoring the progress or
computational performance of the model
The following list of input namelist parameters includes this information:
* Type: the variable's data type.
Notes:
o some character strings have length = CLONG. "CLONG" is a single global
constant used throughout the Coupler to define a "long" character string.
The CLONG is hardcoded to be 256.
o "integer boolean" means an integer such that a value of zero is
interpreted as "false", and any non-zero value is interpreted as "true".
* Default: the default value of the variable. While reasonable default values
are selected when possible, users might want to alter these values
according to their application.
* Required: tells if and when the variable is required input. Very few
input parameters are required. In a few cases, changing one default value
will cause other input parameters to become required.
* Description: a brief description of the purpose and effect of the
parameter.
* Example: a reference to an example namelist which uses the variable
(examples follow this list).
case_name
Type: character(len=CLONG)
Default: "null"
Required: no, but highly recommended
Description: This is the case name text string which is used to create
output file names and is also included in output files to help identify the
model run. Generally this should be a short string (eg. 8 chars) and
contain only those characters that are valid in unix file names.
See Example: 1, 2, 3, 4
case_desc
Type: character(len=CLONG)
Default: "null"
Required: no, but highly recommended
Description: This is a short text string (typically less than 80 chars)
which is included in output files to help identify the model run.
See Example: 1, 2, 3, 4
rest_type
Type: character(len=32)
Default: "startup"
Required: no (but default is of limited usefulness)
Description: This selects the run type.
Valid choices are: "startup", "hybrid", "continue", or "branch".
Selecting "branch" makes rest_bfile a required input.
See Example: 1, 2, 3, 4
rest_pfile
Type: character(len=CLONG)
Default: "null"
Required: yes
Description: This is the complete path and name of the restart "pointer
file." This must include an existing, NFS mounted directory. All run
types will update this file (and create it, if necessary), but only a
continuation runs requires that this file exists prior to the start of
the run.
See Example: 1, 2, 3, 4
rest_bfile
Type: character(len=CLONG)
Default: "null"
Required: required if rest_type = "branch", ignored otherwise.
Description: This is the file name of the "branch file" (the IC data file).
Note that a prefix like "mss:" is used to indicate a file archival device,
Valid prefix options are:
* "cp:" or no-prefix indicates a normal unix file copy from an NFS mounted
file system.
* "mss:" indicates a file on NCAR's MSS
* "null:" indicates no archival -- the file name, stripped of any directory
information, indicates a file in the current working directory.
See Example: 4
rest_date
Type: integer
Default: 00000101 (year 0, month 1, day 1, encoded yyyymmdd)
Required: no (ignored for "continuation" runs, optional for others).
Description: This is the restart date.
* On startup and hybrid runs, rest_date is the initial date of the
simulation.
* On branch runs, if rest_date > 0, it will over-ride the date contained
in the rest_bfile IC restart file. Otherwise the date from the
rest_bfile data file is used.
* On continuation runs rest_date is not used (the date contained in the IC
file is used).
See Example: 1, 2
rest_freq
Type: character(len=32)
Default: "monthly"
Required: no
Description: This is the restart frequency which selects how often restart
data files are created. Options are:
* "yearly" => restart files on every January 1st
* "halfyear => restart files on every January 1st and July 1st
* "quarterly" => restart files on every January, April, July, & October 1st
* "monthly" => restart files on the 1st of every month
* "ndays" => restart files every n days
If rest_freq = "ndays", then namelist parameters rest_n and rest_odate are
involved (see below).
See Example: 4
rest_n
Type: integer
Default: 10
Required: no (only used if rest_freq = "ndays")
Description: If rest_freq = "ndays", restart files will be created
every n days. More specifically, whenever mod(d-p;n) = 0, where
d = the simulation day (1 Jan, year 1 <=> d = 365)
p = an offset such that mod(d-p;n) = 0 on the date specified by rest_odate
n = rest_n
See Example: 4
rest_odate
Type: integer
Default: 0
Required: no
Description: Selects restart file offset calendar date, used in
conjunction with rest_n when rest_freq = "ndays." If rest_odate > 0, it
must be a valid calendar date (encoded: yyyymmdd). Restart data is then
created every n days relative to (and including) either
* the initial date of the run (if rest_odate < 1)
* the date rest_odate (if rest_odate > 0)
stop_option
Type: character(len=16)
Default: "newyear"
Required: no
Description: Selects when to stop the simulation.
* "newdecade" => stop on the January 1st at the start of the next decade
* "newyear" => stop on the next January 1st
* "halfyear => stop on the next January 1st or July 1st
* "newmonth" => stop on the 1st of the next month
* "nmonths" => stop on day 1, n months from this month, where n=stop_n
* "ndays" => stop after advancing n days, where n=stop_n
* "date" => stop when stop_date is reached. This makes stop_date a
required input.
See Example: 1, 2, 3, 4
stop_n
Type: integer
Default: 0
Required: only if stop_option = "ndays" or "nmonths"
Description: If stop_option = "ndays", stop after advancing stop_n days.
If stop_option = "nmonths", stop on day 1, n months from this month.
See Example: 4
stop_date
Type: integer
Default: 00010101 (year 1, month 1, day 1)
Required: no (required if stop_option = "date", ignored otherwise)
Description: If stop_option = "date", stop on this date.
See Example: 2
hist_freq
Type: character(len=16)
Default: "never"
Required: no
Description: selects how often instantaneous history data is created:
* "yearly" => data is created on the 1st of each January
* "quarterly" => data is created on the 1st of January,April,July,October
* "monthly" => data is created on the 1st of each month
* "biweekly" => data is created on the 1st and 15th of each month
* "weekly" => data is created on the 1st, 8th, 15th, and 22nd of each
month
* "daily" => data is created every day
* "ndays" => history data is created every n days relative to a history
offset date specified by hist_odate.
* "nstep" => history data is created every n time steps relative to and
including the first time step of each day.
Note: history data is never created on a simulation stopping date, but
history data can be created on a simulation starting date.
See Example: 3
hist_n
Type: integer
Default: 1
Required: no (only used if hist_freq = "ndays" or "nstep")
Description: If hist_freq = "ndays" > 0, history files will be created
every n days. More specifically, whenever mod(d-p;n) = 0, where
d = the simulation day (1 Jan, year 1 <=> d = 365 )
n = hist_n
p = an offset such that mod(d-p;n) = 0 on the date specified by hist_odate
If hist_freq = "nstep" and hist_n > 0, history files will be created every
n time steps including the first time step of each day.
See Example: 3
hist_odate
Type: integer
Default: 1
Required: no (only used if hist_freq = "ndays")
Description: Selects history file offset calendar date, used in
conjunction with hist_n when hist_freq = "ndays". If hist_odate > 1, it
must be a valid calendar date (encoded: yyyymmdd). See hist_freq for usage.
History data is created every n days relative to (and including) either
* the initial date of the run, if hist_odate < 1
* the 1st of the every month , if hist_odate = 1
* the date hist_odate , if hist_odate > 1
See Example: 3
hist_bundle
Type: character(len=16)
Default: "null" (no bundling)
Required: no
Description: If hist_bundle is "daily", "monthly", "quarterly", or
"yearly", then instantaneous history data files will accumulate multiple
time samples until the next day, month, quarter, or year (respectively) is
encountered, then the data file will be closed and archived, and a new
history file will be created, and subsequent data will accumulate into this
new file. A history file's name indicates the date of the first time sample
in that file.
hist_tavg
Type: integer
Default: 1 (true)
Required: no
Description: If hist_tavg is true (non-zero), the Coupler will create
monthly average history data files and component models will be requested
to do the same. Time averaged data is not bundled (i.e. there is always
one set of monthly average fields per file).
diag_freq
Type: character(len=16)
Default: "never"
Required: no
Description: selects how often instantaneous diagnostic data is created:
* "never" => data is never created
* "yearly" => data is created on the 1st day of each year
* "quarterly" => data is created on the 1st day of each quarter
* "monthly" => data is created on the 1st of each month
* "biweekly" => data is created on the 1st and 15th of each month
* "weekly" => data is created on the 1st, 8th, 15th, and 22nd of each
month
* "ndays" => data is created every n days relative to an offset date
specified by diag_odate. See diag_n.
* "nstep" => data is created every n time steps, including the first
time step of each day. See diag_n.
Note: if diagnostics are being printed out on a given day, they are always
printed out when seconds = 0, 21600, 43200, and 64800 (ie. every six
hours). Seconds = 0 will always occur, but depending on what model
communication intervals are used, it may be that seconds never equals
21600, 43200, or 64800, and hence there may be as few as one printout per
day.
See Example: 3
diag_n
Type: integer
Default: 10
Required: no (only used if diag_freq = "ndays" or "nstep")
Description: If diag_freq = "ndays", diagnostic data will be created
every n days. More specifically, whenever mod(d-p;n) = 0, where
d = the simulation day (1 Jan, year 1 <=> d = 365 )
n = diag_n
p = an offset such that mod(d-p;n) = 0 on the date specified by diag_odate.
If diag_freq = "nstep", diagnostic data will be created every n time steps
including the first time step of each day.
diag_odate
Type: integer
Default: 1
Required: no (only used if diag_freq = "ndays")
Description: Selects diagnostic data offset calendar date, used in
conjunction with diag_n when diag_freq = "ndays". If diag_odate > 1, it
is a valid calendar date (encoded: yyyymmdd). See diag_freq for usage.
Diagnostic data is created every n days relative to (and including) either
* the initial date of the run (if hist_odate < 1)
* the 1st of the month (if hist_odate = 1)
* the date hist_odate (if hist_odate > 1)
flx_albav
Type: integer boolean
Default: 0 (false)
Required: no
Description: The Coupler computes ocean albedos and sometimes modifies
ice albedos.
* if flx_albav = true (non-zero), the ocean albedos are computed such that
they have no zenith angle dependence and ice albedos, which are computed
by the ice model, are unaltered.
* if flx_albav = false (zero), the ocean albedos are computed with a zenith
angle dependence and ice albedos are set to unity on the dark side of the
earth.
Typically flx_albav ("daily average albedos") is only turned on when the
atm component is a climatological data atm model that is sending daily
average data to the coupler, and thus "daily average albedos" are an
appropriate complement to the daily average solar fluxes sent by the
atm component.
flx_epbal
Type: character(len=16)
Default: "off"
Required: no
Description: Non-default values can be used to conserve globally integrated
salinity in ocn & ice components that are coupled to a climatological data
atm model. The conservation takes place by multiplying precipitation, P,
and runoff, R, by a single scalar (spatially constant) factor f to balance
evaporation, E: <E> + f<P> + f<R> = 0, where <x> denotes a globally
averaged value. There are three valid values for flx_epbal:
* "off" => no factor is applied to P + R
* "inst" => the Coupler computes a factor f so that <E> + f<P> + f<R> = 0
at each time step ("instantaneously").
* "ocn" => the ocn component provides the Coupler with a factor f and the
Coupler applies this factor to P and R. Typically this factor
is chosen, by the ocn component, so that <E> + f<P> + f<R> = ,
but perhaps not instantaneously, maybe as an annual average.
This can be used to allow some fluctuation in the global
average of salinity on shorter time scales while enforcing a
constant global average of salinity on longer time scales.
The ocn component is responsible for providing an appropriate
factor to the Coupler.
orb_year
Type: integer
Default: <none>
Required: yes
Description: This is the calendar year which is used to determine the
solar orbit and resulting solar angles. This is necessary, for example,
to compute ocn surface albedo, which may be zenith angle dependent.
Valid values are in the range [-1000000, +1000000].
A typical value might be 1990.
See Example: 1, 2, 3, 4
mss_dir
Type: character(len=CLONG)
Default: "null"
Required: yes
Description: This is a file archival directory name including the
specification of an archival device. Restart and history files go into
this directory. For continuation runs, the initial condition restart file
must also be in this directory. A "prefix" is all the characters up to
and including the first occurrence of ":". The prefix of the file
indicates a storage device. Valid prefix options are:
* "cp:" or no-prefix indicates a normal unix file copy to an NFS mounted
file system.
* "mss:" indicates archival onto NCAR's MSS
* "null:" indicates no archival of any sort.
Some of the following mss_xxx options are only meaningful when the
archival device is NCAR's MSS. With code modification, more archival
devices could be implemented (eg. "hpss:").
See Example: 1, 2, 3, 4
mss_opts
Type: character(len=64)
Default: "nowait, nomail"
Required: no
Description: Options used when data files are sent to NCAR's MSS.
This default request uses asynchronous data file transfer.
See the msrcp man pages at NCAR for more details.
See Example: 2
mss_pass
Type: character(len=16)
Default: " " (no password)
Required: no
Description: Mswrite write password string for files sent to the MSS.
Read passwords are not an option with the Coupler.
See the mswrite man pages at NCAR for more details.
See Example: 2
mss_rtpd
Type: integer
Default: 365
Required: no
Description: Retention period, in days, for data files sent to the MSS.
See the mswrite man pages at NCAR for more details.
See Example: 2
mss_rmlf
Type: integer boolean
Default: 0 (false)
Required: no
Description: "remove local file" after archival. True means local files
will be removed after they are archived. Note that the most recently
created file is never removed, but older files are.
WARNING: successful archival is not verified prior to removal.
WARNING: using a "null:" prefix for mss_dir and mss_rmlf = TRUE will
result in files being deleted but not archived.
See Example: 2
info_dbug
Type: integer
Default: 1
Required: no
Description: Debugging information level: 0, 1, 2, or 3.
* 0 => do not write any extra debugging information to stdout
* 1 => write a small amount of extra debugging information to stdout
* 2 => write a medium amount of extra debugging information to stdout
* 3 => write a large amount of extra debugging information to stdout
See Example: 3
info_time
Type: integer
Default: 0 (false)
Required: no (normally not recommended)
Description: If true (non-zero), write message passing timing info to
stdout.
nx_a,ny_a
nx_i,ny_i
nx_l,ny_l
nx_o,ny_o
Type: integer
Default: <none>
Required: yes
Description: the "i" and "j" 2d-resolution of the atmosphere, ice, land,
and ocean components, respectively. This is with respect to the data
fields that are sent and received from the Coupler.
See Example: 1, 2, 3, 4
Example 1: a "startup" run
$inparm
case_name = "test.01"
case_desc = "testing a startup run "
rest_type = "startup"
rest_pfile = "$HOME:/cpl.test.01.rpointer"
rest_date = 19800101
stop_option = "date"
stop_date = 19800701
orb_year = 1990
mss_dir = "null:/whatever"
nx_a = 128, ny_a = 64, nx_i = 192, ny_i = 94
nx_l = 128, ny_l = 64, nx_o = 192, ny_o = 94
/
Here the inputs specify a "startup" run starting on 1980 Jan 1st and stopping
on 1980 Jul 1st. No initial condition data is needed. A restart pointer file,
rest_pfile, will be created in the user's home directory. The restart pointer
file will contain the name of the most recently created restart file.
Restart and history files will not be archived in any way -- they will remain
in the current working directory.
History data files and restart files will be created at the default frequencies.
Solar orbit calculations will be based on the year 1990.
The "null:" prefix on mss_dir specifies that there will be no archival of
history and restart files -- the files will simply remain in the current
working directory. Presumably the output files will be archived later in some
post-processing phase.
Example 2: a "hybrid" run
$inparm
case_name = "test.01"
case_desc = "testing a hybrid run"
rest_type = "hybrid"
rest_pfile = "$HOME/cpl.test.01.rpointer"
rest_date = 19800101
stop_option = "date"
stop_date = 19800701
orb_year = 1990
mss_dir = "mss:/DOE/csm/test.01/cpl/ "
mss_rtpd = 730
mss_pass = "rosebud"
mss_opts = "nowait"
mss_rmlf = 1
nx_a = 128, ny_a = 64, nx_i = 192, ny_i = 94
nx_l = 128, ny_l = 64, nx_o = 192, ny_o = 94
/
As far as the Coupler is concerned, a "hybrid" run is the same as an
"initial" run. The distinction is for the benefit of other component models.
The stop options will cause the simulation to stop on a particular date, 1981
Aug 1st. The "mss:" prefix on mss_dir selects NCAR's MSS as the archival device
for output files. The mass store file retention period (2 years) and write
password ("rosebud") have been selected here. Files will be deleted after being
archived to the MSS (except that the most recently created file is always left
in the current working directory).
The resolution of the atm and lnd grids is 128x64.
The resolution of the ice and ocn grids is 192x94.
Example 3: a "continuation" run
$inparm
case_name = "test.01"
case_desc = "testing a continuation run "
rest_type = "continue"
rest_pfile = "$HOME/cpl.test.01.rpointer"
stop_option = "newyear"
hist_freq = "ndays"
hist_n = 10
hist_odate = 1
diag_freq = "monthly"
orb_year = 1990
mss_dir = "cp:~/test.01/cpl/ "
info_dbug = 0
nx_a = 128, ny_a = 64, nx_i = 192, ny_i = 94
nx_l = 128, ny_l = 64, nx_o = 192, ny_o = 94
/
Here the inputs specify a continuation run. Assuming this run continues from
where example 1 finished, this run will start on 1980 Jul 1st and stop on 1981
Jan 1st. Exactly where this run continues from is specified by the restart
file, and the restart file which will be used is specified by the restart
pointer file. Restart files will be created according to the default setting
of rest_freq. History data will be created every 10 days relative to the
1st day of each month, i.e. on the 1st, 11th, 21st, and 31st of every month.
Setting diag_freq = "monthly" signals the coupler to calculate some global
diagnostic information on the 1st of each month and write it to stdout. New
restart and history files will be archived by copying them into a subdirectory
of the user's home directory (~/test.01/cpl/). Setting info_dbug = 0 will
minimize the amount of debugging information written to stdout.
Example 4: a "branch" run
$inparm
case_name = "test.02"
case_desc = "testing a branch run "
rest_type = "branch"
rest_pfile = "$HOME/cpl.test.02.rpointer"
rest_bfile = "mss:/DOE/csm/test.01/cpl/test.01.cpl5.r.1981-01-01-00000 "
rest_freq = "ndays"
rest_n = 10
stop_option = "ndays"
stop_n = 31
orb_year = 1990
mss_dir = "~/test.01/cpl/ "
nx_a = 128, ny_a = 64, nx_i = 192, ny_i = 94
nx_l = 128, ny_l = 64, nx_o = 192, ny_o = 94
/
Here the input parameter rest_type specifies a branch run. The branch file
(/DOE/.../r1981-01-01) must be specified. Its prefix, "mss:", indicates that
it is found on NCAR's MSS. This initial condition file was created by a
previous simulation. The date from the branch file will be used (apparently
1981 Jan 1). The simulation will stop after advancing 31 days (1981 Feb 1).
Restart files will be created every 10 days relative to the start of the run.
The absence of a archival device prefix on mss_dir results in the same
behavior as a "cp:" prefix, i.e. history and restart files will be archived
by being copied to the NFS mounted directory specified by mss_dir.