3.3 History Files
History File Format
NetCDF was chosen as the history data format because many common visualization
tools already accept this format as input, thus facilitating the acquisition of a visualization
or analysis utility to view Coupler history files. NetCDF (network Common Data Form) 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. The freely available source can be obtained by
anonymous FTP from ftp://ftp.unidata.ucar.edu/pub/netcdf/ or from other mirror sites.
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.
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 includes the case name corresponding to the history data and the date the data was created.
(2) Model domain data
This includes the coordinates of the grid cells of all model domains, as well as a domain
mask for each surface model.
Each model has two sets of strictly increasing latitude and longitude coordinates,
one corresponding to grid cell centers, xc(i) and yc(j),
and one corresponding to grid cell edges, xe(i) and ye(j). Note that the grid cell
"centers" are typically, but not necessarily, at or near the center of a cell.
A state variable S(i,j) is understood to be a point value located at (xc(i),yc(j)),
which is located within a grid cell bounded by
longitude coordinates xe(i) and xe(i+1) and latitude coordinates ye(j) and ye(j+1).
A flux field F(i,j) can be thought of as a point value located at (xc(i),yc(j)), but more
accurately it is an area average value that applies uniformly over the grid cell containing
that point.
Four sets of coordinate arrays are found in the history data:
- xc_a(i), yc_a(j), xe_a(i), and ye_a(j) are the center and edge coordinates for the atmosphere model grid.
- xc_i(i), yc_i(j), xe_i(i), and ye_i(j) are the center and edge coordinates for the sea-ice model grid.
- xc_l(i), yc_l(j), xe_l(i), and ye_l(j) are the center and edge coordinates for the land model grid.
- xc_o(i), yc_o(j), xe_o(i), and ye_o(j) are the center and edge coordinates for the ocean model grid.
Each surface model (land, sea-ice, 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_l(i,j) is the land model domain mask.
- mask_i(i,j) is the ice model domain mask.
- mask_o(i,j) is the ocean model domain mask.
There is no atmosphere domain mask because 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
§ 7 of this document. Some examples of state variable names are:
- Sa_a_t is an atmosphere state variable on the atmosphere grid, and the variable is
temperature.
- Sa_a_u is an atmosphere state variable on the atmosphere grid, and the variable is
zonal velocity.
- Sa_o_u is an atmosphere state variable on the ocean grid, and the variable is zonal
velocity.
- So_o_t is an ocean state variable 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 on the
atmosphere grid, and the field is precipitation.
- Faoa_o_prec is an atmosphere/ocean flux field computed by the atmosphere on the
ocean grid, and the field is precipitation.
- Faoc_o_taux is an atmosphere/ocean flux field computed by the Coupler on the
ocean grid, and the field is zonal wind stress.
- Faoc_a_taux is an atmosphere/ocean flux field computed by the Coupler 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 § 2 for a more complete description of such variables.
Fri 07 Aug 1998, 12:00:00