The atmosphere setup script, $SCRIPTS/atm.setup.csh, is called by $SCRIPTS/test.a1.run when the atm model is selected in the MODELS environment variable array. atm.setup.csh prepares the atmosphere model component for execution. To do so, it defines the run environment, positions the atmosphere input data sets, then builds the dynamic atmosphere model by calling gmake.
If $SCRIPTS/atm.setup.csh is unable to complete any of these tasks, it will abort with a non-zero error status. The test.a1.run script checks the error status and will halt if an error is detected.
#! /bin/csh -f #=============================================================================== # CVS $Id: atm.setup.csh.tex,v 1.5 2002/06/18 21:25:48 southern Exp $ # CVS $Source: # CVS $Name: $ echo =========================================================================== echo atm.setup.csh: Preparing CAM for execution `date` echo Purpose: echo a. gather or create necessary input files echo b. build the CAM, a CCSM active atm component echo documentation: www.cesm.ucar.edu/models/ccsm2 echo ============================================================================ cat $0;$TOOLS/ccsm_checkenvs || exit -1 # check that enviroment variables are set echo '-------------------------------------------------------------------------' echo ' (a) gather or create necessary input files in EXEDIR ' echo '-------------------------------------------------------------------------'
This first section documents the atmosphere setup script.
The first line of this section identifies this as a C-shell script. The "-f" option prevents the user's personalized $HOME/.cshrc file from being executed to avoid introducing aliases that could adversely affect the operation of this script.
The CVS lines document the revision control version of this script.
The echo lines document the purpose of this script. These output from the echo commands will appear in the component log files.
The cat command combines two functions on one line. The "cat $0" command prints a copy of the entire setup script into the output log file in order to document the exact options set by this script. Then $TOOLS/ccsm_checkenvs writes the environment variables that have been set by test.a1.run into the same output log file. If any of the required environment variables are not set, the setup script will exit with an error status of -1.
cd $EXEDIR # Set restart type #------------------------------------------------ if ($RUNTYPE == 'startup' ) set NSREST = 0 if ($RUNTYPE == 'continue') set NSREST = 1 if ($RUNTYPE == 'branch') set NSREST = 3 if ($RUNTYPE == 'hybrid') set NSREST = 0 # specify physics version: physics #------------------------------------------------ set PHYSICS = physics
First, The cd $EXEDIR command makes $EXEDIR the current working directory. The test.a1.run script defines $EXEDIR as $EXEROOT/atm . All of the atmosphere input and output files will be read from and written to the $EXEDIR directory. Then the runtype setting is parsed into NSREST values appropriate for the the atmosphere model. Finally, the physics version is specified.
# input datasets
#-------------------------
set DATOZON = noaao3.1990.21999.nc
set ABSDATA = abs_ems_factors_fastvx.052001.nc
$TOOLS/ccsm_getinput atm/cam2/ozone/$DATOZON || exit 99
$TOOLS/ccsm_getinput atm/cam2/rad/$ABSDATA || exit 99
# Set parameters associated with resolution and find input dataset
#-------------------------
set DYNAMICS = eul
set NREVSN = ""
set DATINIT = ""
if ($RUNTYPE == 'startup') then
if ($GRID =~ T85*) set DATINIT = JAN1.T85L26.eul.ccsm.c011015.nc
if ($GRID =~ T42*) set DATINIT = JAN1.T42L26.eul.ccsm.052001.nc
if ($GRID =~ T31*) set DATINIT = SEP1.T31L26.c011005.nc
if ($GRID =~ T21*) set DATINIT = SEP1.T21L26.c011017.nc
$TOOLS/ccsm_getinput atm/cam2/inic/gaus/$DATINIT || exit 99
if !($?DATINIT) then
echo atm: ERROR unsupported resolution/physics/dynamics combination
exit 2
endif
endif
if ($RUNTYPE == 'branch') then
set NREVSN = ${REFCASE}.cam2.r.${REFDATE}-00000
$TOOLS/ccsm_getfile $REFCASE/atm/rest/$NREVSN || exit 99
endif
if ($RUNTYPE == 'hybrid') then
set DATINIT = ${REFCASE}.cam2.i.${REFDATE}-00000.nc
$TOOLS/ccsm_getfile $REFCASE/atm/init/$DATINIT || exit 99
endif
This section positions the input datasets needed for the atmosphere model. The input datasets are all uniquely named by a description and a six digit number which documents the creation date (format: yymmdd) of the file. While the hard-wiring of the filenames restrict the degree of automation, it ensures that the exact data requested by the user is input into the model.
Tools from the $TOOLS directory make their first appearance here. $TOOLS/ccsm_cpdata will attempt to copy a version of the file from a local disk into the current working directory. If a local copy of the data file is unavailable, the script will abort. In the branch conditional, $TOOLS/ccsm_msread is used to bring in the restart data set from the sites mass storage device. The complete range of CCSM tools scripts are described in the Supporting Scripts section of this document.
DATOZON is a 4-dimensional(time,longitude, latitude,level) time-series ozone dataset. ABSDATA is the absortivity and emissivity dataset. DATINIT contains the initial atmospheric condition of the model. Alternative versions for different resolutions are also defined.
If this is a branch run, the year, month and day are extracted from the reference date ($REFDATE) and used to acquire the necessary atmosphere restart file.
if ($GRID =~ T85*) set PARAMS = (85 256 128 26 .true. .false. 600) if ($GRID =~ T42*) set PARAMS = (42 128 64 26 .true. .true. 1200) if ($GRID =~ T31*) set PARAMS = (31 96 48 26 .true. .false. 1800) if ($GRID =~ T21*) set PARAMS = (21 64 32 18 .true .false. 2400) set plon = $PARAMS[2]; set plat = $PARAMS[3] ; set plev = $PARAMS[4] set ptrm = $PARAMS[1]; set ptrn = $PARAMS[1] ; set ptrk = $PARAMS[1] set FLXAVE = $PARAMS[5]; set READTRACE = $PARAMS[6]; set DTIME = $PARAMS[7] set KMXHDC = 1 if ($GRID =~ T31*) set KMXHDC = 3 if ($GRID =~ T42* && $plev != 18) set KMXHDC = 5 if ($GRID =~ T85* && $plev != 18) set KMXHDC = 5
This section defines many of the resolution dependent settings of the atmosphere model. For each resolution, the PARAMS array contains the settings for the spectral truncation, the longitude, latitude and level dimensions, and settings for flux averaging, input tracers and the model time step.
In addition, KMXHDC, which defines the number of vertical levels to which the Courant limiter is applied (Defaults to 1.), is set. These setting will be used both to help build the input namelist and in the building of the model executable.
# Create an input namelist file #------------------------------------------------ set BASEDATE_NUM = `echo $BASEDATE | sed -e 's/-//g'` # remove "-" cat >! atm.stdin << EOF &camexp caseid = '$CASE' ctitle = '$CASE $CASESTR' ncdata = '$DATINIT' bndtvo = '$DATOZON' nrevsn = '/$MSSNAME/csm/$REFCASE/atm/rest/$NREVSN' absems_data = '$ABSDATA' mss_irt = $MSSRPD mss_wpass = '$MSSPWD' nsrest = $NSREST dtime = $DTIME start_ymd = $BASEDATE_NUM linebuf = .false. readtrace = $READTRACE nelapse = -9999 ozncyc = .true. flxave = $FLXAVE kmxhdc = $KMXHDC rest_pfile = '$SCRIPTS/rpointer.$MODEL' / EOF
This section constructs the input namelist which is used to control CAM runtime operation. First, the start date, then the runtype setting is parsed into variables which the atmosphere model can interpret.
The primary interface to the atmosphere model is through the namelist input file, in which a wide range of predefined parameters are set to control the behavior of the atmosphere model. The namelist input file, called atm.stdin, is a text file which is read by the atmosphere model. Namelist input for the atmosphere consists of text strings enclosed in quotes, integer and real numerical values and logicals.
A few of the CCSM environment variables, such as $BASEDATE and $RUNTYPE, are translated into variables recognized by the Community Atmosphere Model (CAM).
The "cat" command uses the C-shell here-document option to create the file $EXEDIR/atm.stdin. When atm.stdin is created, all of the environment variables are set to the current values as defined by the $SCRIPTS/test.a1.run script.
| &camexp | is the namelist group name, which matches the groupname defined within CAM. |
|---|---|
| caseid | = $CASE (string) sets a text string (16 characters or less) that is used to identify this run. The CASE variable is set in $SCRIPTS/test.a1.run and is used extensively in the CCSM as an identifier. Since CASE will be used in file and directory names, it should only contain standard UNIX filenaming characters such as letters, numbers, underscores, dashes, commas or periods. |
| ctitle | = '$CASE $CASESTR' (string) provides 80 characters to further describe this run. This description appears in the output logs and in the header data for the output data sets. CASESTR is set in the $SCRIPTS/test.a1.run script. |
| ncdata | = '$DATINIT' is the name of the dataset which contains the initial-condition data for the atmosphere. It contains three-dimensional fields of T, U, V, Q and two-dimensional fields of surface geopotential, standard deviation of orography, land ocean transition flags and masks, subsoil temperature profiles, and constituent tracers. |
| bndtvo | = '$DATOZON' (string) is the name of the ozone boundary dataset. |
| nrevsn | = '$NREVSN' (string) is the optional name of the restart dataset to be read if this is a branch run. This dataset is a binary file containing the exact state of a previous run. |
| absems_data | = '$ABSDATA' (string) is the name of the absortivity and emissivity dataset. |
| irt | = $MSSRPD and rirt = $MSSRPD (integer) specifies the mass store retention period for output history and restart files respectively when running at NCAR. If irt or rirt are set to 0, the output history or restart files are not written to the NCAR MSS. |
| nswrps | = '$MSSPWD' (string) sets the write password for any files written to the NCAR MSS. |
| nsrest | = $NSREST (string) specifies the state in which the run is being started. nsrest settings 0,1,3 map into the CCSM variables (startup/hybrid, continue and branch respectively). |
| dtime | = $DTIME (integer) sets the time step, in seconds, for the atmosphere model. The time step is dependent on both the resolution of the model and the dynamical core used by the model. |
| start_ymd | = $START_YMD (integer) specifies the "basedate" for the run. This date serves as the baseline from which the current step number is calculated. |
| linebuf | = .false. (logical) turns off line-by-line buffering in favor of the default buffering. The linebuf option allows the user to control whether standard output is written line-by-line or buffered. Setting linebuf = .false. allows printed output to be buffered, resulting in increased performance. linebuf is typically set to .true. for debugging so that printed output will be written to the standard out device immediately, rather than being buffered. |
| readtrace | = $READTRACE (logical) specifies whether or not an input chemical tracer file is read. |
| nelapse | = -9999 (integer) indicates that the flux coupler will control the ending timestep for this model run. |
| ozncyc | = .true. (logical) will result in the input ozone dataset being cycled through the first 12 months of data in the input ozone file. |
| flxave | = $FLXAVE (logical) controls whether or not the atmosphere flux averaging feature is enabled. |
|---|---|
| kmxhdc | = $KMXHDC (integer) specifies... |
| rest_pfile | = '$SCRIPTS/rpointer.$MODEL' (string) is the filename of the restart pointer file. The restart pointer file is a one line text file containing the name of the CAM restart files needed to continue the run. |
| / marks the end of the camexp namelist input variables. | |
| EOF | marks the end of the unix here document referenced by the cat command near the start of this section. |
Detailed information on the complete range of atmospheric namelist variables can be found in the CAM user's guide.
The remainder of the atm.setup.csh builds the CAM executable. First the location of the source code is specified, then various resolution and configuration information is put into header files. Once the source code Filepath and header files have been created, the CAM executable is built with gmake.
echo '-------------------------------------------------------------------------' echo ' (b) Build an executable ' echo '-------------------------------------------------------------------------' cd $OBJDIR # atm source code archive #------------------------------------------------ set SRCDIR = $CSMCODE/atm/cam/src set ATMLNDSHR = $CSMCODE/camclm_share set MATHUTIL = mathutil
To avoid filling the $EXEDIR directory with all the artifacts of the build process, the model is built in a subdirectory, $OBJDIR. $OBJDIR which is defined in the $SCRIPTS/test.a1.run script.
$SRCDIR identifies the root directory of the atmospheric source code and $ATMLNDSHR points to the directory containing CSM code shared by both the CAM and Common Land Model (CLM) components.
The variable CSMCODE is set in the test.a1.run script to coordinate CCSM source code.
# Filepath: List of source code directories (in order of importance). # The cmp command will force a rebuild the old and new files are different #-------------------------------------------------------------------- \cat >! .tmp << EOF; cmp -s .tmp Filepath || mv -f .tmp Filepath \$SCRIPTS/src.atm $SRCDIR/dynamics/$DYNAMICS $SRCDIR/advection/slt $SRCDIR/control $SRCDIR/$MATHUTIL $SRCDIR/$PHYSICS $ATMLNDSHR $CSMSHR $CSMCODE/utils/timing EOF
The Filepath file contains he list of source code directories from which to gather the input source code. This list will be used as the input to the gmake VPATH list.
The Filepath directories are listed in order of precedence. If a file is found in more than one of the directories listed in Filepath, the version of the file found in the directory listed first will be used to build the code. The first directory, $SCRIPTS/src.atm, is typically used to hold modified atmospheric source code. If a directory in the Filepath list is either empty or doesn't exist at all, no error will result.
To avoid a complete rebuild of the model every time this script is called, the Filepath list is first put into a temporary file, then the contents of the temporary file are compared against any existing Filepath list. If there is no existing Filepath list or the temporary file differs from the existing Filepath list, the new tmp file is renamed Filepath, causing a complete rebuild of the atmosphere model. If the temporary file is exactly the same as the existing Filepath file, nothing happens.
# build params.h (update only if new or changed) #-------------------------------------------------- \cat >! .tmp << EOF; cmp -s .tmp params.h || mv -f .tmp params.h #ifndef PARAMS_SET #define PARAMS_SET #define PCNST 1 #define PNATS 1 #define PLEV $plev #define PLEVR $plev #define PLON $plon #define PCOLS $plon #define PLAT $plat #define PTRM $ptrm #define PTRN $ptrn #define PTRK $ptrk #endif EOF # build misc.h (update only if new or changed) #------------------------------------------------ if ($NTASK == 1) set SPMD = "#undef SPMD" if ($NTASK > 1) set SPMD = "#define SPMD" \cat >! .tmp << EOF; cmp -s .tmp misc.h || mv -f .tmp misc.h #ifndef MISC_SET #define MISC_SET #define COUP_CSM $SPMD #endif EOF
Two CAM include files are created here. params.h contains information about the model dimensions while misc.h contains flags for whether the model is coupled or standalone and whether CAM will be built to run multitasked.
# Create the executable in EXEDIR/obj
#------------------------------------------------
if ($BLDTYPE == 'true') then
cc -o makdep $CSMBLD/makdep.c
gmake -j 4 -f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS MODEL=cam \
VPFILE=Filepath EXEC=$EXEDIR/atm || exit 2
else
echo "BLDTYPE = $BLDTYPE"
endif
In this last section the atmosphere model is built using gmake.
The CCSM uses the gnumake (also known as ``gmake'') tool to build the model executable. Each of the components setup scripts creates a list of source code directories from which to gather the input source code for that component. This list is called Filepath and will be used as the input to the gmake VPATH list. The file Filepath is written in each of the components $OBJDIR directories.
The Filepath directories are listed in order of precedence. If a file is found in more than one of the directories listed in Filepath, the version of the file found in the directory listed first will be used to build the code. The first directory, $SCRIPTS/src.atm, is typically used to hold modified source code. If a directory in the Filepath list is either empty or doesn't exist at all, no error will result. In general, the directories $SCRIPTS/src.$MODEL can be used to store locally modified source code. Each component script recognizes this directory as the top priority for finding source code.
First the makdep code is compiled. This utility program is called by the Makefile and checks for source code dependencies. This is done by seeing if any of the header or include files have been updated since the model was last built and ensures that the F90 modules are constructed in the proper order.
Once makdep is compiled, the GNU make program, gmake, is used to actually build the model. The -j 4 option uses 4 processors to build the model. The -f $CSMBUILD/Makefile points to the generic CCSM Makefile while MACFILE=$CSMBLD/Macros.$OS points to the machine specific make options. MODEL identifies the component being built and VPFILE points to the Filepath list. Finally, the actual executable to be built is $EXEDIR/$MODEL.
echo ================================================================== echo End of cam setup shell script echo ==================================================================
Once the atm.setup.csh script completes successfully, it will exit with a 0 (no-error) status.