Introduction (CESM2.1)

How To Use This Document

This guide instructs both novice and experienced users on downloading, building and running CESM2.

CESM2 is built on the CIME framework.

The majority of the CESM2 User’s Guide is contained in the CIME documentation.

If you are a new user, we recommend reading the first few sections of the CIME documentation which is written so that, as much as possible, individual sections stand on their own and the CIME documentation guide can be scanned and sections read in a relatively ad hoc order.

Throughout the guide, this presentation style indicates shell
commands and options, fragments of code, namelist variables, etc.


Variables presented as $VAR in this guide typically refer to variables in XML files in a CESM case. From within a case directory, you can determine the value of such a variable with ./xmlquery VAR. In some instances, $VAR refers to a shell variable or some other variable; we try to make these exceptions clear.

Please feel free to provide feedback to the CESM forum about how to improve the documentation.

CESM Model Version Naming Conventions

CESM model release versions include three numbers separated by a period (.) - CESM X.Y.Z

  • X - corresponds to the major release number indicating significant science changes.

  • Y - corresponds to the addition of new infrastructure and new science capabilities for targeted components.

  • Z - corresponds to release bug fixes and machine updates.

When refering to CESM2, it is understood that the all versions of the CESM2.Y.Z series of models are included.

CESM Overview

The Community Earth System Model (CESM) is a coupled climate model for simulating Earth’s climate system. Composed of separate models simultaneously simulating the Earth’s atmosphere, ocean, land, river run-off, land-ice, and sea-ice, plus one central coupler/moderator component, CESM allows researchers to conduct fundamental research into the Earth’s past, present, and future climate states.

CESM can be run on a number of different hardware platforms, and has a relatively flexible design with respect to processor layout of components.

The CESM project is a cooperative effort among U.S. climate researchers. Primarily supported by the National Science Foundation(NSF) and centered at the National Center for Atmospheric Research (NCAR) in Boulder, Colorado, the CESM project enjoys close collaborations with the U.S. Department of Energy (DOE) and the National Aeronautics and Space Administration (NASA). Scientific development of the CESM is guided by the CESM working groups, which meet twice a year. The main CESM workshop is held each year in June to showcase results from the various working groups and coordinate future CESM developments among the working groups. The CESM website provides more information on the CESM project, such as the management structure, the scientific working groups, downloadable source code, and online archives of data from previous CESM experiments.

CESM2 Software/Operating System Prerequisites

The following are the external system and software requirements for installing and running CESM2.


NetCDF must be built with the same Fortran compiler as CESM. In the netCDF build the FC environment variable specifies which Fortran compiler to use. CESM is written mostly in Fortran, netCDF is written in C. Because there is no standard way to call a C program from a Fortran program, the Fortran to C layer between CESM and netCDF will vary depending on which Fortran compiler you use for CESM. When a function in the netCDF library is called from a Fortran application, the netCDF Fortran API calls the netCDF C library. If you do not use the same compiler to build netCDF and CESM you will in most cases get errors from netCDF saying certain netCDF functions cannot be found.

Parallel-netCDF, also referred to as pnetcdf, is optional. If a user chooses to use pnetcdf, version 1.7.0 or later should be used with CESM. It is a library that is file-format compatible with netCDF, and provides higher performance by using MPI-IO. Pnetcdf is enabled by setting the $PNETCDF_PATH Makefile variable in the Macros.make file.