Chapter 1. Introduction

Note: This User's Guide is under active development. It was last modified on 3 April 2010.

Version 4.0 of the Community Atmosphere Model (CAM) is the latest in a series of global atmosphere models originally developed at the National Center for Atmospheric Research (NCAR). The current development of CAM is guided by the Atmosphere Model Working Group (AMWG) of the Community Climate System Model (CCSM) project. CAM is used as both a standalone model and as the atmospheric component of the CCSM. CAM has a long history of use as a standalone model by which we mean that the atmosphere is coupled to an active land model (CLM), a thermodynamic only sea ice model (CICE), and a data ocean model (DOCN). When one speaks of "doing CAM simulations" the implication is that it's the standalone configuration that is being used. When CAM is coupled to active ocean and sea ice models then we refer to the model as CCSM.

In versions of CAM before 4.0 the driver for the standalone configuration was completely separate code from what was used to couple the components of CCSM. One of the most significant software changes in CAM-4.0 is a refactoring of how the land, ocean, and sea ice components are called which enabled the use of the CCSM coupler to act as the CAM standalone driver (note that this also depended on the complete rewritting of the CCSM coupler to support sequential execution of the components). It is now accurate to say that the CAM standalone configuration is nothing more than a special configuration of CCSM in which the active ocean and sea ice components are replaced by data ocean and thermodynamic sea ice components.

Since the CAM standalone model is just a special configuration of CCSM it can be run using the CCSM scripts. This is done by using one of the "F" compsets and is described in the CCSM-4.0 User's Guide. The main advantage of running CAM via the CCSM scripts is to leverage the high level of support that those scripts provide for doing production runs of predefined experiments on supported platforms. The CCSM scripts do things like: setting up reasonable runtime environments; automatically retrieving required input datasets from an SVN server; and archiving output files. But CAM is used in alot of environments where the complexity of production ready scripts is not necessary. In these instances the flexibility and simplicity of being able to completely describe a run using a short shell script is a valuable option. In either case though, the ability to customize a CAM build or runtime configuration depends on being able to use the utilities described in this document. Any build configuration can be set up via appropriate commandline arguments to CAM's configure utility, and any runtime configuration can be set up with appropriate arguments to CAM's build-namelist utility.

Much of the example code in this document is set off in sections like this.
Many examples refer to files in the distribution source tree using
filepaths that are relative to distribution root directory, which we denote
by $CAM_ROOT.  The notation indicates that CAM_ROOT is a shell variable
that contains the filepath.  This could just as accurately be referred to
as $CCSM_ROOT since the root directory of the CCSM distribution is the
same as the root of the CAM distribution which is contained within it.

Getting Help -- Other User Resources

The CAM Web Page

The central source for information on CAM is the CAM web page.

The CAM Bulletin Board

The CAM Bulletin Board is a moderated forum for rapid exchange of information, ideas, and topics of interest relating to the various versions of CAM. This includes sharing software tools, datasets, programming tips and examples, as well as discussions of questions, problems and workarounds. The primary motivation for the establishment of this forum is to facilitate and encourage communication between the users of the CAM around the world. This bulletin board will also be used to distribute announcements related to CAM.

The CAM Bulletin Board is here:

Reporting bugs

If a user should encounter bugs in the code (i.e., it doesn't behave in a way in which the documentation says it should), the problem should be reported electronically to the CAM Bulletin Board. When writing a bug report the guiding principle should be to provide enough information so that the bug can be reproduced. The following list suggests the minimal information that should be contained in the report:

  1. The version number of CAM (or CCSM if CAM was obtained as part of a CCSM distribution).

  2. The architecture on which the code was built. Include relevent information such as the Fortran compiler, MPI library, etc.

  3. The configure commandline.

  4. The build-namelist commandline.

  5. Model printout. Ideally this would contain a stack trace. But it should at least contain any error messages printed to the output log.

Please note that that CAM is a research model, and not all features are supported.