CCSM3 Output Filename Requirements

The general format for CCSM3 output files is

/$LOG/$CASE/$gcomp/subdir/$CASE.$scomp.$type.yyyy-mm-dd-sssss[.$ending]
[loc]/$CASE/$gcomp/subdir/$CASE.$scomp.$type.yyyy-mm-dd-sssss[.$ending]
....................[loc]/$CASE.$scomp.$type.yyyy-mm-dd-sssss[.$ending]

gcomp = [atm,lnd,ocn,ice,cpl]
subdir = [rest,init,hist]
scomp = [cam2,clm2,pop,csim,cpl,dice5]
type = r(restart), i(initial), h(history), d(diagnostic), rh(restart history), rd(restart diagnostic) followed by [a-z,0-9] optional
ending = "", .nc, .hdr

• $CASE is normally 7 chars (bnn.nnn) for CCSM, but is not limited to this length. $CASE should be coded as a 16 character string. $CASE in the filename is required for CCSM but can be implemented as an optional namelist at the components' discretion.
• $gcomp is the generic component name as defined above. It should be coded as an 8 character string.
• $scomp is the specific component name. The CCSM standard naming convention is above. $scomp in the filename is required for CCSM but can be implmented as an optional namelist at the components' discretion. $scomp should be code as an 8 character string.
• $type is one or two chars except for incomplete history files with are required for restart and those have an r appended in front of their history type.
• $ending can only be one of the specific types indicated above.
• All dates should be based on a yyyy-mm-dd-sssss convention. 0 <= sssss < 86400. If necessary, yyyy can be increased to more than 4 digits, 4 digits is the minimum.
• Dates in files should use the current naming standard depending on the type of file. For undefined date naming conventions, users must negotiate an appropriate naming convention with the rest of ccsm and then a standard will be added to this document.
  • yyyy-mm-dd-sssss = instantaneous time (ie, snapshot, initial or restart)
  • yyyy-mm-dd = daily average file
  • yyyy-mm = monthly average file
  • yyyy = annual average file
  • yyyy-mm-dd-sssss = first timestamp of data on other history file
  • yyyy-mm-dd-sssss = "restart" timestep for incomplete history files
• Restart dates are for the current timestep to run, so would be, for example, 0002-01-01-00000 if written at the end of year 1, month 12.
• Model output data streams should conform to these standards as much as possible. Unique diagnostic files or other output files could have some non-standard naming conventions if that makes them easier to identify.
• Filename conventions for processed model output data are presented in Section 2
• All restarts look like $CASE.$scomp.r*.yyyy-mm-dd-sssss or information is in the rpointer files about what auxiliary files are required either as a comment or as informational.
• All histories look like $CASE.$scomp.h*.[date][$ending]. The second char of the type is left up to the developer. There are no requirements.
• All monthly average history files look like $CASE.$scomp.h*.yyyy-mm.nc. The date string (NOT THE TYPE) tells you whether the file is yearly, monthly, daily averaged or other.
• Histories and restart histories are connect via $CASE.$scomp.h* and $CASE.$scomp.rh* even though the dates might be quite different. The dates for restart histories must conform with the restart date. The date for histories are set by the averaging strategy or the last date data was written.
• $CASE is picked up in the component models via namelist.
• If models can write to the mass store, they should have a namelist input to set the mass store root. This is not a requirement.
• Care must be used when not using the optional character. For instance, for a case where you might have $CASE.$scomp.h.yyyy.nc and $CASE.$scomp.h.yyyy-mm.nc for an annual average and monthly average outputs, the date makes the files unique. However, their restart equivalents will have identical names because the date string is the yyyy-mm-dd-sssss of the restart. There will be a conflict. Again, it's up to the developer to make this robust.

What this does is as follows, all restarts start with r in type. All histories start with h in type. All initials start with i in type. All restart versions of history files use the history type with an r in front. Some models have multiple restarts, some have multiple histories, etc. It's up to the liason to choose whether to attach an optional char to the r, h or i and what that char would be. Also, all restarts will be $CASE.$scomp.r*.yyyy-mm-dd-sssss. All monthly average files will look like $CASE.$scomp.h*.yyyy-mm. A minor problem is that the "type" will not indicate a monthly average, only the date will.

