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_freq 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 CCSM2.0 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 CCSM2.0 User's Guide for details.
Restart files are in a machine dependent binary format, written using simple, 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 been created if the simulation had not been stopped and restarted. "Continuation" or "branch" runs can do exact restarts, and thus require a restart file. For "startup" or "hybrid" runs, the Coupler does not need or use a restart file, hence these types of runs cannot do exact restarts. See the CCSM2.0 User's Guide for more information about these runtypes. 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.
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. See http://www.unidata.ucar.edu/packages/netcdf.
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.
See http://www.cgd.ucar.edu/cms/eaton/cf-metadata.
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",
xc and yc, and one corresponding to grid cell "vertices", xv and yv. Each cell
is defined by four vertices which describe a quadrilateral. Grid cell "centers"
lie within this polygon, typically near its center.
Data is indexed by i, j, and k: xc(i,j), yc(i,j) and xv(i,j,k), yc(i,j,k),
because the underlying data structures are 2D arrays indexed by (i,j),
and because all cells have four vertices, indexed by k (k=1,2,3,4).
Note that latitude and longitude are a function of both i and j, which is
general enough to describe, for example, shifted pole grids.
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.
Five sets of coordinate arrays are found in the history data:
* xc_a(i,j), yc_a(i,j), xv_a(i,j,k), and yv_a(i,j,k) are the center and vertex
coordinates for the atmosphere model grid.
* xc_i(i,j), yc_i(i,j), xv_i(i,j,k), and yv_i(i,j,k) are the center and vertex
coordinates for the sea-ice model grid.
* xc_l(i,j), yc_l(i,j), xv_l(i,j,k), and yv_l(i,j,k) are the center and vertex
coordinates for the land model grid.
* xc_r(i,j), yc_r(i,j), xv_r(i,j,k), and yv_r(i,j,k) are the center and vertex
coordinates for the land model's runoff grid.
* xc_o(i,j), yc_o(i,j), xv_o(i,j,k), and yv_o(i,j,k) are the center and vertex
coordinates for the ocean model grid.
Each surface model (land, land runoff, sea-ice, and ocean) also has a
corresponding domain mask. The domain mask is an integer array such that if
mask(i,j) /= 0, then the indices (i,j) correspond to a grid cell that is in the
active model domain, i.e., S(i,j) is a valid model state and F(i,j) is a valid
flux value. Conversely, if mask(i,j) = 0, then S(i,j) and F(i,j) are undefined.
Three masks are found in the history data:
* mask_a(i,j) is the atmosphere model domain mask.
* mask_l(i,j) is the land model domain mask.
* mask_r(i,j) is the land model's runoff domain mask.
* mask_i(i,j) is the ice model domain mask.
* mask_o(i,j) is the ocean model domain mask.
While there is an atmosphere domain mask, it is assumed that it is non-zero
everywhere, ie. all atmosphere data points are assumed to be valid points
within the atmosphere domain.
(3) Two dimensional state and flux data
This includes model state variables, component flux fields, and merged input
flux fields. The naming convention for two dimensional variables follows the
convention introduced in the pseudo-code section of this document. Some
examples of state variable names are:
* Sa_a_t is an atmosphere state variable, is on the atmosphere grid, and the
variable is temperature.
* Sa_a_u is an atmosphere state variable, is on the atmosphere grid, and the
variable is zonal velocity.
* Sa_o_u is an atmosphere state variable, is on the ocean grid, and the
variable is zonal velocity.
* So_o_t is an ocean state variable, is on the ocean grid, and the
variable is temperature.
Some examples of flux field variable names are:
* Faoa_a_prec is an atmosphere/ocean flux field computed by the atmosphere,
is on the atmosphere grid, and the field is precipitation.
* Faoa_o_prec is an atmosphere/ocean flux field computed by the atmosphere,
is on the ocean grid, and the field is precipitation.
* Faoc_o_taux is an atmosphere/ocean flux field computed by the Coupler,
is on the ocean grid, and the field is zonal wind stress.
* Faoc_a_taux is an atmosphere/ocean flux field computed by the Coupler,
is on the atmosphere grid, and the field is zonal wind stress.
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.