Chapter 1. Introduction

Table of Contents
Changes from previous release
Getting Help -- Other User Resources

Version 5.1 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 Earth System Model (CESM) project. CAM is used as both a standalone model and as the atmospheric component of the CESM. 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 CESM.

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 the CCSM. One of the most significant software changes in CAM-4.0 was 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 (this also depended on the complete rewritting of the CCSM coupler to support sequential execution of the components). Hence, for the CESM1 model, just as for CCSM4 before it, it is accurate to say that the CAM standalone configuration is nothing more than a special configuration of CESM 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 CESM it can be run using the CESM scripts. This is done by using one of the "F" compsets and is described in the CESM-1.0 User's Guide. The main advantage of running CAM via the CESM scripts is to leverage the high level of support that those scripts provide for doing production runs of predefined experiments on supported platforms. The CESM 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 a lot 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. Issues that are specific to running CAM from the CESM scripts will not be discussed in this guide. Rather we focus on issues that are independent of which scripts are used to run CAM, although there is some attention given in this guide to the construction of simple scripts designed for running CAM in its standalone mode.

Changes from previous release

New features in CAM-5.1

  • Physics packages:

    • Final bug fixes and tuning of CAM-FV w/ cam5 physics on 1 and 2 deg grids.

    • Some tuning has been done to allow running the bulk aerosols with the cam5 physics package. Either prescribed bulk aerosols (as used by the cam4 physics package) or prognostic bulk aerosols (via the trop_bam chemistry option) can be used. The motivation was to provide a less expensive cam5 configuration which may be useful when aerosol indirect radiative effects are not the focus of the experiment.

    • The cam3 physics package has been restored. Using the configure argument -phys cam3 now gives a physics package that matches what was produced by the CAM3.1 model release. This is mainly useful in an aquaplanet configuration since the land component cannot be reverted to CLM3. To run an aquaplanet configuration that contains the customizations required by the intercomparison experiment protocol use the aquaplanet_cam3 use case (as an argument to build-namelist).

  • Dynamics packages:

    • Change default for number of FV vertical remappings per physics timestep. Was 1, but now set to 2 for 1/2 deg FV and finer grids. This changes answers for all high resolution (1/2 deg and finer) runs using FV dycore.

    • Allow subcycling in Eulerian dycore. See namelist variable eul_nsplit.

    • Add new low resolution FV grid: 2.5x3.33. The physics packages have not been tuned at this resolution.

  • Chemistry packages:

    • Extend unstructured grid functionality to modal aerosol package (trop_mam3). Because the modal aerosols are doing a dry deposition calculation on the atm grid, a new dataset is required when running the spectral element dycore (SE) on the cubed sphere grid (see namelist variable drydep_srf_file).

    • Provide more intuitive data-timing namelist variables. See, for example, the new *_cycle_yr, *_fixed_ymd, *_fixed_tod variables.

    • Update trop_mozart with latest MOZART4 mechanism.

    • Restore lighting NOx production in super_fast_llnl.

    • Give flexibility to the units of the emissions datasets.

    • Use more up-to-date dataset for waccm_ghg forcing.

    • Include CO2 reactions for WACCM to improve concentrations in upper regions

    • Updates to dry deposition module. The default for deposition velocity calculation is changed to be done in CLM except when modal aerosols are active.

    • Provide an additional optional wet deposition method for gas phase chemical species.

    • Include short wavelength photolysis in tropospheric chemistry.

    • New treatment of WACCM stratospheric aerosols.

    • New chemistry package added : trop_strat_bam_v1.

    • Provide dynamic creation of default deposition species lists namelist settings using master lists.

    • Correction to the wet deposition lists of species for super_fast_llnl, and waccm_mozart.

    • Correction to the configure options for the offline driver regression test.

  • Diagnostics:

    • All new diagnostics that are being produced for the CESM CMIP5 contributions are available in this release.

    • The COSP implementation has been updated to work with the cam5 physics package.

    • An option was added to the COSP simulator to allow it to be run on a subset of the timesteps when the radiation code is run. See the namelist variable cosp_nradsteps.

  • History output:

    • Add ability to interpolate fields on the SE dycore's grid (cubed sphere) to a rectangular grid for history output. See namelist variables interpolate_analysis, interp_nlat, interp_nlon, interp_gridtype, and interp_type. This is off by default.

    • Option for history output (columns) along a specified track. See namelist variables sathist_track_infile, sathist_fincl, sathist_mfilt, and sathist_hfilename_spec.

    • Option for history output to be averaged over local time zones. See namelist variables lcltod_start and lcltod_stop.

    • Add ability to have more than three non-time dimensions in output variables. This removes the need to use the vertical dimension as a mixed or combined coordinate which was the common workaround in the past.

    • Option for history output of multiple single columns. The default is for single column specifications to be output as separate variables. This option allows all single columns specified in a history file to be written as a single variable using the same format that is used to output unstructured grid data. The option is enabled by the new namelist variable collect_column_output. The reason for implementing this option is for efficiency in writing single column output.

  • configure and build-namelist:

    • Add argument to configure (-fc_type) to allow specifying which type of Fortran compiler is being used when that compiler is being invoked via a generic script (e.g., mpif90 or ftn). This is only used by CAM standalone builds.

    • Add argument to build-namelist (-ntasks) to produce default FV decomposition settings (npr_yz). This functionality was previously embedded in the CESM scripts and was not available to user's of CAM standalone scripts.

    • Add use cases for the RCP CMIP5 experiments.

