Any of the CCSM models can be replaced by a simple data component which simply reads previously calculated data for that component and supplies these data to the coupler. The data components were previously an integral step in the CSM1 model spin-up procedure, but now the CCSM2.0 spin-up involves starting the full set of active models from climatological conditions, without using the data components. While the data components now play a lesser role in making a CCSM run, they are valuable tools for testing and debugging. For this reason, they are included in the distribution package as examples of ways to supply existing data to the CCSM. The test data referenced in these scripts uses CSM1 forcing data and should not be expected to return realistic results for the CCSM2.0 model.
To use a data component in place of the active component, replace the name of the active component (i.e. atm for the atmosphere) with the data-model equivalent in the proper place in the $SETUPS array definition in $SCRIPTS/test.a1.run script. Also, $NTHRDS and $NPROCS should both be set to 1. This may require a change in the batch queue setting associated with the number of threads and processes (task_geometry on the IBM SP, mpp_p on the SGI and nodes:ppn on the Compaq).
All of the data component scripts follow a similar pattern, so only the data atmosphere script will be described here.
#! /bin/csh -f #=============================================================================== # CVS $Id: # CVS $Source: # CVS $Name: #=============================================================================== # datm.setup.csh: Prepare a CSM data atmosphere component, datm5, for execution # For help, see: http://www.cesm.ucar.edu/models/atm-datm #=============================================================================== cat $0;$TOOLS/ccsm_checkenvs || exit -1 # cat this file, check envs
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 --------------------------------------------------------------------------- #if ( $GRID =~ T42*) set DATA_DIR = mss:/BOVILLE/csm/f015.00/datm/data if ( $GRID =~ T42*) set DATA_DIR = cp:$CSMDATA/atm/datm5 if ( $GRID =~ T31*) set DATA_DIR = mss:/SHIELDS/csm/f023.02/datm/data #rm -f 0005-01.nc #rm -f 0009-12.nc #if ( $GRID =~ T42*) $TOOLS/ccsm_getinput atm/datm5/0005-01.nc #if ( $GRID =~ T42*) $TOOLS/ccsm_getinput atm/datm5/0009-12.nc set RUN_TYPE = $RUNTYPE if ($RUNTYPE == startup) set RUN_TYPE = initial if ($RUNTYPE == hybrid) set RUN_TYPE = initial
$DATA_DIR points to specifies the directory path to the input data sets. The first DATA_DIR setting which is commented out with a # in the 1st column, shows a local NCAR method for pointing to a collection of T42 input data. The second setting illustrates how to copy the data from the $CSMDATA area. The third setting is another local NCAR methods for acquiring the T31 input data.
The set of four commented out lines (using the C-shell # symbol) is another method which simply places the required data in the execution directory. Since the data component will always look in the local directory first before trying to find the data in a remote spot, this is the most straightforward method. The disadvantage of this is that the names of the input files must be specifically set, while the previous methods will position the files as they are needed.
The $RUNTYPE is parsed for use in the data component. For $RUNTYPE = branch or continue, no translation is needed. However both $RUNTYPE = startup and hybrid are interpreted as an 'initial' run for the data component.
echo --------------------------------------------------------------------------- echo b. create the namelist input file echo --------------------------------------------------------------------------- cat >! $MODEL.stdin << EOF &inparm case_name = '$CASE' case_desc = '$CASE $CASESTR' rest_type = '$RUN_TYPE' ncpl = 24 data_dir = '$DATA_DIR' data_year0 = 5 data_nyear = 1 data_oyear = 1 flux_albfb = 1 / EOF
This section constructs the input namelist which is used to control runtime operation of the data component.
The "cat" command creates the file $EXEDIR/$MODEL.stdin with all the settings being evaluated to the current values of the specified environment variables.
| &inparm | is the namelist group name, which matches the groupname defined within the data component. |
|---|---|
| caseid | = $CASE (string) is a unique 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. |
| rest_type | = ' $RUN_TYPE ' (string) specifies the state in which the run is to be started. rest_type settings initial, branch and continue map into the CCSM variables (startup/hybrid branch and continue). |
| ncpl | = 24 (integer) sets the coupling frequency to 24 times per day. |
| data_dir | = '$DATA_DIR' (string) supplies the location of the input data directory to the code. |
| data_year0 | = 5 (integer) sets the first year of the input data to be year 5. |
| data_nyear | = 1 (integer) sets the total number of years to cycle the input data over to 1. |
| data_oyear | = 1 (integer) defines the coupler year corresponding to data_year0. This allows data with arbitrary dates to be input. |
| flux_albfb | = 1 (integer) enables the optional albedo feedback calculation. |
The data ocean component (docn) namelist has been modified to provide more functionality. The following variables have been removed: data_miss data_year0, data_rmlf, data_nyear and data_oyear.
The following namelist inputs appear in the data-ocean component.
| domain_file | = '$FILE_DOMAIN' (string) is the name name of domain netcdf file. |
|---|---|
| data_file | = '$FILE_SST' (string) is the input sea-surface temperature file. |
| data_form | = '$DATA_FORM' (string) describes the time configuration of the data either 'annual' or 'multiyear' DEFAULT is 'annual' |
| data_sstname | = '$DATA_SSTNAME' (string) is the name of the sst field on input data file. DEFAULT is 'T'. |
| data_lonname | = 'xc' (string) name of longitude coordinate on input data file. DEFAULT is 'xc' (can be one dimensional, or two dimensional for non-rectilinear coordinates) |
| data_latname | = 'yc' (string) name of latitude coordinate on input data file, DEFAULT is 'yc' (can be one dimensional, or two dimensional for non-rectilinear coordinates). |
echo ---------------------------------------------------------------------------
echo c. Build an executable in $EXEDIR/obj
echo ---------------------------------------------------------------------------
# Filepath: List of source code directories (in order of importance).
#--------------------------------------------------------------------
cd $OBJDIR
\cat >! Filepath << EOF
$SCRIPTS/src.$MODEL
$CSMCODE/atm/datm5
$CSMSHR
EOF
# Check to see if a new dims.h is needed.
cmp -s $CSMCODE/atm/datm5/dims.h.$ATM_GRID dims.h || \
cp $CSMCODE/atm/datm5/dims.h.$ATM_GRID dims.h || exit 3
The data component executable is build in $OBJDIR.
The filepath is 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 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.$MODEL, 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.
Next, the file containing the dimensions of the data component is positioned in $OBJDIR if it is different than the existing dimensions file.
# run make
#--------------------------------------------------------------------
if ($BLDTYPE == 'true') then
cc -o makdep $CSMBLD/makdep.c || exit 2
if ($NTHRD > 1) setenv THREAD TRUE
gmake -j 6 VPFILE=Filepath MODEL=datm EXEC=$EXEDIR/$MODEL \
-f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS || exit 2
else
echo "BLDTYPE = $BLDTYPE"
endif
In this last section the data component is built using gmake if $BLDTYPE is set to '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.cpl, is typically used to hold modified coupler 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.
# document the source code used, cleanup $OBJDIR files
#--------------------------------------------------------------------
grep 'CVS' *.[hf]*
#gmake -f $CSMBLD/Makefile MACFILE=$CSMBLD/Macros.$OS mostlyclean
echo ' '
echo ===========================================================================
echo End of setup shell script `date`
echo ===========================================================================
The final portion of the script documents the CVS tags of the source code and has an optional, commented out, line to clean up the object files that were created.
At this point, control is returned to test.a1.run.