The land setup script, scripts/test.a1/lnd.setup.csh, is called by test.a1.run when the lnd model is selected in the MODELS environment variable array. lnd.setup.csh prepares the land model component for execution by defining the run environment, positioning the land input data sets and building the dynamic land model by calling gmake.
If lnd.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: lnd.setup.csh.tex,v 1.6 2002/06/18 21:25:51 southern Exp $ # CVS $Source: # CVS $Name: $ #=============================================================================== # lnd.setup.csh: Preparing a CCSM Common Land Model, clm2, for execution # # (a) set environment variables, preposition input data files # (b) create the namelist input file # (b) build this component executable # # For help, see: http://www.cgd.ucar.edu/cms/lsm/clm/clm.html #=============================================================================== cat $0;$TOOLS/ccsm_checkenvs || exit -1 # cat this file, check envs
This first section documents the land 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.
echo --------------------------------------------------------------------------- echo a. set environment variables, preposition input data files echo --------------------------------------------------------------------------- # lnd source code archive #------------------------ set SRCDIR = $CSMCODE/lnd/clm2/src set CAMLND_SHARE = $CSMCODE/camclm_share
First, the directories for the CLM source code and code which is shared with the CAM model are set.
cd $EXEDIR
# Set restart type
#------------------------------------------------
if ($RUNTYPE == 'startup') then
set NSREST = 0
set NREVSN = ""
if ($GRID =~ T42* ) then
set DATINIT = Ba.b19.clmi_00030101_00000.nc
$TOOLS/ccsm_getinput lnd/clm2/inidata/csm/$DATINIT || exit 99
if !(-f $DATINIT) exit 99
else
set DATINIT = ""
endif
else if ($RUNTYPE == 'continue') then
set NSREST = 1
set DATINIT = ""
set NREVSN = ""
else if ($RUNTYPE == 'branch' ) then
set NSREST = 3
set DATINIT = ""
set NREVSN = ${REFCASE}.clm2.r.${REFDATE}-00000
$TOOLS/ccsm_getfile $REFCASE/lnd/rest/$NREVSN || exit 99
if !(-f $NREVSN) exit 99
else if ($RUNTYPE == 'hybrid') then
set NSREST = 0
set NREVSN = ""
set DATINIT = ${REFCASE}.clm2.i.${REFDATE}-00000.nc
$TOOLS/ccsm_getfile $REFCASE/lnd/init/$DATINIT || exit 99
if !(-f $DATINIT) exit 99
endif
The current directory is set to $EXEDIR to ensure that all the files necessary to build and run the land model are in the correct directory.
Then the restart flag ($NSREST), the restart filename ($NREVSN) and the initial data file ($DATINIT) are set depending upon the type of run that was requested in the master test.a1.run script. If either an initial or a restart data file is needed, ccsm_getinput is called to position it in the current directory.
For $RUNTYPE = 'startup',the restart flag ($NSREST) is set to 0, the branch restart filename ($NREVSN) is set to blank and the initial dataset ($DATINIT) is identified and positioned in the current directory.
For $RUNTYPE = 'continue', the restart data come from the land restart files written previously. Here, the restart flag ($NSREST) is set to 1 and both the branch restart filename ($NREVSN) and the initial dataset ($DATINIT) are set to blank. The land model will internally generate the name of the required restart dataset by reading the restart pointer file.
$RUNTYPE = 'branch' is conceptually similar to a 'continue' run, except the restart file is explicitly named and the land model logic requires that the $CASE name be different from that of the reference $CASE name. To do this, the restart flag ($NSREST) is set to 3, the initial dataset ($DATINIT) is set to blank and the branch restart filename ($NREVSN) is identified and positioned in the current directory.
$RUNTYPE = 'hybrid' is similar to a `startup` run. In this case, the name of the initial data set is generated from the reference case ($REFCASE) and reference date ($REFDATE) set in test.a1.run.
# Position the input data
#------------------------------------------------
set data_dir = lnd/clm2
if ($ATM_GRID == 'T85') set atmres = '256x128'
if ($ATM_GRID == 'T42') set atmres = '128x064'
if ($ATM_GRID == 'T31') set atmres = '096x048'
if ($ATM_GRID == 'T85') set DTIME = 600
if ($ATM_GRID == 'T42') set DTIME = 1200
if ($ATM_GRID == 'T31') set DTIME = 1800
if ($ATM_GRID == 'T85') set RTM_NSTEPS = 18
if ($ATM_GRID == 'T42') set RTM_NSTEPS = 9
if ($ATM_GRID == 'T31') set RTM_NSTEPS = 6
set surf_dat_date = ""
if ($atm_setup == atm && $ATM_GRID == 'T42') set surf_dat_date = ".080101"
set surf_dat = surface-data.${atmres}_${atm_setup}.${OCN_GRID}_ocn${surf_dat_date}.nc
$data_dir specifies the directory path (relative to $CSMDATA set in test.a1.run) to the land model input data sets in the CCSM2 distribution. The atmosphere model resolution ($atmres), land model time step in seconds ($DTIME) and the number of model steps between river transport model calculations ($RTM_NSTEPS) are defined for the different supported resolutions. Finally, the name of the land surface dataset is based upon the atmosphere resolution, the type of atmosphere model and the ocean resolution.
A spun-up land initial dataset is supplied for use with the active atmosphere at T42 resolution. For other cases, the land model will try to do a ``cold'' start. During a cold start, the CLM is initialized from a generic state and will, over time, settle into an equilibrium state. The adjustment time for most CLM fields is around 5 years. However, it may take as long as 200 years for soil water content at the deepest layer to reach equilibrium.
$TOOLS/ccsm_getinput $data_dir/pftdata/pft-physiology || exit 1 $TOOLS/ccsm_getinput $data_dir/rtmdata/rdirc.05 || exit 1 if ($surf_dat != ' ') then $TOOLS/ccsm_getinput $data_dir/srfdata/csm/$surf_dat || exit 1 else $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_soicol_clm2.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_lanwat.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_glacier.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_urban.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_lai.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_pft.nc || exit 1 $TOOLS/ccsm_getinput $data_dir/rawdata/mksrf_soitex.10level.nc || exit 1 endif set BASEDATE_NUM = `echo $BASEDATE | sed -e 's/-//g'` # remove "-"
A number of input datasets are required for the land model. First, Plant Functional Type (PFT) physiological constants and the River Transport Model (RTM) files are moved into the local directory.
If a surface dataset ($surf_dat) is defined, then it is acquired. Otherwise, the files in the rawdata directory are used to create a surface dataset at runtime.
# Create the input parameter namelist file ' #------------------------------------------------ cat >! lnd.stdin << EOF &clmexp rtm_nsteps = $RTM_NSTEPS caseid = '$CASE' ctitle = '$CASE $CASESTR' nsrest = $NSREST start_ymd = $BASEDATE_NUM start_tod = 0 nelapse = -9999 dtime = $DTIME irad = -1 csm_doflxave = .true. nrevsn = '$NREVSN ' finidat = '$DATINIT ' fsurdat = '$surf_dat' fpftcon = 'pft-physiology' frivinp_rtm = 'rdirc.05' mksrf_fvegtyp = 'mksrf_pft.nc' mksrf_fsoitex = 'mksrf_soitex.10level.nc' mksrf_fsoicol = 'mksrf_soicol_clm2.nc' mksrf_flanwat = 'mksrf_lanwat.nc' mksrf_fglacier = 'mksrf_glacier.nc' mksrf_furban = 'mksrf_urban.nc' mksrf_flai = 'mksrf_lai.nc' mss_wpass = '$MSSPWD' hist_nhtfrq = 0 hist_crtinic = 'YEARLY' mss_irt = $MSSRPD rpntpath = '$SCRIPTS/rpointer.$MODEL' / EOF
In the namelist input file, a wide range of parameters are set to control the behavior of the land model. The namelist input file, clmexp, is a text file that is read by the land model. This section constructs the input namelist that is used to control runtime operation of the land model.
The "cat" command uses the Unix here-document option to create the file $EXEDIR/clmexp with all the settings being evaluated to the current values of the specified environment variables.
| &clmexp | is the namelist group name, which matches the groupname defined within the land-surface model. |
|---|---|
| rtm_nsteps | = $RTM_NSTEPS (integer) sets the number of timesteps between river runoff calculations. |
| caseid | = '$CASE' (string) sets a unique, 16-character, test string used to identify this run. The CASE variable is set in $SCRIPTS/test.a1.run script and is used extensively in the CLM 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 the run. This description appears in the output logs and in the header data for the output data sets. CASESTR is set in the run script. |
| nsrest | = $NSREST (integer) specifies the state in which the run is to be started. nsrest settings 0,1,3 map into the CCSM variables (startup/hybrid, continue and branch). |
| start_ymd | = $BASEDATE_NUM (integer) specifies the "basedate" for the run. This date serves as the baseline from which the current step number is calculated. |
| start_tod | = 0 (integer) sets the starting time of day for the run in seconds. |
| nelapse | = -9999 (integer) indicates that the flux coupler will control the ending timestep for this model run. |
| dtime | = $DTIME (integer) sets the timestep, in seconds, for the land model. The timestep is dependent on the resolution of the model. |
| irad | = -1 (integer) sets the iteration frequency for shortwave radiation calculations. If the number is positive, then the frequency is specified in model timesteps. If the number is negative, then the frequency is specified in model hours. |
| csm_doflxave | = .true. (logical) instructs the land model to only communicate with flux coupler on albedo calculation timesteps. |
| nrevsn | = '$NREVSN ' (string) is the optional name of the branch 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. |
| finidat | = '$DATINIT ' (string) sets the name of the initial data file. If $DATINIT is blank, then the land model is initialized from a ``cold start'' condition. |
| fsurdat | = '$surf_dat' (string) is name of the land surface dataset. If $surf_data is blank, then the land model surface dataset at the model resolution is created at runtime from a ``cold start'' condition. |
| fpftcon | = 'pft-physiology-vegdyn-cleanup-ratio' (string) identifies the Plant Functional Type (PFT) physiological constants input dataset. |
| frivinp_rtm | = 'rdirc.05' (string) is the name of the River Transport Model (RTM) input dataset. |
| mksrf_fvegtyp | = 'mksrf_pft.nc' (string) is the vegetation type data file name. |
| mksrf_fsoitex | = 'mksrf_soitex.10level.nc' (string) is the soil texture data file name. |
| mksrf_fsoicol | = 'mksrf_soicol_clm2.nc' (string) is the soil color data file name. |
| mksrf_flanwat | = 'mksrf_lanwat.nc' (string) is the inland water data file name. |
| mksrf_fglacier | = 'mksrf_glacier.nc' (string) is the glacier data file name. |
| mksrf_furban | = 'mksrf_urban.nc' (string) is the urban data file name. |
| mksrf_flai | = 'mksrf_lai.nc' (string) is the leaf area index data file file name. |
|---|---|
| mss_wpass | = '$MSSPWD' (string) sets the write password for any files written to the NCAR MSS. |
| hist_nhtfrq | = 0 (integer) is the history tape output interval (+ = iterations, - = hours, 0=monthly aveerage) |
| hist_crtinic | = 'YEARLY' (string) outputs a land initial condition file if set to 'MONTHLY' or 'YEARLY', |
| mss_irt | = $MSSRPD (integer) specifies the mass store retention period for output history and restart files when running at NCAR. If irt is set to 0, the output history and restart files are not written to the Mass Storage System. |
| rpntpath | = '$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 CLM restart files needed to continue the run. |
| / | marks the end of the clmexp namelist input variables. |
| EOF | marks the end of the Unix here document referenced by the cat command near the start of this section. |
The rest of the lnd.setup.csh builds the CLM 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 CLM executable is built with gmake.
echo '-------------------------------------------------------------------------' echo b. Build an executable in $OBJDIR echo '-------------------------------------------------------------------------' cd $OBJDIR # build Filepath: List of source code directories (in order of importance) # (update only if new or changed) #-------------------------------------------------------------------- \cat >! .tmp << EOF; cmp -s .tmp Filepath || mv -f .tmp Filepath $SCRIPTS/src.lnd $SRCDIR/main $SRCDIR/biogeophys $SRCDIR/ecosysdyn $SRCDIR/riverroute $SRCDIR/biogeochem $SRCDIR/mksrfdata $CAMLND_SHARE $CSMSHR $CSMCODE/utils/timing EOF
The land-surface model is build in the directory $OBJDIR to ensure that all the files involved with building the land-surface model are in one directory.
The Filepath file contains the 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 directories appearing in the Filepath file are listed in order of precedence, from most important to least important. 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 listed, $SCRIPTS/src.lnd, is typically used to hold modified land-model source code. If a directory in the filepath list is either empty or doesn't exist at all, no error will result.
# build preproc.h: land model dimensions # (update only if new or changed) #---------------------------------------------------------- if ($GRID =~ T85* ) set LONLAT = ( 256 128 ) if ($GRID =~ T42* ) set LONLAT = ( 128 64 ) if ($GRID =~ T31* ) set LONLAT = ( 96 48 ) \cat >! .tmp << EOF; cmp -s .tmp preproc.h || mv -f .tmp preproc.h #ifndef PREPROC_SET #define PREPROC_SET #define LSMLON $LONLAT[1] #define LSMLAT $LONLAT[2] #endif EOF
With Filepath set, the CCSM land grid is parsed into integer longitude and latitude grid dimension values (LSMLON and LSMLAT) acceptable to the land model. These dimension values are inserted into the preproc.h header file.
# build misc.h # (update only if new or changed) #------------------------------------------------ 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 $spmd #define COUP_CSM #define RTM #endif EOF
The misc.h header file sets options for automatically building the coupled version of the model (COUP_CSM), building a single-task or multi-task version of the code and using the River Transport Model (RTM). Note, this document only discusses the coupled version. See the land model document www.cesm.ucar.edu/models/ccsm2.0/UsersGuide/UsersGuide ). for information on running the land model as a ``standalone'' model.
# Create the executable
#----------------------
if ($BLDTYPE == 'true') then
set echo on
cc -o makdep $CSMBLD/makdep.c
if ($NTHRD > 1) setenv THREAD TRUE
gmake -j 6 -f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS MODEL=clm \
VPFILE=Filepath EXEC=$EXEDIR/lnd || exit 2
else
echo "BLDTYPE = $BLDTYPE"
endif
wait
The land model executable is only built if $BLDTYPE is true.
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.lnd, is typically used to hold modified component 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 6 option uses 6 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 clm2 model setup shell script echo ==================================================================