Time-averaged history files

Because of additional requirements placed upon POP2 time-averaged output files by CESM1 and because of the extended capability of the CESM1 POP2 time-averaged history fields, the two versions are documented separately in the following two subsections.

LANL Time-averaged history files

The namelist tavg_nml controls the frequency and content of time-averaged history files. These files are constructed by accumulating in memory at each time-step the running sums of selected variables or correlation of variables. Consequently, time averaging can be very memory intensive and may not be feasible on your computer. Snapshot history files provide an alternative, but at the price of having to recall many files from archival storage to compute the sums. The tavg_freq determines both the frequency at which the files are written as well as the interval over which the time average is to be performed.

Because the time averages are running averages, tavg restart files are written whenever a model restart file is written so that the averaging can continue upon restart. Note that the fields in the output files are normalized by the accumulated time since the start of the time average. The time interval used for this normalization is output as the file attribute tavg_sum. When the model restarts from a restart file, the sums are de-normalized before continuing the accumulated sum.

The user may also control when the time averaging will begin. For example, if the time averaging should be started after the model has equilibrated, the user can specify when time averaging should start through the tavg_start variables. The choices are similar to the model start options.

IMPORTANT: Before a new run-sequence is begun, careful thought should be given to the contents of the time-average history files. The same considerations apply to snapshot history and movie files. Although it is possible to redefine the contents at any time during the sequence, this is not recommended. Changing the contents can greatly complicate the process of combining short-interval (e.g., monthly) files into longer-interval files, such as seasonal, annual and multi-year composite files.

For time-averaged output, a tavg_contents file is required containing a simple list (one field per line) of accepted short names for all the fields desired for the output file. A sample_tavg_contents file is supplied containing a large list of fields available for tavg output. It is meant for the user to use as a template, modifying it for their own needs by deleting entries or adding new ones. If a user wishes to add a field that is currently not available, the user must modify the code to add that field using other available fields as a template.

CESM1 Time-averaged history files

In CESM1 POP2, the time-averaged history-file ("tavg") module has been modified to provide additional features and options to the user:

• support for the creation of multiple, simultaneous output streams generated during a single model run
• "timeseries files," which are output files containing multiple time levels per file.
• an "offset" date specification, which allows finer control over the tavg_freq and tavg_freq_opt options described below.
• the option for a "one-time header," in which all time-invariant information is written into the first tavg file of each stream, at the beginning of each run segment, and then omitted from all subsequent files in that stream for the remainder of the run segment.
• support for double-precision tavg output files

Presently, CESM1 POP2 supports the creation of a maximum of four concurrent tavg output streams, with a hard limit of nine streams possible if the tavg module is appropriately modified. Options for each of the streams is set individually, using array syntax in the namelist.

In order to support these additional features, the CESM1 POP2 tavg_contents files and the tavg_nml namelist have necessarily become more complex than the basic LANL POP2.

There are two main differences between the CESM1 POP2 tavg_contents file and the LANL counterpart, but they are small:

• The first line in LANL tavg_contents file contains the integer number of fields in the file, whereas in CESM1, this line is unnecessary and has been eliminated.
• Each subsequent line of the LANL tavg_contents file is filled with a single string that identifies a requested variable via a unique variable short name. In CESM1, the format of each line is only slightly different: three characters have been inserted on each line prior to the variable's short-name string.

The first character of each line in the CESM1 POP2 tavg_contents file is either a comment character or an integer in the interval [1,4]. The next two characters must be blank; the remaining characters on the line spell out the short name of a requested variable.

If the leading character is a comment character -- either the pound sign (#) or the exclamation point (!) -- then the entire line is treated as a comment.

If the leading character on the line is an integer, it identifies the number of the output stream in which the requested field will appear. Each requested tavg output field may be assigned to only one stream; assigning the same field to more than one stream will result in the model ignoring it and all subsequent requests. Similarly, duplicate requests of the same field within the same stream will be eliminated. In all cases, a summary of field and stream assignments is printed in the output log file, which allows the user to confirm which fields will be written to which stream.

Output filenames for the each stream are determined from within the CESM1 tavg module, incorporating the stream number into the output filename in all but the first stream. This seemingly inconsistent treatment of tavg output filenames was chosen based on the requirement for backwards-compatibility in filenames. For example, a one-stream case would generate tavg output files of the form $CASE.pop.h.*; an N-stream case would generate tavg output files of the form $CASE.pop.h.*, $CASE.pop.h2.*, ..., $CASE.pop.hN.*

Most of the CESM1 tavg namelist variables are now arrays of length (max_avail_tavg_streams), which allows the user to set controls for each tavg history-file stream on a stream-by-stream basis.

In the table below, any array element that is undefined in the CESM1 pop2 namelist file is set to the default value identified in curly braces.

Note that we append "_2" to a variable name in order to write that variable to two tavg output files; this convention can be extended to more than two streams in a similar fashion.

To customize tavg output in your CESM1 run:

• > create_newcase -case $CASE ... per the CESM1.0 instructions
• > cd $CASE
• > cd $CASE/SourceMods/src.pop2
• > cp $CCSMROOT/models/ocn/pop2/input_templates/$RES_tavg_contents .
• > edit $RES_tavg_contents -- comment out, activate, or change streams according the instructions above.

then continue with the CESM1 $CASE configure, build, and run procedure.