CESM Models

CCSM4/CESM1 Output Filename Requirements

21 February 2011

This document presents naming conventions for CESM output files, which fall into two broad categories: those files generated by the CCSM4/CESM1 component models at run-time ("model output data") and those created by post-processing the run-time files ("post-processed data"). This document describes the filename conventions of both types of files, for both CCSM4 and CESM.

At the present time, this document does not describe the output files generated by the data-assimilation version of the CESM ("dart" files).

1. CESM Model Output Data Filenames

The general filename formats for output files generated at run-time by the CESM component models are:

$output = $CASE.$scomp.$type.[$string.]$date[$ending]
$log = $CASE.$gcomp.$ltype.$logdate

where:

CCSM3 model developers were required to conform to the following points. Many of them are still valid for CESM:

2. CESM Model Output File Locations

Depending on the stage of the model execution and the options selected in the CESM case, run-time output files will reside in different locations. See the CESM User's Guide for the definitions of $RUNDIR, $DOUT_S_ROOT, and $DOUT_L_MSROOT and how they are set.

Example of Long-Term Archive Filenames:

The * below represents an "optional" character.

/$DOUT_L_MSROOT/$CASE/atm/hist/$CASE.cam2.h*.yyyy-mm.nc
........................./hist/$CASE.cam2.h*.yyyy-mm-dd-sssss.nc
........................./init/$CASE.cam2.i.yyyy-mm-dd-sssss.nc
......................lnd/hist/$CASE.clm2.h*.yyyy-mm.nc
........................./hist/$CASE.clm2.h*.yyyy-mm-dd-sssss.nc
......................ocn/hist/$CASE.pop.h*.yyyy-mm.nc
........................./hist/$CASE.pop.hm.yyyy-mm-dd-sssss.nc (movie stream)
........................./hist/$CASE.pop.hs.yyyy-mm-dd-sssss.nc (snapshot stream)
......................ice/hist/$CASE.cice.h.yyyy-mm.nc
........................./init/$CASE.cice.i.yyyy-mm-dd-sssss.nc
......................cpl/hist/$CASE.cpl.h*.yyyy.nc
........................./hist/$CASE.cpl.h*.yyyy-mm.nc
........................./hist/$CASE.cpl.h*.yyyy-mm-dd.nc
........................./hist/$CASE.cpl.h*.yyyy-mm-dd-sssss.nc
......................rest/yyyy-mm-dd-sssss/$CASE.cam2.h0.YYYY-12.nc
........................../yyyy-mm-dd-sssss/$CASE.cam2.i.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.cam2.r.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.cam2.rs.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.cice.r.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.clm2.h0.YYYY-12.nc
........................../yyyy-mm-dd-sssss/$CASE.clm2.r.yyyy-01-01-00000
........................../yyyy-mm-dd-sssss/$CASE.clm2.r.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.cpl.r.yyyy-01-01-00000.nc
........................../yyyy-mm-dd-sssss/$CASE.pop.r.yyyy-01-01-00000
........................../yyyy-mm-dd-sssss/$CASE.pop.r.yyyy-01-01-00000.hdr
........................../yyyy-mm-dd-sssss/$CASE.pop.ro.yyyy-01-01-00000
........................../yyyy-mm-dd-sssss/$CASE.rpointer.atm
........................../yyyy-mm-dd-sssss/$CASE.rpointer.drv
........................../yyyy-mm-dd-sssss/$CASE.rpointer.ice
........................../yyyy-mm-dd-sssss/$CASE.rpointer.lnd
........................../yyyy-mm-dd-sssss/$CASE.rpointer.ocn.ovf
........................../yyyy-mm-dd-sssss/$CASE.rpointer.ocn.restart
........................../yyyy-mm-dd-sssss/$CASE.rpointer.ocn.tavg

where YYYY = one year prior to yyyy.

3. Post-Processed Data Filenames

In the preceding section, naming conventions were established for model output data files generated by the CESM model as it executes. In this section, the conventions are extended in order to define rules for data files that result from the post-processing of CESM model output data.

Post-processed data files may include temporal averages (eg, seasonal, annual, or decadal), spatial averages (eg, zonal, meridional, global), timeseries, or other diagnosed quantities (eg, meridional overturning streamfunction, barotropic streamfunction). The following rules are intended to provide a consistent structure for naming each of these types of files.

The development of these naming conventions was guided by the desire to:

Users are free to use their own naming conventions in their own personal directories, but filenames of all data files that are written to NCAR HPSS /CCSM/csm/ directories must follow the conventions described in this document.

If there are particular post-processing circumstances that are not addressed in this document, it is important to discuss them with CSEG first, prior to creating non-standard filenames. Only after the issues have been resolved and the documentation updated should the files be created with new naming conventions.

3.1 Filename Requirements for Post-Processed CESM Data

Data files which result from the post-processing of /CCSM/csm model output may be stored in the /CCSM/csm directory on the NCAR mass-storage system only if the filenames conform to the following general format:

$DIRNAME/$FILENAME

where

$DIRNAME = /CCSM/csm/$CASE/$gcomp/$subdir/$tdir/$tperiod

$FILENAME = $CASE.$scomp.$type.$SSTRING.[$TPREFIX.]$TSTRING[.$ending]

quantities within square brackets [] are optional, and $CASE, $gcomp, $scomp, and $type are as defined in Section 1.

The following are definitions of the various components of $DIRNAME and $FILENAME; note that several examples follow below, to illustrate the use of these options.

IMPORTANT NOTE: Because of character-string limitations on the NCAR MSS, the above TSTRING conventions were unable to be followed for CCSM4/CESM CMIP5 cases. So from April 2010 until the retirement of the NCAR MSS in 2011, the following departures from conventions were in effect:

The upshot is that a postprocessed file that should have been named, for example:

/CCSM/csm/b40.20th.track1.1deg.007/lnd/proc/tseries/monthly/b40.20th.track1.1deg.007.clm2.h0.QSNWCPICE_NODYNLNDUSE.1850-01_cat_2005-12.nc

(138 characters long) was written instead as

/CCSM/csm/b40.20th.track1.1deg.007/lnd/proc/tseries/monthly/b40.20th.1deg.007.clm2.h0.QSNWCPICE_NODYNLNDUSE.185001-200512.nc

(125 characters) which is under the character limit. Note that the $CASE is never changed in the path, just in the actual filename.

3.1.1 Standard Filename String Names

Several descriptive names have been identified as "standard" CESM analysis string names and are therefore restricted to the meaning defined below. Presently, standard names have been established only for post-processed ocean files. Users of other CESM components are encouraged to submit additional candidates for standard string names, and should be free to develop suitable descriptive string names to suit their own applications, as long as they do not conflict the the reserved strings listed below.

In the event that more than one, but not all, of the original component output fields are extracted into a processed file, the user must decide how to describe the file contents. For a small number of fields, the user may decide that it is best to combine the individual field names, such as UVEL_VVEL_WVEL. For a large number of fields, the user may instead decide to define a meaningful string which describes the collection of fields. The user who decides to define such a string must register that string name with the CSEG prior to storing the files in the official proc or ipcc directories.

3.1.2 Examples

Combinations of the various string names are intended to provide sufficient flexibility to describe the file contents. The following examples are used to illustrate standard practices:

3.1.3 Conventions for Ensemble Averages

Conventions for Ensemble-Average files have not been addressed by this document. The development of good filenaming conventions for these ensemble-average files will require thoughtful analysis of existing requirements.