The coupler outputs three types of data: standard out (stdout) diagnostic data, restart files, and diagnostic history files.
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.
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.
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.
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.
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 is understood to be a point value located at the center of cell . A flux field 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:
Xa2c_a_Sa_u bundle: Xa2c_a ~ atm-to-cpl bundle on atm domain field: Sa_u ~ atm meridional velocity Xc2o_o_Foxx_taux bundle: Xc2o_o ~ cpl-to-ocn bundle on ocn domain field : Foxx_taux ~ merged zonal ocn surface stress domain_o_lat bundle: domain_o ~ time invariant ocn domain information field : lat ~ grid cell latitude frac_o_ifrac bundle: frac_o ~ surface fractions on ocn domain field: ifrac ~ ice fractionEach 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.