Table of Contents
CAM produces a series of NetCDF format history files containing atmospheric gridpoint data generated during the course of a run. It also produces a series of NetCDF format restart files necessary to continue a run once it has terminated successfully and a series of initial conditions files that may be used to initialize new simulations. The contents of these datasets are described below.
History files contain model data values written at specified frequencies during a run. Options are also available to record averaged, instantaneous, maximum, or minimum values on a field-by-field basis. If the user wishes to see a field written at more than one time frequency (e.g. daily, hourly), additional history files must be declared. This functionality is available via setting namelist variables.
History files may be visualized using various commercial or freely available tools. Examples include the the NCAR Graphics package (via NCL), CDAT, FERRET, ncview, MATLAB, and IDL. For a list of software tools for interacting with NetCDF files, view the UNIDATA maintained link Software for Manipulating or Displaying NetCDF Data.
CAM writes a sequence of time samples to each of its specified history files. There can currently be from one to six history file streams, and each stream has its own set of the following attributes:
fields
output frequency
maximun number of time samples in a file
output precision (4-byte or 8-byte floats)
output domain (global or rectangular subdomains)
Each time sample in a history file has an associated timestamp which
conforms to the CF metadata
conventions. The time unit used in CAM's output files is
"days since reference date" where the reference date is the run start date
by default, but can be customized via the ref_ymd
and ref_tod
namelist
variables. The variables relevant to the timestamps are the following
(from the output of the NetCDF ncdump utility):
double time(time) ; time:long_name = "time" ; time:units = "days since 0000-01-01 00:00:00" ; time:calendar = "noleap" ; time:bounds = "time_bnds" ; double time_bnds(time, nbnd) ; time_bnds:long_name = "time interval endpoints" ; int date(time) ; date:long_name = "current date (YYYYMMDD)" ; int datesec(time) ; datesec:long_name = "current seconds of current date" ;
The variable names, time
, time_bnds
, date
, and datesec
are all
local conventions. What makes the history files CF compliant is that the
time coordinate, time
, can be identified by it's units attribute "days
since 0000-01-01 00:00:00". The reference date is in the form YYYY-MM-DD
HH:MM:SS where YYYY, MM, DD, HH, MM, SS are year, month, day, hour, minute,
second respectively, and a missing timezone defaults to UTC. The
calendar
and bounds
attributes are also part of CF. The calendar
value "noleap
" denotes the Gregorian calendar with no leap years. The
bounds
value time_bnds
denotes that the variable with the name
time_bnds
contains the timestamps that bound the time intervals over
which an operation such as computing an averager or a minimum or maximum
value has been applied. Whether or not the interval specified by
time_bnds
is relevent depends on the individual variables, e.g., a single
file can contain both instantaneous and time averaged fields. The type of
the time operation that has been applied is contained in the cell_methods
attribute of each variable, e.g.,
float T(time, lev, lat, lon) ; T:mdims = 1 ; T:units = "K" ; T:long_name = "Temperature" ; T:cell_methods = "time: mean" ;
The cell_methods
attribute for the temperature variable indicates that it
is being output as a time averaged field. If temperature was instantaneous
then the cell_methods
attribute would not be present since instantaneous
is the default.
The variables date
and datesec
are for convenience only; they don't
play any role in terms of CF compliance. The date
variable is an
integer which is encoded to contain the digits YYYYMMDD where YYYY, MM, and
DD are the year, month, and day of month respectively. datesec
is
the integer number of seconds past 0Z in the current day. The variables
date
and datesec
are redundant in the sense that they can be recovered
from the time
variable via a date calculation using the specified
calendar.
The timestamp associated with each time sample in a history file is the model time at the end of the timestep during which the model writes data to the disk. In the case of instantaneous data the meaning is clear. However when the data is representative of a time interval, the timestamp corresponds to the end of the interval.
This is often a point of confusion when looking at history files. Since
the endpoint of one interval is the same as the begining of the next
interval, when looking at a monthly average for January, which has a
timestamp of 0Z on Feb 01, at first glance the timestamp would seem to
correspond to a February average. Hence it's important for post processing
tools to make use of the data in the time_bnds
variable so that the time
interval endpoints can be used to compute an interval midpoint which is the
more appropriate timestamp to associate with the interval.
Example 4.1. Timestamps for a year of monthly averages
Here are the timestamps and corresponding time interval bounds for a one year sequence of monthly averages starting at 0000-01-01 00:00:00.
Month time date datesec time_bnds Jan 31 201 0 0, 31 Feb 59 301 0 31, 59 Mar 90 401 0 59, 90 Apr 120 501 0 90, 120 May 151 601 0 120, 151 Jun 181 701 0 151, 181 Jul 212 801 0 181, 212 Aug 243 901 0 212, 243 Sep 273 1001 0 243, 273 Oct 304 1101 0 273, 304 Nov 334 1201 0 304, 334 Dec 365 10101 0 334, 365
CAM's default history output is a sequence of monthly averaged fields, written with one time sample per file. This restriction is related to the default file naming scheme which uses the string "YYYY-MM" to indicate the year and month of the average contained in the file. However in general it is possible to write multiple time samples in any of the history file streams that don't contain monthly time intervals. However there is one somewhat unexpected "feature" of multiple time sample files that we wish to point out here.
Example 4.2. Timestamps for five daily averages
Here are the timestamps and corresponding time interval bounds for all time samples written to a single file from a 5 day run starting at 0000-01-01 00:00:00.
Sample time date datesec time_bnds 1 0 101 0 0, 0 2 1 102 0 0, 1 3 2 103 0 1, 2 4 3 104 0 2, 3 5 4 105 0 4, 5 6 5 106 0 5, 6
Instead of ending up with a file containing five time samples, i.e., a daily average for each of the first five days of January, we get six time samples. The first one looks a bit strange since the time bounds are indicating an interval of zero duration. But in fact that's correct for the first time sample which is instantaneous data representing the initial conditions which have only been modify by a partial first step up to the point of the radiation calculation. This "extra" time sample from the initialization phase is included in every history file except for the monthly average file. An unfortunate consequence of this extra time sample is that it's not possible to create a sequence of files with the same number of time intervals since the first file in the sequence will always have one fewer time interval than the rest due to the inclusion of the time zero sample.
CAM is set up by default to output a set of fields to a single monthly average history file. There is a much larger set of available fields, known as the "master field list," from which the user can choose fields of interest to add to the history file via namelist settings. Both the set of default fields and the master field list depend on how CAM is configured. Due to the large number of fields we have chosen to make lists of fields for some standard configuration available via linked documents rather than to inline the lists here. Each of the field list documents is comprised of tables containing the lists of fields that are output by default as well as the master field list.
NOTE: The master field list tables may contain some fields that are not actually available for output. The presence of a field in the master field list is a necessary, but not sufficient condition that the corresponding field in the history file will contain valid data. This is because in some instances fields are added to the master field list (this is done in the source code) even though that field may not be computed in the configuration that is built (specified via the arguments to configure). When adding non-default fields to the history file it's important to check that the fields contain reasonable data before doing a long run.
The following links provide tables of default and master field lists for
some standard model configurations which are characterized by the values of
the -dyn
, -phys
,
and -chem
arguments to configure. The source of the
information in these tables is CAM's default log file, so you can always
look there for any configuration not included in the list below.
fv, cam4, waccm_mozart (use_case: waccm_2000_cam4)
fv, cam4, super_fast_llnl (use_case: 2000_cam4_super_fast_llnl)