4 Input Namelist Parameters

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 this namelist from a data file, called cpl.nml, at runtime.

Many of the Coupler namelist values are set as part of creating a case within CCSM (See the CCSM3 Users Guide). Most namelist variables which can be changed by the user within an already existing case are in the env_run file in the it $CASE directory. Remaining variables can be changed by editing Buildnml_Prestage/cpl.buildnml_prestage.csh in the $CASE directory.

4.1 Conventions

Coupler input variables follow a naming convention in which the first few letters of the variable identify a basic functionality group or ``event'':

* case_xxx

selects options with respect to specifying a case name and description

* start_xxx

selects options with respect to selecting restart files or the simulation start date.

* rest_xxx

selects options with respect to when restart files are created

* 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

* 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. Note: some character strings have length = CL. "CL" is a single global constant used throughout the Coupler to define a "long" character string. The CL is hard-coded to be 256. If necessary, a one line change to the source code will lengthen all such character variables.

Default:

the default value of the variable. While reasonable default values are selected when possible, generally users need to alter some of 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).

4.1.1 Generic periodic event specification.

Many namelist variables are used to specify periodic events such as restart file creation, history file creation, creation of diagnostics data, etc. All such periodic events are triggered by the same underlying calendar/clock/alarm functionality and thus they all have the same set of namelist variables. This general functionality and the related variables is described here, and then referred to below as necessary. <event> refers to one of the functional groups listed above (case start etc.).

• 
  

  <event>_option
  TYPE: character(len=32)
  DEFAULT: <varies, see the particular namelist variable>
  REQUIRED: <varies, see the particular namelist variable>
  DESCRIPTION: This is the option that selects how often an event will occur. When an event happens on a day, it happens at the start of the day.
  OPTIONS:

  "date"

  occurs only once, on the given date

  "daily"

  occurs every day

  "yearly"

  occurs on every January 1st

  "monthly"

  occurs on the 1st of every month

  "ndays"

  occurs every n days relative to an offset date

  "nmonths"

  occurs every n months relative to an offset date

  "never"

  never occurs

  EXAMPLES: start_option stop_option
  
  • 
    

    If <event>_option = "date" then namelist parameters <event>_date is required to specify the date (see below).

    If <event>_option = "ndays" or nmonths, then namelist parameters <event>_n and <event>_date are both required (see below), to specify n and the offset date, respectively.

  <event>_n
  TYPE: integer
  DEFAULT: <varies, see the particular namelist variable>
  REQUIRED: maybe, only used if event_option = "ndays" or "nmonths"
  DESCRIPTION:
  EXAMPLES: rest_n stop_n
  

  • 
    

    If <event>_option = "ndays", the event will occur every n days, where = <event>_n.

    If <event>_option = "nmonths", the event will occur every n months, where $n = event\_n$.

  But in either case, the exact timing of the event is not yet completely specified, one must specify an "offset date" (see below), such that an event occurs on the offset date and every n days (or n months) before or after the offset date. It is not necessary that a simulation ever encounters this offset date.
  There is a special case that occurs when, for example, event_option = "monthly", event_n = 1, event_date = 31. Apparently the event should occur on February 31st, a non-existent date. In such a case the event will occur on the last day of the month. Thus the events will occur on January 31st, February 28th, March 31st, April 30th, May 31st, etc.

  <event>_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION:
  EXAMPLES: start_date stop_date
  

  • 
    

    If <event>_option = "date", then this is the date when the event will occur.

    If <event>_option = "ndays" or "nmonths", then this is the offset date described above. This offset date must either be a valid calendar date, encoded: yyyymmdd, or, if $event\_date < 1$, the offset date is taken to be the starting date of the simulation (this is the default value).

4.2 List of Parameters

