2.3 Use Cases

This section provides a few examples of using configure and build-namelist to set up a variety of model runs. These examples were chosen to illustrate many of the configuration and namelist options described above and in the section named CAM Namelist Variables (B). They do not discuss the intricacies of running CAM 3.0 on its various supported platforms; a discussion of that topic may be found in the section named Sample Run Scripts (2.4). The following use cases have been tested on a linux PC using the Portland Group compiler (pfg90).

These examples assume a stand-alone configuration of CAM 3.0. Furthermore, it is assumed that the root directory for the CAM 3.0 dataset distribution is /data. (The root directory contains the subdirectories atm and lnd.)

The examples in this section all assume that the CAM configuration script directory is located in the standard place within the CAM distribution. It is also assumed that the CAM configuration directory is not in the user's PATH environment variable. For this reason the configure script must be invoked using an absolute pathname. The script attempts to use the pathname that it was invoked with to determine the configuration script directory. If this is successful then configure can determine the CAM root directory without the user needing to set the CAM_ROOT environment variable.

2.3.1 Configuring and running the default CAM executable

The following interactive C shell session builds a default production version of CAM. The shell variable tmpdir is set to a working directory on the user's system, and camcfg is set to the CAM configuration directory ($CAM_ROOT/models/atm/cam/bld). The following output is from a linux system, but will appear similar on other machines.

% cd $tmpdir
% $camcfg/configure -test 
creating /big/data/temp/Filepath
creating /big/data/temp/params.h
creating /big/data/temp/misc.h
creating /big/data/temp/preproc.h
creating /big/data/temp/Makefile
creating /big/data/temp/config_cache.xml
Looking for a valid GNU make... using gmake
Testing for Fortran 90 compatible compiler... using pgf90
Testing NetCDF library... ok
configure done.
% gmake -j2  >&! make.out
% setenv CSMDATA /data
% $camcfg/build-namelist -test
Write out namelist to: namelist
% ./cam < namelist >&! output.txt

We started by changing into the directory in which the CAM executable will be built. All the files produced by configure except for the cache file are required to be in the CAM build directory, so it is generally easiest to be in that directory when configure is invoked. This example was carried out on a linux machine. We recommend using the -test option the first time CAM is built on any machine. This will check that the environment is properly set up so that the Fortran compiler works and can successfully link to the NetCDF and MPI (if SPMD enabled) libraries. The testing tells us that gmake is a GNU Make on this machine, that the Fortran compiler is pgf90, and that the compiler can successfully reference the NetCDF library.

We then issued the gmake command with a -j2 option, which tells gmake to use 2 processors for the build. Output from the make, including the messages issued to STDERR, are redirected to the file make.out. In the event of an error during the build, the make.out file will contain the command that was issued by gmake that resulted in the error.

Next we set the environment variable CSMDATA to point to the root of the input data distribution (where we unpacked the intput dataset tar files).

Next we issued the build-namelist command. The first time a namelist for a particular CAM configuration is produced, we recommend using the -test option which checks whether the initial and boundary datasets exist on a local filesystem. If they do not then a warning is issued to inform the user which datasets must be copied to the directory from which CAM will be run.

The execution of build-namelist with -test produces the following default namelist:
&camexp
ABSEMS_DATA = '/data/atm/cam2/rad/abs_ems_factors_fastvx.c030508.nc'
AEROPTICS = '/data/atm/cam2/rad/AerosolOptics_c040105.nc'
BNDTVAER = '/data/atm/cam2/rad/AerosolMass_V_64x128_clim_c031022.nc'
BNDTVDMS = '/data/atm/cam2/rad/DMS_emissions_64x128_c030722.nc'
BNDTVGHG = '/data/atm/cam2/ggas/ghg_1870_2100_c040122.nc'

 bndtvo         = '/data/atm/cam2/ozone/pcmdio3.r8.64x1_L60_clim_c970515.nc'
 bndtvoxid              = '/data/atm/cam2/rad/oxid_3d_64x128_L26_c030722.nc'
 bndtvs         = '/data/atm/cam2/sst/sst_HadOIBl_bc_64x128_clim_c020411.nc'
 bndtvscon              = '/data/atm/cam2/rad/scon_1870_2100_c040122.nc'
 bndtvsox               = '/data/atm/cam2/rad/SOx_emissions_64x128_L2_c030722.nc'
 bndtvvolc              = '/data/atm/cam2/rad/VolcanicMass_1870-1999_64x1_L18_c040115.nc'
 caseid         = 'camrun'
 iyear_ad               = 1950
 ncdata         = '/data/atm/cam2/inic/gaus/cami_0000-09-01_64x128_L26_c030918.nc'
 nelapse                = -1
 nsrest         = 0
