next up previous contents
Next: 2 Source Code Reference Up: 1 User's Guide Previous: 4 Input Namelist Parameters   Contents


5 Output Data

The coupler outputs three types of data: standard out (stdout) diagnostic data, restart files, and diagnostic history files.

5.1 Stdout Data

Stdout output consists mostly of brief messages that indicate how the simulation is progressing and whether any error conditions have been detected. Stdout also contains a record of the values of all Coupler input parameters. If global diagnostics have been activated (see the diag_option namelist parameter), stdout will also contain some diagnostic information, specifically global averages and time averages of various flux fields flowing through the Coupler.

Exactly where the Coupler's stdout (and stderr, standard error) shows up is determined outside of the Coupler source code and executable. Certain environment variables found in the CCSM run scripts are used to determine where the Coupler will execute (its current working directory, or cwd) and also to redirect stdin and stdout - these env variables determine where stdout text will end up. Normally the run script arranges for stdout text to show up in a ``log'' file in the Coupler's execution directory (current working directory) while the simulation is in progress, and then later, after the simulation ends, the run script moves this log file to an archival location. See the CCSM User's Guide for details.

5.2 Restart Files

Restart files are in a machine dependent binary format, written using standard Fortran write statements. Restart files provide the Coupler with all the IC data necessary to do an ``exact restart'' of a previous simulation. ``Exact restart'' means stopping and restarting a simulation while preserving, bit-for-bit, the results that would have be created if the simulation had not been stopped and restarted.

``Continuation'' or ``branch'' runs both require a restart file and are capable of exact restart. For ``initial'' runs, the Coupler does not use a restart file. Initial runs cannot do exact restarts. The CCSM User's Guide describes the related concepts of ``startup'', ``branch'', ``hybrid'', and ``continuations'' runs. At the system-wide level there are four types of runs, but for the Coupler alone, there are only three modes of operation. Both ``startup'' and ``hybrid'' at the system level invoke an ``initial'' run in the Coupler component. See the CCSM User's Guide for more information.

Normally there is no need to examine the contents of a restart file. All fields found in the restart file can be saved into history files, which are machine independent NetCDF files.

5.3 History Files

5.3.1 Instantaneous and Time Averaged File

The Coupler can create either instantaneous history file, time averaged history files, or both. Their creation is controlled by two independent sets of namelist variables. When doing an ncdump the contents of both files appear to be the same, but the values in the time coordinate variables (time and time_bound) clearly define the time averaging interval, if any, as required by the NetCDF Climate and Forecast Metadata Conventions, version 1.0 (CF 1.0). The Coupler's NetCDF files conform to the CF 1.0 format.

5.3.2 History File Format

NetCDF (network Common Data Form) was chosen as the history data format because many common visualization tools already exist that handle this data format. NetCDF is an interface for array-oriented data access and a library that provides an implementation of the interface. The NetCDF library also defines a machine independent format for representing scientific data. Together the interface, library, and format support the creation, access, and sharing of scientific data. The NetCDF software was developed at the Unidata Program Center in Boulder, Colorado.

5.3.3 History File Content

Because NetCDF files are self-describing, the most complete and accurate description of the contents of a Coupler history file (or any NetCDF file) will always come from the NetCDF data file itself. The NetCDF tool "ncdump" will generate the CDL text representation of a NetCDF file on standard output, optionally excluding some or all of the variable data in the output.

The Coupler's NetCDF files conform to the CF 1.0 format. The CF conventions generalize and extend the COARDS conventions.

Three types of data are found in Coupler NetCDF history data files: global attributes, domain data, and two dimensional state and flux data.

(1) Global attributes

This is text information, including the case name corresponding to the history data, and the date the data was created.

(2) Model domain data

This includes the spatial coordinates of the grid cells as well as the cell areas and a domain mask for each surface model. Each model has two sets of latitude and longitude coordinates, one corresponding to grid cell "centers" and one corresponding to grid cell "vertices". Each cell is defined by four vertices which describe a quadrilateral. Grid cell "centers" lie within this polygon, typically near its center.

A state variable $S(i,j)$ is understood to be a point value located at the center of cell $(i,j)$. A flux field $F(i,j)$ can be thought of as a point value located at the cell center, but more accurately it is an area average value that applies uniformly over the entire grid cell.

Currently only the grid cell centers are put onto history data files.

The Coupler deals with five model domains: atmosphere, ice, land, land runoff, and ocean. For each of these model domains, the following domain information is on the history files:

(3) Two dimensional state and flux data

This includes model state variables, component flux fields, and merged input flux fields.

A variable naming convention has been adopted to help organize and identify the literally hundreds of state and flux fields managed by the Coupler.

The cpl6 Coupler manages fields by grouping them into bundles of fields. A bundle is a group of fields that share the same domain. A domain includes grid cell coordinates, mask, areas, and decomposition. More information on these Coupler datatypes can be found in Section 8. The variables found in NetCDF history files are based on the same naming convention as the variables found in the source code. The variable names found in the history file are formed by appending a field name onto a bundle name: <bundle>_<field>

Bundles have names like Xa2c_a where the _a indicates the bundle's domain is the atm domain and Xa2c is a meaningful shorthand description, in this case Xa2c means ``everything sent from the atm to the cpl.'' The X means ``everything'', the a is for ``atm'', the c is for ``cpl.''

Fields have names like Sa_t or Faoc_lat which are also a meaningful shorthand description, in this case Sa_t means ``atm state, temperature'' and Faoc_lat means ``atm/ocn flux, computed by cpl, latent heat''. Additional information on the naming convention for variables in the Coupler is in Section 9.1.

Here are more examples from the Coupler history file:

   bundle: Xa2c_a    ~ atm-to-cpl bundle on atm domain
   field:  Sa_u      ~ atm meridional velocity
   bundle: Xc2o_o    ~ cpl-to-ocn bundle on ocn domain
   field : Foxx_taux ~ merged zonal ocn surface stress
   bundle: domain_o  ~ time invariant ocn domain information
   field : lat       ~ grid cell latitude
   bundle: frac_o    ~ surface fractions on ocn domain
   field:  ifrac     ~ ice fraction
Each variable in the NetCDF history file has long_name and units attributes which further describe the variable. Also see the Data Exchanged section of this document.

next up previous contents
Next: 2 Source Code Reference Up: 1 User's Guide Previous: 4 Input Namelist Parameters   Contents