• 
  

  case_name
  TYPE: character(len=CL)
  DEFAULT: "unset"
  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. Because this variable is used to construct file names, it must contain only those characters that are valid in unix file names. While the name can be quite long, it is recommended that it be rather short, for example, 8 to 16 characters.
  See Example: 1, 2, 3

  case_desc
  TYPE: character(len=CL)
  DEFAULT: "unset"
  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

  start_type TYPE: character(len=16)
  DEFAULT: "initial"
  REQUIRED: no (but default is of limited usefulness)
  DESCRIPTION: This selects the run type. Valid choices are: "initial", "continue" or "branch. Selecting "branch" makes start_bfile a required input.
  See Example: 1, 2, 3

  start_pfile
  TYPE: character(len=CL)
  DEFAULT: $HOME/cpl6.<case_name>.rpointer or ./rpointer if case_name is unspecified.
  REQUIRED: no
  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 run requires that this file exists prior to the start of the run.
  See Example: 1, 2, 3

  start_bfile
  TYPE: character(len=CL)
  DEFAULT: "unset"
  REQUIRED: yes, if start_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: 3

  start_date
  TYPE: integer
  DEFAULT: 00010101 (January 1st, year 1, encoded yyyymmdd)
  REQUIRED: no (ignored for "continue" and "branch" runs)
  DESCRIPTION: This is the start date for "initial" runs

  On "inital" runs

  , start_date is the initial date of the simulation.

  On "branch" runs

  , the start date will be the date found in the start_bfile file, this is the IC/restart file.

  On "continue" runs

  , the start date will be the date found in the restart file.

  See Example: 1

  rest_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: This is the restart option that selects how often restart The generic periodic event specification (Sec. 4.1.1) applies to this option with the exception is that a restart file will never be created at the start of a run.
  See Example: 1, 2, 3

  rest_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if rest_option = "ndays" or "nmonths")
  DESCRIPTION: The generic periodic event specification (Sec. 4.1.1) applies to this option.
  See Example: 2

  rest_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec. 4.1.1) applies to this option.
  See Example: 3

  stop_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: This is the stop option that selects when the simulation The generic periodic event specification (Sec. 4.1.1 ) applies to this option with the exception that every run must be at least two days long. Also note that if stop_option = "date", and the the given date is before the start of the model run, the model will stop with an error message.
  See Example: 1, 2, 3

  stop_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if stop_option = "ndays" or "nmonths") DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 2

  stop_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 3

  hist_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: Selects how often history data files are created. The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 2

  hist_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if hist_option = "ndays" or "nmonths")
  DESCRIPTION:
  The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 2

  hist_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  hist_64bit
  TYPE: logical
  DEFAULT: false
  REQUIRED: no
  DESCRIPTION: If true, history files contain 64-bit binary data, otherwise history files contain 32-bit binary data. This option applies to both instantaneous and time averaged history files.

  avHist_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: Selects how often time average history data files are created. The generic periodic event specification (Sec 4.1.1) applies to this option. Note: time average history data is averaged over the interval defined by these file creation events. For example, avHist_option = "monthly" results in monthly average data and avHist_option = "yearly" results in annual average data.

  avHist_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if avHist_option = "ndays" or "nmonths") DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  avHist_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  diag_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: Selects how often instantaneous diagnostics data is written to stdout. The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 2

  diag_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if diag_option = "ndays" or "nmonths")
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.
  See Example: 2

  diag_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  avDiag_option
  TYPE: character(len=32)
  DEFAULT: "monthly"
  REQUIRED: no
  DESCRIPTION: Selects how often time averaged diagnostics data is written to stdout. The generic periodic event specification (Sec 4.1.1) applies to this option.

  avDiag_n
  TYPE: integer
  DEFAULT: 3
  REQUIRED: maybe (only used if diag_option = "ndays" or "nmonths") DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  avDiag_date
  TYPE: integer
  DEFAULT: 0
  REQUIRED: no
  DESCRIPTION: The generic periodic event specification (Sec 4.1.1) applies to this option.

  flx_albav
  TYPE: logical
  DEFAULT: .false.
  REQUIRED: no
  DESCRIPTION: The Coupler computes ocean albedos and sometimes modifies ice albedos. See Sections 16.3.2 and  16.3.3.

  if flx_albav = true

  , 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

  , 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 and 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$: $\langle E \rangle + f \langle P \rangle + f \langle R \rangle = 0$, where $\langle x \rangle$ 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 $\langle E \rangle + f \langle P \rangle + f \langle R \rangle = 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 $\langle E \rangle + f \langle P \rangle + f \langle R \rangle = 0$, 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

  info_dbug
  TYPE: integer
  DEFAULT: 1
  REQUIRED: no
  DESCRIPTION: Debugging information level: 0, 1, 2, or 3. Level 1 is recommended, levels 2 and three are generally for debugging purposes.

  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_bitCheck
  TYPE: integer
  DEFAULT: 0 (off)
  REQUIRED: no (normally not recommended)
  DESCRIPTION: computes and writes to stdout information that can be used when comparing two simulations to see if they are bit-for-bit identical. The information written can verify two runs are NOT bit-for-bit, and it can strongly suggest two runs are bit-for-bit, but it is insufficient to prove that two runs are bit-for-bit identical.

  0:

  do not compute or write any information

  1:

  compute and write information once per month

  2:

  compute and write information once per day

  3:

  compute and write information every time step

