CCSM2.0.1 POP Input Data File Naming and Documentation Conventions

August 2002

The following guidelines are intended to apply to the naming of CCSM ocean-model input datasets and the creation of documentation which sufficiently describes them. Many of the guidelines are general enough to be easily extended to other CCSM component models.

There are presently two locations where CCSM ocean-model input datasets reside at NCAR: the NCAR mass-storage system (mss) and local disk (fileserver). The files on the mss are considered archival copies, and are expected never to be removed. The files on the fileserver disk are convenient copies of the archival datasets, and although their lifetime on the disk is expected to be long, there is no guarantee that obsolete fileserver copies will exist on the disk always.

• directory names:
  • main pathnames:
    • mss: /CCSM/inputdata/ocn/pop
    • local: /fs/cgd/csm/inputdata/ocn/pop

  • two subdirectories:
    • $GRID (gx3v4, gx1v3, etc) -- resolution-dependent datasets
      • four $GRID subdirectories:
        • "grid" -- grid-related input datasets
        • "ic" -- initial-condition datasets
        • "forcing" -- forcing datasets
        • "source" -- resolution-dependent source code

    • source -- resolution-independent source used in the creation of input datasets. Collections of files are tar'd. If source code is simple, it may be included in the associated "readme" file instead (see below). Source code in this directory is available on the mss; it is generally not available on the fileserver disk.

• root filenames:
  • root filenames consist of the letters [a-z], [A-Z], the digits [0-9], and the characters "_" (underscore), "-" (hyphen), and "." (dot)
    • lower-case letters are recommended, except for acronyms or for matching existing casenames which contain upper-case letters
  • root filenames for new files must be consistent with existing filenames whenever possible
  • every root filename must end with an embedded creation date in the format _yyyymmdd
    • if necessary, the creation date may include a suffix "a", "b", etc, to distinguish betweeen files of the same name created on the same day
  • any root filename that also contains a model date must specify it in the format _mdyyyymmdd , to distinguish it from the mandatory creation date.

• filename suffixes:
  • the file suffix is separated from the root filename by the character "."
  • all filenames will contain one suffix that describes the dataset format. To date, the following suffixes have been defined:
    • "ieeer8" ==> ieee real*8, big endian
    • "ieeei4" ==> ieee integer*4,big endian
    • "ieeemx" ==> ieee mixed types (document in "readme") (big endian)
    • "nc" ==> netCDF
    • "ascii" ==> ascii text
    • "readme" ==> information about file contents

• input dataset documentation:
  • all new data files must have a companion information file with the identical path and root filename, plus the suffix "readme" (see above).
  • in the case where there are two or more files with the same rootname, but different suffixes, a single "readme" file will describe each. in this case, the only allowable difference between the data files is the data format (including precision)
  • the template "inputdata/ocn/pop/source/template.readme" has been created to prompt the dataset creator for the following mandatory and optional information:

    • mandatory "readme" file information:
      • a concise summary of the data contents (eg, "3x smoothed gx1v3 topography"). this should be the first line of the file
      • name of the person who created the file
      • date and time of file creation
      • machine used to create the file
      • "endian-ness" of the file
      • filename of the archived copy of this file
      • description of methodology used to create the data file

    • optional "readme" file information -- supply if available:
      • description of other datasets used to create the data file (with references to archived copies of all datasets)
      • a copy of any code or scripts used to create the file, or a reference to an archived version of these codes or scripts

  • for each datafile, the ocn.setup.csh script must copy the companion "readme" file into the execution directory "input", to provide full documentation for each dataset used in model execution

• file permissions:
  • all files in /CCSM/inputdata/ocn/pop will have the write password, "rusure"
  • all files in /fs/cgd/csm/inputdata/ocn/pop will have write permission disabled
  • all subdirectories in /fs/cgd/csm/inputdata/ocn/pop will have write permission enabled for the owner and the group (cgdcsmoc)

Proposed Filenames for Existing CCSM POP Files

inputdata/ocn/pop/gx1v3

inputdata/ocn/pop/gx3v4