REPO:

REPO:

2. Filenames for Processed CCSM3 Datasets

In the preceding section, naming conventions were established for output data files generated by the CCSM3 model as it executes ("model output data"); in this section, the conventions are extended in order to define rules for data files that result from the post-processing of CCSM3 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:

• maintain a close and logical connection to the original model output filenames
• allow for the easy identification of the processed files' contents from the filename itself
• separate at a high level the standard CCSM processed data, which are available to the general CCSM community, from the CCSM model output data or the more specialized processed data, such as data intended for the IPCC inter-comparison project
• allow for the creation of unique filenames

Users are free to use their own naming conventions in their own personal directories, but filenames of all data files that are written to /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.

2.1 Filename Requirements for Post-Processed CCSM 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.

• $subdir = [proc,ipcc]

  $subdir differentiates broad classifications of processed data files at a high level. proc is used for the standard suite of CCSM post-processing; ipcc is used for the more specialized processing required for the IPCC intercomparisons (data have been re-gridded and variable names have been changed)

• $tdir = [tavg,tseries]

  $tdir is used to distinguish time-averages from time series; note that the tseries directory can include timeseries of time-averaged quantities; see examples below

• $tperiod = [daily,monthly,seasonal,annual,${N}year]

  $tperiod denotes the time period over which the data were processed. ${N} = 2,3,... Use of $tperiod = seasonal is deferred; see $TPREFIX below

• $SSTRING

  $SSTRING provides a flexible means to describe non-temporal aspects of the file contents; the rules governing $SSTRING are listed below

• $TPREFIX

  $TPREFIX is intended to serve the highly specialized function of identifying specific seasons in the case in which $tperiod = seasonal. This option is deferred, pending further discussion

• $TSTRING

  $TSTRING provides a means to describe temporal aspects of the file contents, either a specific time period or a range of time periods represented in the processed file; the rules governing $TSTRING are listed below

• $ending = [nc]

  $ending is an optional filename suffix used to describe the file format $ending = .nc indicates the file is in netCDF format $ending absent indicates the file is in native binary format

Both $SSTRING and $TSTRING have additional rules that are intended to allow for the creation of a unique filename that helps to unambiguously identify the contents of the file:

$SSTRING Format: substring1[_substring2[_substring3...]]

$SSTRING Rules:

1. The complete absence of $SSTRING has a particular meaning: there have been no spatial operations done on the original model history-file contents, and all of the original history-file variables are contained within the post-processed data file
2. $SSTRING may contain one or more "descriptors," each of which is denoted by substring${N}, ${N}=1,2,... in the format above. A descriptor identifies important aspects of the file contents, such as the names of fields that have been extracted from the original history files, or spatial operations that have been performed. Certain standard descriptor names have been established and are cataloged below
3. If there are multiple descriptors in $SSTRING, each is separated from the other by the underscore character ("_")
4. $SSTRING may contain field information. For netCDF files, use the short_name value(s), such as such as UU, VVEL, or UVEL_VVEL
5. The absence of a field name in $SSTRING indicates that all fields from the original history file are included in the processed file
6. Naming conventions for some spatial operators have been established:
   • zavg -- zonally averaged data
   • gavg -- globally averaged data
   • nh -- northern-hemisphere averaged data
   • sh -- southern-hemisphere averaged data
   All datasets created with any of these spatial operations must use the appropriate operator listed above in $SSTRING.

The format and rules for $TSTRING, which is intended to indicate the time or time periods of the original data files which were processed in order to create this file, are as follows:

$TSTRING Format: datestring1[_operator_datestring2]

$TSTRING Rules:

1. $TSTRING datestrings must follow the conventions for model output files, eg

   yyyy-mm-dd-sssss	-- instantaneous
   yyyy-mm-dd	-- daily average
   yyyy-mm	-- monthly average
   yyyy	-- annual average