4.3 Example Input Namelists

Example 1: a "startup" run

    $inparm
    case_name   = "test.01"
    case_desc   = "testing a startup run "
    start_type   = "initial"
    start_pfile  = "$HOME/cpl6.test.01.rpointer"
    start_date   = 19800101
    rest_option = "monthly"
    stop_option = "monthly"
    orb_year    = 1990
    /

Here the inputs specify a initial run starting on 1980 Jan 1st and stopping every month, in this case on February 1st, 1980. No initial condition data is needed - ``initial'' runs don't use any IC data. Restart files will also be created every month. A restart pointer file, cpl6.test.01.rpointer, will be created in the user's home directory and will contain the name of the most recently created restart file. History data files and diagnostic data will be created at the default frequencies. Solar orbit calculations will be based on the year 1990.

Example 2: a "continuation" run

    $inparm
    case_name   = "test.01"
    case_desc   = "testing a continuation run "
    start_type   = "continue"
    start_pfile  = "$HOME/cpl6.test.01.rpointer"
    stop_option = "nmonths"
    stop_n      = 6
    rest_option = "nmonths"
    stop_n      = 3
    hist_option = "ndays"
    hist_n      = 10
    diag_option = "ndays"
    diag_n      = 10
    orb_year    = 1990
    info_dbug   = 0
    /

Here the inputs specify a continuation run. Assuming this run continues from where example 1 finished, this run will start on 1980 February 1st and stop six months later on 1981 August 1st. Exactly where this run continues from is specified by the restart file - the restart file which will be used is specified by the restart pointer file. Restart files will be created every three months. History data and diagnostic data both will be created every 10 days relative to the start of the run. Setting info_dbug = 0 will minimize the amount of debugging information written to stdout.

Example 3: a "branch" run

    $inparm
    case_name   = "test.02"
    case_desc   = "testing a branch run "
    start_type  = "branch"
    start_pfile = "$HOME/cpl6.test.02.rpointer"
    start_bfile = "test.01.cpl6.r.1980-08-01-00000 "
    stop_option = "date"
    stop_date   = 19810101
    rest_option = "date"
    rest_date   = 19810101
    orb_year    = 1990
    info_dbug   = 2
    /

Here the input parameter start_type specifies a branch run. The branch file (a restart file from a previous run) must be specified. In this case it's expected to be pre-positioned in the execution directory. The start date will be taken from the branch file (apparently 1980 August 1). The simulation will stop on the given date (1981 January 1st). A restart file will also be created on the given date (1981 January 1st). Setting info_dbug = 2 will increase the amount of debugging information written to stdout.