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.
% 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:
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.
Before a SOM run can be initiated, a boundary dataset must be built which contains SOM-specific information. Required steps are:
./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.
./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".