2. $TSTRING datestrings may be separated by an operator which describes the temporal operations that were performed on the original data file(s) in order to produce this file
3. The following temporal operators are defined
   • tavg -- time average between consecutive time slices
   • cat -- concatenation of all consecutive time slices contained within a series of history files, which creates a timeseries
4. If present, the $TSTRING temporal operator is separated from datestring1 and datastring2 by the underscore character ("_")

2.1.1 Standard Filename String Names

Several descriptive names have been identified as "standard" CCSM 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 CCSM 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.

• SST (ocn) -- sea surface temperature
• SSS (ocn) -- sea surface salinity
• BSF (ocn) -- barotropic streamfunction
• k${N} (ocn) -- vertical k-index, where ${N} =1,2,... (eg, k1 means "k=1")
• ${N}m (ocn) -- vertical distance in meters from the surface; eg, 50m means "at 50m depth"
• hyphen ("-") -- the hyphen character can be embedded in a single substring to indicate an inclusive range (eg, k1-k3 means "k=1 through k=3,inclusive")

2.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:

• Directory names ($DIRNAME)

  /CCSM/csm/b30.004/atm/proc/tseries/annual /CCSM/csm/b30.004/cpl/proc/tseries/monthly /CCSM/csm/b30.004/ice/proc/tavg/annual /CCSM/csm/b30.004/ocn/proc/tavg/10year /CCSM/csm/b30.004/atm/ipcc/tavg/annual

• One Field

  /CCSM/csm/b30.031/atm/proc/tseries/b30.031.cam2.h0.UU.0400-01_cat_0499-12.nc timeseries of monthly average atmospheric UU velocities, for the period January 400 through December 499, inclusive

• Multiple Fields

  /CCSM/csm/b30.004/ocn/proc/tavg/5year/b30.004.pop.h.UVEL_VVEL_WVEL.0300_tavg_0304.nc 5-year time average of pop U,V,and W velocities, averaged over years 300 through 304, inclusive

• All Fields

  /CCSM/csm/b30.031/atm/proc/tavg/10year/b30.031.cam2.h0.0400_tavg_0409.nc 10-year time average of all atmospheric model h0 history fields, averaged over years 400 through year 409, inclusive (note the absence of $SSTRING)

• Zonal, Global, and Hemispheric Averages

  /CCSM/csm/b30.031/atm/proc/tseries/monthly/b30.031.cam2.UU_zavg.h0.0400-01_cat_0499-12.nc timeseries of the monthly zonally averaged atmospheric model UU velocity field, for the period January 0400 through December 0409, inclusive /CCSM/csm/b30.031/ice/proc/tseries/monthly/b30.031.csim.h.v_nh.0400-01_cat_0499-12.nc timeseries of the monthly northern-hemisphere averaged ice-model v velocity field for the period January 400 through December 499, inclusive

• Yearly Averages

  /CCSM/csm/b30.031/ocn/proc/tavg/annual/b30.031.pop.h.0880.nc annual average of all ocean-model history fields, averaged over year 0880 /CCSM/csm/b30.031/ocn/proc/tavg/50year/b30.004.pop.h.TEMP.0200_tavg_0249.nc 50-year average of the pop temperature field, TEMP, averaged over years 200 through 249, inclusive /CCSM/csm/b30.031/ocn/proc/tseries/annual/b30.004.pop.h.SALT.0200_cat_0249.nc timeseries of the annual averages of the pop salinity field, SALT, from years 200 through 249, inclusive

• Designating Time Periods in Filenames
  • annual average -- although the conventions allow for more than one way to identify an annual average, the use of $TSTRING = YYYY is recommended; eg,
    

    /CCSM/csm/b30.004/ocn/proc/tavg/b30.004.pop.h.0500.nc
    

    is annual average of all pop history fields for year 0500

• Miscellaneous
  • cat and tavg usage -- note the following associations between _cat_ and tseries, and between _tavg_ and tavg

    /CCSM/csm/b30.031/atm/proc/tseries/b30.031.cam2.h0.UU.0400-01_cat_0499-12.nc /CCSM/csm/b30.031/atm/proc/tavg/10year/b30.031.cam2.h0.0400_tavg_0409.nc