User's Guide to NCAR CAM2.0 Search Page

Appendix B: Details of the configuration files

The configure utility creates the header files misc.h, params.h, and preproc.h and the directory search path file Filepath. These files are written to the directory given by the -cam_bld argument of configure (the default is the directory from which configure is executed). It is not necessary to edit these files to produce supported CAM configurations as that can be easily accomplished by the configure utility. However, a user experimenting with non-standard configurations may need to edit these files directly. Thus, the file contents are summarized below. The use of these files by gmake is also discussed below in the section "Details of gmake procedure".

• Filepath
Contains a list of directories used by gmake to determine the list of source files to build. All source files listed by the filename expansion expressions *.F90, *.F, and *.c in each of the directories are included in the build. It a given filename occurs in more than one of the directories, it is the version in the first directory of the list that will be built. The list of directories in Filepath will vary with target architecture and depend on the specified dynamics and physics packages.
• misc.h
Contains a list of resolution-independent cpp directives. The following cpp tokens must either be defined or undefined (i.e. preceded by #define or #undef).

Table C.1: misc.h pre-processor tokens

misc.h cpp tokens	Synopsis
COUP_CSM	Define if the flux-coupled ocean configuration will be used.  COUP_CSM is always undefined for stand-alone mode.
PERGRO	Define if you want to make error growth tests with your model simulation. This token turns off parts of the prognostic cloud water parameterization so that the error growth happens at a reasonable rate. Default setting is with PERGRO undefined.
USEFFTLIB	Define if you want to use a intrinsic FFT package rather than the ECMWF FFT package provided with the code in the "models/atm/cam/src/utils" directory. Default setting is USEFFTLIB undefined.
SPMD	Enables the distributed memory (SPMD) implementation.
STAGGERED	Enables staggered grid processing.  Required for use with the Lin-Rood dynamical core, otherwise undefined.

• params.h
Contains a list of resolution-dependent cpp directives for the atmosphere model.

Table C.2: params.h pre-processor tokens

params.h cpp tokens	Synopsis
PCNST	Number of advected constituents including water vapor and cloud-water.  Default setting is 1 (for water vapor).
PNATS	Number of non-advected constituents.  Default setting is 1 (for cloud water).
PLEV	Number of vertical levels.  Default setting is 26.
PLEVR	Number of vertical levels over which radiation calculations are performed. Use of separate vertical coordinate for the radiation calculation has not been tested. Therefore this directive must currently be set to the same value as PLEV.
PLON	Number of longitudes on the transform grid.  Default setting is 128.
PLAT	Number of Gaussian latitudes on the CAM2.0 transform grid.  Default setting is 64.
PCOLS	Maximum number of columns to use for the physics. This value can be tuned for different computer architectures in order to increase performance. Default setting is 16.
PTRM	Spectral truncation of the zonal wavenumber m.  Default setting is 42.
PTRN	Spectral truncation of the total wavenumber n for zonal wavenumber 0.  Default setting is 42.
PTRK	Maximum total wavenumber k, for any zonal wavenumber m.  Default setting is 42.

• preproc.h
Contains a list of resolution-dependent cpp tokens for the land-model code. Currently the resolution of the land-model must be the same as that of the atmospheric component. Table C.3: preproc.h pre-processor tokens

preproc.h cpp tokens	Synopsis
COUP_CAM	Tell the CLM that it is being run as a subroutine beneath the atmospheric model.
LSMLON	Number of longitudes for the landmodel grid. Currently this directive must have the same value as PLON in params.h.
LSMLAT	Number of latitudes for the land-model grid. Currently this directive must have the same value as PLAT in params.h.

cpp directives of the form #include, #if defined, etc., are used to enhance portability, and allow for the implementation of distinct blocks of platform-specific code within a single file. Header files, such as misc.h, are included with #include statements within the source code. When gmake is invoked, the C preprocessor includes or excludes blocks of code depending on which cpp tokens have been defined. cpp directives are also used to perform textual substitution for resolution-specific parameters in the code. The format of these cpp tokens follows standard cpp protocol in that they are all uppercase versions of the Fortran variables, which they define. Thus, a code statement like

    parameter(plat = PLAT)

will result in the following processed line (for standard T42 resolution).

     parameter(plat = 64)

gmake invokes the utility mkSrcfiles to generate a list of source files (written to the file Srcfiles) using each directory listed in Filepath. gmake then invokes the utility mkDepends to create a dependency file (written to the file Depends) in the CAM build directory. If a file listed as a dependency does not exist in the CAM build directory, gmake searches the directories contained in Filepath, in the order given, for a file with that name. The first file found satisfies the dependency. If user-modified code is to be introduced, Filepath should contain, as the first entry (or entries), the directory containing the user code. User code directories are specified with the -usr_src option to configure.

A parallel gmake is achieved in the build scripts by using gmake with the -j option, which specifies the number of jobs (commands) to run simultaneously.

 Search page

Questions on these pages can be sent to... erik@ucar.edu .