Summary of answer changes

The only configuration of CAM-5.1 that preserves answers bit-for-bit with the previous release is the cam4 physics package, in aqua-planet mode, and at FV resolutions courser than 1/2 degree. The cam4 physics package was used for the majority of the CESM runs runs submitted to CMIP5.

The following summarizes the answer changes between CAM-5.1 and CAM-5.0.

  • All configurations using the CAM-5.1 physics package have a different climate from the CAM-5.0 version. This is due to bug fixes and retuning. This is the default physics package. It may also be explicitly specified with the argument "-phys cam5" to configure.

  • All configurations using the cam3 physics package "-phys cam3" have a different climate from the previous version. This is due to refactoring to restore the results that were produced by the CAM-3.1 model release.

  • All configurations using the FV dycore at resolutions of 1/2 degree and finer will have climate changes due to several changes designed to improve the high resolution stability.

  • Chemistry scenario "-chem super_fast_llnl" has climate changes due to wet deposition and lightning NOx production.

  • Chemistry scenario "-chem trop_mozart" has climate changes due to updates to the latest MOZART4 mechanism and to including short wavelength photolysis.

  • Chemistry scenario "-chem waccm_mozart" has climate changes due to adding CO2 reactions, a new treatment of stratospheric aerosols, and wet deposition changes.

  • Chemistry scenario "-chem waccm_mozart_v1" has only climate preserving answer changes (correction to the O1D + CCL4 -> 4*CL reaction). This is the mechanism that has been used in the CESM WACCM runs for CMIP5.

Code cleanup and refactoring

  • Modify code to consistently save and reuse the physics buffer indicies rather than invoking a linear search for the indices wherever they are needed.

  • Start refactoring modal_aer_opt module to make use of the rad_constituent interfaces. This will eventually provide a prescribed modal aerosol capability and fully functioning diagnostic calculations for radiative forcing.

  • Implement separate drivers for the cam5 macrophysics and microphysics. The driver for the cam4 macro/micro physics remains in stratiform.F90.

  • Microphysics changes:

    • Remove unnecessary passed variables and use statements for the CAM5 cloud microphysics (cldwat2m_micro.F90)

    • Add functionality for a logical flag called 'sub_column' to be passed to the CAM5 microphysics that changes how it works, but with the flag set (false) to reproduce the standard code (cldwat2m_micro.F90)

  • Refactoring in cam history to allow for extra dimensions in output fields beyond the current spatial/temporal ones. Previously the fields in a history file time sample only had (lon,lat,lev,time) or (ncol,lev,time) dimensions. The "addfld" calls allowed lev to be set to 1, plev or plevp. To work around this constraint in the past optional flags were added to the addfld subroutine that allowed more values of lev, but this workaround did not provide extra dimensions. In cases where multiple non-horizontal dimensions were needed, e.g., level and optical depth, or level and subcolumn, the technique employed was to combine multiple dimensions into a single mixed dimension. We have eliminated the need to do that (in the output field only -- internal data structures still require this mixed dimension). Optional arguments have been added to the addfld subroutine which allow defining multiple dimensions rather than just a single "lev" dimension.

  • Add new namelist groups to the dycores. Continue to move namelist variables out of the generic cam_inparm group.

  • The old ISCCP simulator has been removed. The current ISCCP simulator is available as part of the COSP package.

Bugs fixed

  • CAM5 micro/macro physics:

    • A fix to immersion freezing (small changes).

    • Fixing the diagnostic output FICE to trap for roundoff errors (diagnostic only).

    • Bug fix for subgrid cloud water treatment in contact nucleation (small changes).

    • Bug fix for size of snow particles used in radiation (they get smaller by a factor of 3 and more reflective: some impact).

    • Fix to guarantee the in-stratus LWC to be within the specified range even when the cloud fraction is very small (< 1.e-5 ).

    • Fix to prevent model crash by dividing by near zero cloud fraction in the droplet activation routine.

  • Chemistry:

    • Corrected vertically integrated wet deposition rates diagnostics.

    • Corrected MASS and AREA output fields.

    • Corrected chemical prod/loss rates diagnostics.

  • State variables now output time-averaged by default when "budget_history" is true.

  • Fix a bug in call to conv_water_4rad that would lead to erroneous results with conv_water_in_rad=2 option if invoked.

Known bugs

  • "-chem trop_mam7" currently not working. This is a side effect of a partial code refactoring in modal_aer_opt.