/
&clmexp
 finidat                = '/data/lnd/clm2/inidata_2.1/cam/clmi_0000-09-01_64x128_T42_USGS_c030609.nc'
 fpftcon                = '/data/lnd/clm2/pftdata/pft-physiology'
 fsurdat                = '/data/lnd/clm2/srfdata/cam/clms_64x128_USGS_c030605.nc'
/

build-namelist used the configuration cache file (config_cache.xml) that was produced by configure to determine the dynamics package, land model, and resolution of the CAM executable. This information was used to choose the default initial and boundary datasets. The default run type is an initial run (nsrest=0), the run length is 1 day beyond the date of the initial conditions (nelapse=-1), and the valid year for the calculated orbital parameters is 1950 (iyear_ad=1950).

The absence of warnings from build-namelist indicates that all the initial and boundary datasets were found on the local filesystem.

Finally, we execute the cam executable and tell it to read its standard input from the namelist file. On systems that support running in SPMD mode this command line will be more complicated, and will typically involve a poe (on NCAR's IBM AIX machines) or a mpirun (on linux clusters) command. Please see the section named Sample Run Scripts (2.4) for details.

When the model is done executing, the directory should contain the files:

camrun.cam2.r.0000-09-02-00000
camrun.cam2.rh0.0000-09-02-00000
camrun.clm2.r.0000-09-02-00000

These are, respectively, a CAM master restart file, a CAM history buffer restart file, and a CLM restart file. There is no regular CAM history file because by default these are output monthly, and this was only a one day run.

2.3.2 Using the Slab Ocean Model (SOM)

The default prescribed-SST, prescribed-ice configuration of the standalone CAM model can be swapped out and replaced with a mixed-layer slab ocean model (SOM). Mixed layer temperature is the prognostic variable output from SOM. The thermodynamic ice model configured with SOM is the same as in CAM when run in prescribed-ice mode, with two additions. First, ice fraction is predicted rather than read from a boundary dataset. Second, ice thickness is also predicted, rather than fixed at 2 meters in the northern hemisphere and 1 meter in the southern hemisphere. Since SOM-configured CAM is run on the same horizontal grid as CAM, the CCSM flux coupler is not used.

Before a SOM run can be initiated, a boundary dataset must be built which contains SOM-specific information. Required steps are:

1)

Define annually averaged mixed layer depths at the target horizontal resolution. Instructions for this procedure are contained in subdirectory models/atm/cam/tools/definemld of the CAM source tree. From this directory, an example sequence of commands to define mixed layer depths (after running gmake) might be:

./definemld1x1 -m mldfile.nc -v
./definemldbdy -s 10 -v -i mldfile.nc -o sst.nc

The first command creates mixed layer depth information at a horizontal resolution of 1 degree by 1 degree from ASCII input files, which are provided in the directory. The next command averages these data to the horizontal grid defined by a template file (sst.nc in the example). The mixed layer depths are written to the template file. A good choice for a template file is an existing prescribed ice/SST dataset at the desired resolution.

2)

Define surface flux balance information from a control run which was done with prescribed ice and SSTs. Detailed build and execute instructions are contained in subdirectory models/atm/cam/tools/defineqflux. After building the executable, the command to construct the final boundary dataset looks something like:

./defineqflux -f firstfile_fromcontrolrun -l lastfile_fromcontrolrun -s sst.nc -v

The sequence of monthly history files from a control run is defined by the arguments to "-f" and "-l". All monthly data defined by these time boundaries must be in the working directory before running defineqflux. Output flux balance variables are written to the output file defined by the "-s" argument. Both the control run and the output file must be at the same horizontal resolution.

Example boundary dataset sst.nc is now ready for use by a SOM-enabled CAM. To configure CAM to be run in SOM mode, Filepath must be modified to include som instead of dom. Secondly, cpp token COUP_SOM must be defined in the file misc.h. Both of these tasks can be accomplished by running configure with "-ocn som".

3)

Once CAM has been built with SOM as the underlying ocean model, namelist variable "bndtvs" needs to point to the SOM-specific boundary dataset described above. Since ocean surface temperature (i.e. mixed layer temperature) is a prognostic variable when SOM is enabled, model equilibration times are generally much longer than when SSTs and ice fraction are prescribed. Forty years or more of integration time may be needed for the model to reach a quasi-equilibrium state. Annually averaged mixed-layer depths (described above) are capped at 200 meters to prevent even longer equilibration times.