While the executing of the Coupler and the component models is explicitly done
in the NQS script, the pre-execution preparation of the components is deferred
to the setup scripts.
The purpose of the setup scripts is to build their respective executable codes,
document what source code and data files are being used,
and gather or create any necessary input data files.
All model-specific details are handled by the component model setup scripts.
This natural decomposition of code allows the persons responsible for a
given model to create an appropriate setup script for their model without being confused by the details of another model.
Here we describe all the necessary pre-execution preparation of the Coupler. This is
done by a cshell setup script called "cpl.setup.csh," which is called by the parent NQS
batch job shell script described in § 4. The purpose of the setup script is to build
an executable Coupler code, gather and/or create any necessary data files, and to document
exactly which code and data files are being used in a given simulation.
The Coupler has its own, separate subdirectory, $EXEDIR/cpl, see § 4, in
which the setup script is run, in which the Coupler executable resides, and in which all the
Coupler's input and output files are kept.
The environment variables
$CASE, $CASESTR, $RUNTYPE, $ARCH, $MSGLIB, $MAXCPUS, $SSD,
$MSS, $MSSDIR, $MSSRPD, $MSSPWD, $RPTDIR, $CSMROOT, and $CSMSHARE
are input from the parent NQS script and are available for use, see § 4.
Note that the example NQS script in § 4 makes use of separate and independent
setup subscripts for the Coupler and each component model. While this is not required,
it is a natural decomposition of code, and is highly recommended. Because the Coupler,
or any other component model, has its own setup script, the persons responsible for this code
can edit this file as necessary without being confused by extraneous details about other
component models, and without the danger of inadvertently introducing errors into the
top-level NQS run script or the setup scripts of the other component models.
An example Coupler setup script is given below:
(a) Build an executable
The goal here is to build an executable Coupler binary in the current working directory.
This is done by first identifying the source code directories,
copying all files from those directories,
selecting a resolution-dependent "dims.h" file,
executing a script that creates the necessary include files needed by the makefile,
and invoking a makefile
(note how the executable name and target architecture are specified).
The dimensions of the component models (i.e. the number of x and y grid points) must
be known to the Coupler at compile time and are all specified in one
resolution-dependent file: dims.h. Notice how an appropriate dims.h file is selected.
In general, several dims.h.* files may be available for building a Coupler binary
suitable for various component model resolutions.
The details of how to build the executable (eg. preprocessor options and compiler options)
are contained in the standard Makefile.
See § 8, or a make man page on any UNIX system for more information.
(b) Document the source code used
Here we make a detailed listing of the source code used, a list of revision control system
(CVS) information, and list of the contents of the current working directory.
This information can be used to identify what Coupler source code, input namelist, etc. were
used in a particular simulation. This is not necessary but is strongly suggested.
(c) Create an input parameter namelist file
Here we are creating a Coupler input parameter namelist file.
To create an appropriate namelist we must know and specify whether the run is an
initial run, a continuation run, a branch run, or a regeneration run.
Checking the value of the environment variable $RUNTYPE gives this information.
See the § 6 for a complete description of input namelist variables.
The environment variables $CASE, $CASESTR, and $MSSDIR are used to construct a descriptive
text string found in history files and to create history and restart data path names.
Recall from the discussion in § 4 that these environment variables
are set in the NQS script specifically for use by this, and other, setup scripts.
This particular input namelist was selected just to illustrate how the "cpl.setup.csh"
script works. For a detailed discussion of Coupler input parameters,
along with several example input namelists, see § 6.
Each component model has a separate subdirectory,
$EXEDIR/atm, $EXEDIR/ice, $EXEDIR/lnd, or $EXEDIR/ice, see § 4, in which
the setup script is run, and where the executable and all input and output files are kept.
As in the Coupler setup script, the environment variables
$CASE, $CASESTR, $RUNTYPE, $ARCH, $MSGLIB, $MAXCPUS, $SSD,
$MSS, $MSSDIR, $MSSRPD, $MSSPWD, $RPTDIR, $CSMROOT, and $CSMSHARE are set by
the parent NQS script and are available for the setup scripts to use, see § 4.
These environment variables are not intended to be accessed by the component model
exectuable codes themselves. It is recommended that the executable codes use input
namelist parameters instead of accessing environment variables.
If the UNICOS specific assign function is used prior to executing a code,
the assigning of I/O units should be done here in the setup script.
Setting environment variable FILENV = ./.assign in the top level run script, see § 4,
allows each component model to do it's own I/O unit assignments, using it's own .assign file,
without conflicting with the I/O unit assignments of other models.
See the assign man page on a UNICOS system for more details.
5.1 The Flux Coupler Setup Script
#=======================================================================
# File name cpl.setup.csh
# Purpose prepares Flux Coupler (aka "cpl") for execution
# Assumptions these env variables have been set by a parent shell:
# CASE, CASESTR, RUNTYPE, ARCH, MSGLIB, MAXCPUS, SSD,
# MSS, MSSDIR, MSSRPD, MSSPWD, RPTDIR
#=======================================================================
#-----------------------------------------------------------------------
# (a) Build an executable
#-----------------------------------------------------------------------
mkdir src
cd src
set SRCDIR =
cp -fp $CSMSHARE/* .
cp -fp $CSMROOT/models/cpl/cpl4.0/* .
cp -fp dims.h.T31_x3 dims.h
Makeprep
make EXEC=../cpl4 ARCH=$ARCH
cd ..
#-----------------------------------------------------------------------
# (b) document the source code used
#-----------------------------------------------------------------------
pwd ; ls -alF src
grep CVS src/*.[hF]
#-----------------------------------------------------------------------
# (c) Create an input parameter namelist file
#-----------------------------------------------------------------------
if ($RUNTYPE == 'initial' ) then
set rest_type = 'initial'
set rest_bfile = '/unused/rest_bfile'
set rest_date = 00010101
else if ($RUNTYPE == 'continue') then
set rest_type = 'continue'
set rest_bfile = '/unused/rest_bfile'
set rest_date = -999
else if ($RUNTYPE == 'branch' ) then
set rest_type = 'branch'
set rest_bfile = '/KAUFF/csm/b003.01/cpl/r0010-01-01'
set rest_date = 00010101
else if ($RUNTYPE == 'regen' ) then
set rest_type = 'regen'
set rest_bfile = "$MSSDIR/cpl/r1999-01-01"
set rest_date = 19990101
else
echo 'unknown RUNTYPE = ' $RUNTYPE ; exit -1
endif
cat >! cpl.parm << EOF
&cpl_parm
case_name = '$CASE '
case_desc = '$CASESTR '
rest_type = '$rest_type '
rest_pfile = '$RPTDIR/cpl.$CASE.rpointer '
rest_bfile = '$rest_bfile '
rest_date = $rest_date
rest_freq = 'monthly'
stop_option = 'newyear'
hist_freq = 'monthly'
mss_dir = '$MSSDIR/cpl/ '
/
EOF
cat cpl.parm
#=======================================================================
# End of Coupler setup shell script
#=======================================================================
Items (a) through (c) in the above Coupler setup script are now reviewed.
5.2 Component Model Setup Scripts
Preparing the component models (atmosphere, ice, land, ocean) for a coupled run
is analogous to preparing the Coupler (see § 5.1).
Such preparation is done in the component model setup scripts
"atm.setup.csh," "ice.setup.csh," "lnd.setup.csh," and "ocn.setup.csh,"
which are called by the parent NQS batch job shell script described in § 4.
The purpose of the setup scripts is to build their respective executable codes,
document what source code and data files are being used,
and gather or create any necessary input data files.