next up previous contents
Next: 11 The Ocean Model Up: UsersGuide Previous: 9 The Graphical User   Contents


10 The Atmosphere Setup Script: atm.setup.csh

The atmosphere setup script, $SCRIPTS/atm.setup.csh, is called by $SCRIPTS/ 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 script checks the error status and will halt if an error is detected.

10.1 Document the atmosphere setup script

#! /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:
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 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.

10.2 Define and position the atmosphere input datasets


# 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 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 
$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 =
  if ($GRID =~ T42*) set DATINIT =
  if ($GRID =~ T31*) set DATINIT =
  if ($GRID =~ T21*) set DATINIT =
  $TOOLS/ccsm_getinput atm/cam2/inic/gaus/$DATINIT || exit 99
  if !($?DATINIT) then
   echo atm: ERROR unsupported resolution/physics/dynamics combination
   exit 2
if ($RUNTYPE == 'branch') then
  set NREVSN = ${REFCASE}.cam2.r.${REFDATE}-00000
  $TOOLS/ccsm_getfile $REFCASE/atm/rest/$NREVSN || exit 99
if ($RUNTYPE == 'hybrid') then
  set DATINIT = ${REFCASE}.cam2.i.${REFDATE}
  $TOOLS/ccsm_getfile $REFCASE/atm/init/$DATINIT || exit 99

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.

10.3 Define resolution dependent parameters

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 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.

10.4 Write the atmosphere input namelist

# Create an input namelist file

set BASEDATE_NUM =  `echo $BASEDATE | sed -e 's/-//g'`  # remove "-"

cat >! atm.stdin << EOF
 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'

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/ 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/ 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/ 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.

10.5 Create the atmosphere executable

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 '-------------------------------------------------------------------------'


# 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/ 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 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

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

# 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 

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

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.

next up previous contents
Next: 11 The Ocean Model Up: UsersGuide Previous: 9 The Graphical User   Contents