J. Input__Parameters__for__the__Flux__Coupler_________________________ The Flux Coupler uses the FORTRAN namelist input parameter processing capability available in most FORTRAN compilers as an extension to FORTRAN 77. This is also a standard feature of FORTRAN 90. The coupler reads this input namelist, called drv.parm, from stdin at runtime. The following list shows all available namelist input parameters. The list shows the variable names of the input parameter variable name as it appears in both the input namelist and the model code. Recall that FORTRAN is not case sensitive with respect to variable names, but it is case sensitive with regard to character strings. Flux Coupler input variables follow a naming convention in which the first few letters of the variable identify a basic functionality group: o rest__xxxx selects options with respect to model initial conditions and the acquisition and creation of restart files, o stop__xxxx selects options with respect to when a simulation will stop, o hist__xxxx selects options with respect to when and what type of history data is created, o mss__xxxx selects options with respect to data file storage on NCAR's Mass Storage System, o diag__xxxx selects options with respect to run-time diagnostics of the physical simulation, o init__xxxx selects options with respect to special model initialization procedures, o msg__xxxx selects options with respect to the message passing environment, o info__xxxx selects options with respect to monitoring the computational performance of the model. A list of the Flux Coupler Input Namelist variables follows which includes: o the default value of the variable. While reasonable default values are selected for all variables, users might want to alter these values according to their application. o If and when the variable is required input. Note that very few input parameters are required. In a few cases, changing one default value will cause another input parameter to become required. o a brief description of the purpose and effect of the parameter. o see an example input namelist which uses the variable (examples follow the list). rest__type Default: "initial" Required: no (but default is of limited usefulness) Description: This selects the run type. Valid choices are: "initial", "continue", "branch", "regenerate." Selecting "branch" or "regenerate" makes rest__bfile a required input. See Example: 1, 2, 3, 4 J-1 rest__dir Default: "/invalid/rest__dir/" Required: yes, always Description: This is a mass store directory name. Restart and history files go into this directory. For continuation or regeneration runs, the initial condition restart file must also be in this directory. See Example: 1, 2, 3, 4 rest__bfile Default: "/invalid/rest__bfile" Required: no (required if rest__type = "branch" or "regeneration", ignored otherwise) Description: This is the mass store file name of initial condition restart data. See Example: 3, 4 rest__date Default: 00000830 ( 30 Aug, year 0) Required: no (optional for initial and branch runs, ignored otherwise) Description: This is the restart date (encoded: yyyymmdd). o On initial runs, rest__date is the initial date of the simulation. o 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. o On continuation or regeneration runs rest__date is not used. See Example: 1 rest__str Default: "< no rest__str >" Required: no, but highly recommended Description: This is a short text string, up to 80 characters, which is included in output files to help identify the model run. See Example: 1, 2, 3, 4 rest__freq Default: "monthly" Required: no Description: This is the restart frequency, one of "monthly" or "ndays" which selects how often restart data files are created. See Example: 2, 4 rest__nday Default: 14 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__nday J-2 See Example: 4 rest__odate Default: 0 Required: no Description: Selects restart file offset calendar date, used in conjunction with rest__nday when rest__freq = "ndays." If rest__odate > 0, it is a valid calendar date (encoded: yyyymmdd). Restart data is created every n days relative to (and including) either o the initial date of the run (if rest__odate 0) o the date hist__odate (if rest__odate > 0) See Example: 4 stop__option Default: "newyear" Required: no Description: Selects when to stop the simulation. o "newyear" => stop on the next January 1st o "newdecade" => stop on the next decade o "ndays" => stop after advancing n days where n=stop__nday o "date" => stop when stop__date is reached This makes stop__date a required input. See Example: 1, 2, 3, 4 stop__nday Default: 1 Required: no Description: If stop__option = "ndays," stop after stop__nday days. See Example: 3 stop__date Default: 00000101 (1 Jan, year 0) Required: no (required if stop__option = "date," ignored otherwise) Description: If stop__option = "date," stop on this date. See Example: 4 hist__freq Default: "monthly" Required: no Description: One of "monthly," "biweekly," "weekly," or "ndays," which selects how often history data files are created. o "monthly" => data is created on the 1st of each month o "biweekly" => data is created on the 1st and 15th of each month o "weekly" => data is created on the 1st, 8th, 15th, and 22nd of each month o "ndays" => history data is created every n days relative to a history offset date specified by hist__odate. J-3 Note: a history file is never created on a simulation stopping date, but a history file can be created on a simulation starting date. See Example: 2 hist__nday Default: 14 Required: no (only used if hist__freq = "ndays") Description: If hist__freq = "ndays" > 0, 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 ) n=hist__nday p=an offset such that mod(d - p; n) = 0 on the date specified by rest__odate See Example: 2 hist__odate Default: 0 Required: no (only used if hist__freq = "ndays") Description: Selects history file offset calendar date, used in conjunction with hist__nday when hist__freq = "ndays". If hist__odate > 1, it is a valid calendar date (encoded: yyyymmdd). See hist__freq for usage. History data is created every n days relative to (and including) either o the initial date of the run (if hist__odate 0) o the 1st of the month (if hist__odate = 1) o the date hist__odate (if hist__odate > 1) See Example: 2 hist__tavg Default: 1 (true) Required: no Description: If hist__tavg is true (non-zero), component models will be requested to create monthly averaged history data files. See Example: 4 mss__opts Default: "nowait, nomail" Required: no Description: Options used when data files are sent to NCAR's Mass Storage System (MSS) via a mswrite library call. This default request uses asynchronous data file transfer. See the mswrite man pages at NCAR for more details. See Example: 4 mss__pass Default: " " Required: no Description: Mswrite password string for files sent to the MSS. See the mswrite man pages at NCAR for more details. J-4 See Example: 4 mss__rtpd Default: 365 Required: no Description: Retention period for data files sent to the MSS. See the mswrite man pages at NCAR for more details. See Example: 4 diag__glob Default: 0 (false) Required: no Description: If true (non-zero), print global diagnostic information. See Example: 2 flux__albd Default: "instant" Required: no Description: Albedo calculation selection, one of "instant" or "davg". o "instant" => atm is sent albedo fields which have a zenith angle dependence. o "davg" => atm is sent albedo fields which are zenith angle independent. flux__solar Default: 1 (true) Required: no Description: If true (non-zero): redistribute solar radiation between ice, land, and ocean models proportional to (1 - albedo). flux__prec Default: 0 (false) Required: no Description: If true (non-zero): adjust the precipitation field over the non-land ocean domain such that E + P = 0 over that ocean and ice surface area. init__solar Default: 1 (true) for initial runs, 0 (false) otherwise Required: no Description: If true (non-zero), the coupler and atmosphere will exchange an additional message pair on startup. This message pair consists of the coupler sending the merged surface albedos, and the atmosphere returning the resulting downward radiation. The default is that this only happens on an initial run. init__davg Default: 1 (true) for initial runs, 0 (false) otherwise Required: no Description: If true (non-zero), there is an initial one day simulation in which only models that communicate more than once per day are advanced, allowing J-5 the formation of initial daily average fluxes. After this one special day simulation, all models will begin to advance together. The default is that this only happens on an initial run. info__dbug Default: 1 Required: no Description: Debugging information level: 0, 1, 2, or 3. o 0 => do not write any extra debugging information to stdout o 1 => write a small amount of extra debugging information to stdout o 2 => write a medium amount of extra debugging information to stdout o 3 => write a large amount of extra debugging information to stdout See Example: 2 info__time Default: 0 (false) Required: no (normally not recommended) Description: If true (non-zero), write message passing timing info to stdout. msg__group Default: "unknown" Required: yes, always Description: A character string (up to eight characters) used to uniquely identify the message passing group of the simulation. All connected component models must use the same group identifier. See Example: 1, 2, 3, 4 msg__method Default: "default" Required: no Description: Message passing between the driver and the component models may be implemented using various message passing libraries (this requires some isolated re-coding within the driver, as well as recoding within all connected coupled models). Some libraries may offer a choice of various methods for passing messages. For example, the MCL 1.0 message passing library (developed within SCD at NCAR), allows several choices of methods: o "pvm3" => use PVM3 (only) as the underlying message passing method. o "named-pipe" => use a hybrid of PVM3 and UNIX named-pipes as the underlying message passing method. This normally has a faster data transfer rate, but may be less portable than straight PVM3. See the MCL 1.0 document for more details. o "default" => the same as selecting pvm3 See Example: 4 J-6 msg__maxt Default: 300 Required: no Description: the number of seconds elapsed before the message passing library gives up waiting for a message to arrive. The coupled system will shut down if a message fails to arrive. See Example: 4 Examples of input namelists Example 1: an initial run E$drv__parm rest__str = "case b001.01 (an initial run) " rest__dir = "/DOE/csm/b001.01/drv/ " rest__type = "initial" rest__date = "19800831" stop__option = "date" stop__date = 19801001 msg__group = "b001.01" $ Here the inputs specify an initial run, starting on 31 Aug 1980, and stopping on 1 Oct 1980. History data and restart files will be created according to the default settings: there will be a restart file for 1 Sep 1980 and 1 Oct 1980, and there will be a history file for 1 Sep 1980 (but not for 1 Oct 1980). The Flux Coupler will communicate with atmosphere, ocean, and ice models that have also joined the message passing group "b001.01." Example 2: a continuation run E$drv__parm rest__str = "case b001.01 (a continuation run) " rest__dir = "/DOE/csm/b001.01/drv/ " rest__type = "continue" rest__freq = "ndays" stop__option = "newyear" hist__freq = "ndays" hist__nday = 10 hist__odate = 0 info__dbug = 0 diag__glob = 1 msg__group = "b001.01" $ Here the inputs specify a continuation run. Assuming this run continues from where example 1 finished, it will start on 1 Oct 1980 and the stop__option will cause the simulation to stop on 1 Jan 1981. Restart files will be created according to the default settings (the 1st of every month, including 1 Jan 1981). History data will be created on the 1st, 11th, 21st, and 31st of every month (including 1 Oct 1980, but excluding 1 Jan 1981). Setting info__dbug = 0 will minimize the amount of debugging information written to stdout. Setting diag__glob = 1 will signal the coupler to calculate some global diagnostic information and write it to stdout. J-7 Example 3: a branch run E$drv__parm rest__str = "case b001.02 (a branch run) " rest__dir = "/DOE/csm/b001.02/drv/ " rest__type = "branch" rest__bfile = "/DOE/csm/b001.01/drv/r1981-01-01 " stop__option = "ndays" stop__nday = 181 msg__group = "b001.02" $ Here the inputs specify a branch run. The branch file (/DOE/.../r1981-01-01) must be specified. The branch file is an existing file from some previous simulation. Since the simulation's starting date (rest__date) is unspecified in the namelist, the date from the branch file will be used (apparently 1 Jan 1981). The stop__option will cause the simulation to stop after 181 days (i.e., on 1 Jul 1981). Example 4: a regeneration run E$drv__parm rest__str = "case b001.02 (a regen run) " rest__dir = "/DOE/csm/b001.02/drv/ " rest__type = "regeneration" rest__bfile = "/DOE/csm/b001.02/drv/r1981-01-01 " rest__freq = "ndays" rest__nday = 10 rest__odate = 19810701 stop__option = "date" stop__date = 19810701 mss__rtpd = 30 mss__pass = ",secret" mss__opts = "nowait" msg__group = "b001.02" msg__maxt = 600 msg__method = "named-pipe" $ Here the inputs specify a regeneration run. The initial condition file (/DOE/.../r1981- 01-01) must be specified. It is an existing file from the same simulation. This simulation's starting date is taken from the branch file (1 Jan 1980). The stop__option will cause the simulation to stop on 1 Jul 1981. Restart files will be created every 10 days, based on and including 1 Jul 1981. Setting msg__maxt = 600 tells the message passing system to allow up to 10 minutes for a message to arrive (although expected wait times are a fraction of a second). If the coupler is using the MCL 1.0 message passing library, which it will be if it was compiled using the makefile called "Makefile.MCL1.0," see section I, subsection IV, setting msg__method = "named-pipe" changes the message passing method from the default (standard PVM3) to an optional named-pipe implementation, see the MCL 1.O document for details. The mass store file retention period, write password, and other options have been selected here. J-8