root/trunk/pop/doc/userguide/POPusers_chap4.tex

\chapter{Model diagnostics and output}\label{ch:output}

While it is possible to run a POP ocean simulation
without generating any output at all, most users desire
a means of looking at the results of their simulation.
POP offers several types of model output with choices
governed by several types of model input.  The following
sections describe all of the options currently available.

\section{Output formats}\label{sec:output-formats}

POP now supports both netCDF and binary output formats.
The format for a particular type of file is chosen at
run time through namelist input for each of the output
types.  In both cases, most output is in single precision
(32-bit). The exception is restart files which are written
in full double precision (64-bit) format.  There are
advantages and disadvantages of using each format which
are discussed below.

\subsection{netCDF}\label{sec:output-format-netCDF}

The netCDF output format provides a self-describing
output file which is portable across machines.  It is
also recognized by many graphics and post-processing
utilities.  These are important and very useful features
and are the reasons a netCDF option has been included
in POP.  However, there are two disadvantages to using
this format.

The most serious disadvantage with netCDF format is that
netCDF does not currently permit parallel I/O; all
netCDF operations are funneled through a single processor.
For high resolution simulations, this can present a serious
performance bottleneck as the model attempts to pass
several Gbytes through a single processor.  If netCDF
output is desired and is proving to be too slow, the
user should switch to binary format and convert the
binary files off-line to netCDF.

Currently, the data portion of a netCDF file utilizes
IEEE binary format.  For portability, if a
machine does not use IEEE format for its native binary
format, netCDF will be performing a conversion (hidden
to the user) to this format.  In such a case, loss
of precision during this conversion will occur and
exact restart can not be guaranteed.  To avoid this,
binary format should typically be chosen for all restart
files.

\subsection{binary}\label{sec:output-format-binary}

The binary format option creates files in local machine
binary format.  These files are written as Fortran
direct-access files so there are no record headers or
footers and the file can be read by other applications
as a pure binary stream.  Typically, each record in
the file contains a horizontal slice of a particular
field (so the record length is the size of a horizontal
slice of the global data).  On parallel machines, fast
parallel I/O is achieved by reading/writing each
of these slices from a different processor
with the number of processors reading/writing data
specified in the
\hyperref{I/O namelist.}
         {I/O namelist (see Sec.}{).}
         {sec:op-io}

Unlike netCDF, these binary files contain no information
about themselves (not self-describing) and no information
about the fields in the files.  To remedy this, each
binary file written by POP is accompanied by a `header
file' with the same name as the binary file and an
additional suffix `.hdr'.  This header file is an ASCII
file which contains all the information you would find in
a netCDF file, including file attributes, fields in the file
and attributes of those fields.  As part of the field
attributes, the starting record of the field in the
binary file is included.  Such a header file provides
some of the capability of a self-describing data format
and also provides information for easy conversion to
netCDF (or other self-describing format).

Because binary formats differ across machines, binary
files are not typically portable across machines.
To achieve portability, the user is encouraged to
convert the binary files to a more portable data format
like netCDF.

\section{File-naming convention}\label{sec:names}

All output file names have the form:
{\tt root-filename.runid.time-indicator.output-format}.
Here {\tt root-filename} is a name defined by the user
through namelist input for each file type,
\hyperref{{\tt runid}}
         {{\tt runid} (see Sec. }{)}
         {sec:op-timemanager}
is a character identifier for the run sequence,
{\tt time-indicator} depends on the output frequency
chosen and {\tt output-format} is either `nc' for netCDF
files or `bin' for binary files. If the output file is written
at a frequency of {\tt nday, nmonth} or {\tt nyear}, the
{\tt time-indicator} is typically the date in yyyymmdd
(where yyyy, mm and dd can be optionally separated by a
character defined in the time manager namelist). If the
output file is written every {\tt nstep} steps, the
{\tt time-indicator} is the step number.

A convention has been developed for naming POP output files
in which the root filenames for {\em restart, time-averaged
history, snapshot history,} and {\em movie}files are
simply the one-letter names `d', `t', `h', `m' respectively.
These are the default values in the namelists for each
of these options, but the user is not required to follow
this convention.  Come up with your own convention.  We don't
mind.  Really.  Have fun with it.  The only requirement
is that the {\tt root-filename} must be distinct for each
type of output file.
Because `.' is used to delimit {\tt runid} in file names and
`/' is reserved as a separator in Unix path names, neither
should be used within {\tt runid}.

\section{Model diagnostics}\label{sec:diagnostics}

The progress of a POP simulation is recorded in a `log file'
that is either written to standard output (stdout) or
redirected to an optional
\hyperref{log file}
         {log file (see Sec.}{)}
         {sec:op-io}.
A new log file is created each time the model is started.
Values of the model version number, release date, date and
time of the run, input namelist parameters, and initial or
restart conditions are documented at the beginning of each
log file.  After the introductory information, the log file
will contain output from model timers and all the
scalar diagnostics.

There are three types of scalar diagnostics available.
Global diagnostics compute a variety of globally-averaged
values of tracers, kinetic energy and several tendencies for
checking balances. CFL diagnostics compute the Courant numbers
for advection and diffusion terms.  Transport diagnostics
compute mass, heat and salt transports through various regions
defined in an input file.

These diagnostics are chosen by setting the frequency
{\tt freq\_opt} at which each diagnostic is computed.
If diagnostics are chosen, the diagnostics are written
both to the log file (or stdout) and to a separate
diagnostics output file.  Monitoring this output
as the model runs is a useful way of making sure the
model is behaving reasonably.  For example, the Courant
numbers reported in the CFL diagnostics should remain small
and various tendencies reported in the global diagnostics
should remain balanced.

In addition to printing these diagnostics to a log file, the
diagnostics are printed to other output files in a format
more suitable for various graphics programs.  The output
files are ASCII files with each line containing {\tt tday}
(decimal time in days for the entire simulation), the value
of the diagnostic and a name for the diagnostic.  The name
of these output files can be changed using the variables
{\tt diag\_outfile, diag\_transport\_outfile}.

\begin{table}\caption{Diagnostics namelist}\label{tab:nmldiag}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf \&diagnostics\_nml} &
  {\bf  }                  &
  {\bf generation of model diagnostics} \\
\hline
  diag\_global\_freq\_opt                                           &
  [`never'], `nstep', `nyear', `nmonth', `nday', `nhour', `nsecond' &
  units of time for 'diag\_global\_freq' \\
\hline
  diag\_global\_freq &
  [100000]           &
  how often (in above units) to compute and print global diagnostics \\
\hline
  diag\_cfl\_freq\_opt                                              &
  [`never'], `nstep', `nyear', `nmonth', `nday', `nhour', `nsecond' &
  units of time for 'diag\_cfl\_freq' \\
\hline
  diag\_cfl\_freq &
  [100000]        &
  how often (in above units) to compute and print CFL stability
  diagnostics \\
\hline
  diag\_transp\_freq\_opt                                           &
  [`never'], `nstep', `nyear', `nmonth', `nday', `nhour', `nsecond' &
  units of time for 'diag\_transp\_freq' \\
\hline
  diag\_transp\_freq &
  [100000]           &
  how often (in above units) to compute and print transport
  diagnostics \\
\hline
  diag\_transport\_file     &
  `sample\_transport\_file' &
  input filename (with path) describing requested transports \\
\hline
  diag\_outfile &
  `pop\_diag'   &
  file to which global and cfl diagnostics are to be written \\
\hline
  diag\_transport\_outfile &
  `pop\_transp'            &
  file to which transport diagnostics are to be written \\
\hline
  diag\_all\_levels &
  [.false.]         &
  if true, tracer mean diagnostics at all vertical levels are output \\
\hline
  cfl\_all\_levels &
  [.false.]        &
  if true, cfl diagnostics at all vertical levels are output \\
\hline
  / &
    &
    \\
\hline
\end{tabular}
\end{table}

\subsection{Transport diagnostics}\label{sec:diag-transport}

Computing transport diagnostics requires an input file describing
the requested transports.  A sample transport input file is
provided with the distribution.  The transport input file
must contain the number of transport regions in the first record.
Each following record must contain 6 integers
{\tt imin, imax, jmin, jmax, kmin, kmax} which are global
array indices which define the transport region. Note that
the region must be a plane so that one of the horizontal
dimensions must be fixed. Following these integers must be
a 5-character string that specifies `zonal' or `merid'
transport.  Note that this descriptor defines the orientation
of the {\em section} and not the direction of the velocity
normal to it.  A `zonal' section implies the transport across
that section uses the meridional velocity (velocity
perpendicular to the section).  The last item in each record
is a name for the transport region (e.g. `Drake Passage').

\begin{table}\caption{Transport descriptions}\label{tab:diag-transp}
\begin{tabular}{|l|l|l|l|l|l|l|l|}
\hline
  {\bf imin}    &
  {\bf imax}    &
  {\bf jmin}    &
  {\bf jmax}    &
  {\bf kmin}    &
  {\bf kmax}    &
  {\bf section} &
  {\bf label}   \\
\hline
   64   &
   64   &
    1   &
  128   &
    1   &
   20   &
  merid &
  sample meridional section \\
\hline
    1   &
  192   &
   64   &
   64   &
    1   &
   10   &
  zonal &
  sample zonal section \\
\hline
\end{tabular}
\end{table}

\section{Model output files}\label{sec:output}

In this section, we often refer to `model dates' and `model
times' as corresponding to actual dates and times in the
real world.  This is only true if the model initial time
was set appropriately and only has true meaning if the model
is forced by actual observed forcing fields with proper dates
associated with them. Otherwise, `model time' simply refers
to the model's internal calendar.

\subsection{Time-averaged history files }\label{sec:output-tavg}

The namelist {\tt tavg\_nml} controls the frequency and
content of time-averaged history files. These files are
constructed by accumulating in memory at each time-step
the running sums of selected variables or correlation of
variables.  Consequently, time averaging can be very memory
intensive and may not be feasible on your computer. Snapshot
\hyperref{history files}
         {history files (see Sec.}{)}
         {sec:output-history}
provide an alternative, but at the price of having to recall
many files from archival storage to compute the sums. The
{\tt tavg\_freq} determines both the frequency at which the
files are written as well as the interval over which the
time average is to be performed.

Because the time averages are running averages, {\tt tavg}
restart files are written whenever a model restart file is
written so that the averaging can continue upon restart. 
Note that the fields in the output files are normalized by
the accumulated time since the start of the time average.
The time interval used for this normalization is output
as the file attribute {\tt tavg\_sum}.  When the model
restarts from a restart file, the sums are de-normalized
before continuing the accumulated sum.

The user may also control when the time averaging will
begin.  For example, if the time averaging should be
started after the model has equilibrated, the user can
specify when time averaging should start through the
{\tt tavg\_start} variables.  The choices are similar
to the model start options.

\begin{table}\caption{Time-average file namelist}\label{tab:nmltavg}
\begin{tabular}{|p{1in}|p{1.25in}|p{2in}|}
\hline
  {\bf \&tavg\_nml} &
  {\bf  }           &
  {\bf generation of time-average history files} \\
\hline
  tavg\_freq\_opt                                                   &
  [`never'], `nyear', `nmonth', `nday', `nhour', `nsecond', `nstep' &
  units of time for `tavg\_freq' \\
\hline
  tavg\_freq &
  [100000]   &
  interval in above units for computation and output of time-average
  history files \\
\hline
  tavg\_start\_opt                                &
  [`nstep'], `nyear', `nmonth', `nday', `date'    &
  units for tavg\_start (`date' implies yyyymmdd) \\
\hline
  tavg\_start &
  [100000]    &
  time in above units after which to start accumulating time average \\
\hline
  tavg\_infile &
  [`unknown']  &
  restart file for partial tavg sums if starting from restart
      (ignored if luse\_pointer\_files is enabled) \\
\hline
  tavg\_fmt\_in &
  [`bin'],`nc'  &
  format for tavg restart file (binary or netCDF) \\
\hline
  tavg\_outfile &
  [`unknown']   &
  root filename (with path) for tavg output files (suffixes
  will be added) \\
\hline
  tavg\_fmt\_out &
  [`bin'],`nc'   &
  format for tavg output files (binary or netCDF) \\
\hline
  tavg\_contents           &
  `sample\_tavg\_contents' &
  file name for input file containing names of fields requested for
  tavg output \\
\hline
  / &
    &
    \\
\hline
\end{tabular}
\end{table}


{\bf IMPORTANT}: Before a new run-sequence is begun, careful
thought should be given to the contents of the time-average
history files. The same considerations apply to snapshot
history and movie files.  Although it is possible to redefine
the contents at any time during the sequence, this is not
recommended. Changing the contents can greatly complicate
the process of combining short-interval (e.g., monthly) files
into longer-interval files, such as seasonal, annual and
multi-year composite files.

For time-averaged output, a {\tt tavg\_contents} file
is required containing a simple list (one field per line)
of accepted short names for all the fields desired for the
output file.  A {\tt sample\_tavg\_contents} file is supplied
containing a large list of fields available for tavg output.
It is meant for the user to use as a template, modifying it
for their own needs by deleting entries or adding new ones.
If a user wishes to add a field that is currently not available,
the user must modify the code to add that field using other
available fields as a template.

\begin{table}[!h]\caption{Current available tavg fields}
\label{tab:tavgfields}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf Name}        &
  {\bf Units}       &
  {\bf Description} \\
\hline
  SHF               &
  $W/m^2$           &
  Surface Heat Flux \\
\hline
  SFWF                          &
  mm/day                        &
  Surface Freshwater Flux (p-e) \\
\hline
  SSH                &
  cm                 &
  Sea Surface Height \\
\hline
  H2            &
  $cm^2$        &
  ${\rm SSH}^2$ \\
\hline
  H3                                      &
  unitless                                &
  $(\Delta_x(SSH))^2 + (\Delta_y(SSH))^2$ \\
\hline
  TAUX             &
  $dyne/cm^2$      &
  Zonal windstress \\
\hline
  TAUY                  &
  $dyne/cm^2$           &
  Meridional windstress \\
\hline
  UVEL           &
  cm/s           &
  Zonal Velocity \\
\hline
  VVEL                &
  cm/s                &
  Meridional Velocity \\
\hline
  KE                                      &
  $cm^2/s^2$                              &
  Horizontal Kinetic Energy $(U^2+V^2)/2$ \\
\hline
  TEMP                  &
  ${\ }^\circ C $       &
  Potential Temperature \\
\hline
  SALT     &
  g/g      &
  Salinity \\
\hline
  TEMP2                 &
  ${\ }^\circ C^2$      &
  ${\rm Temperature}^2$ \\
\hline
  SALT2              &
  $(g/g)^2$          &
  ${\rm Salinity}^2$ \\
\hline
  UET               &
  ${\ }^\circ C/s$  &
  East Flux of Heat \\
\hline
  VNT                &
  ${\ }^\circ C/s$   &
  North Flux of Heat \\
\hline
  WTT              &
  ${\ }^\circ C/s$ &
  Top Flux of Heat \\
\hline
  UES               &
  g/g/s             &
  East Flux of Salt \\
\hline
  VNS                &
  g/g/s              &
  North Flux of Salt \\
\hline
  WTS              &
  g/g/s            &
  Top Flux of Salt \\
\hline
  UEU                         &
  $cm/s^2$                    &
  East Flux of Zonal Momentum \\
\hline
  VNU                          &
  $cm/s^2$                     &
  North Flux of Zonal Momentum \\
\hline
  UEV                               &
  $cm/s^2$                          &
  East Flux of Meridional Momentum  \\
\hline
  VNV                               &
  $cm/s^2$                          &
  North Flux of Meridional Momentum \\
\hline
  PV                  &
  1/s                 &
  Potential Vorticity \\
\hline
  Q                                 &
  $g/cm^4$                          &
  z-derivative of potential density \\
\hline
  PD                                      &
  $g/cm^3$                                &
  Potential density referenced to surface \\
\hline
  UDP           &
  erg           &
  Pressure work \\
\hline
  PEC                                        &
  $g/cm^3$                                   &
  Potential energy release due to convection \\
\hline
  NCNV                              &
  adjustments/s                     &
  Convective adjustments per second \\
\hline
  WTU                        &
  $cm/s^2$                   &
  Top flux of Zonal Momentum \\
\hline
  WTV                             &
  $cm/s^2$                        &
  Top flux of Meridional Momentum \\
\hline
  ST                   &
  ${\ }^\circ Cg/g$    &
  Temperature*Salinity \\
\hline
  RHO              &
  $g/cm^3$         &
  In-situ density  \\
\hline
\end{tabular}
\end{table}

\newpage
\subsection{Snapshot history files }\label{sec:output-history}

If sufficient memory is not available for run-time
accumulation of time-averaged history files or if the user
simply needs an instantaneous view of the ocean state, snapshot
history files can be written at regular intervals.
The interval must be short enough that whatever time-averaging
interval may be desired in the future, there will be three or
more samples (snapshots) per averaging-interval. For monthly
averages, snapshots should be collected at intervals of 10 days
or less.  Only one time-level of the prognostic
variables and selected diagnostic variables needs to be saved, since
second-moments and correlations can be computed later from these snapshot
files, at the cost of retrieving a potentially large number of snapshot
files.  To choose which fields are written to the history files,
a history contents file must be supplied with a list of fields
desired.  A sample file is included which contains all the
currently available fields; the user may edit this file to
select the desired fields.  If a field is not currently included
in the list of available fields, the user must modify the source
code to make that field available (see the Reference Manual).

\begin{table}[h]\caption{History file namelist}\label{tab:nmlhist}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf \&history\_nml} &
  {\bf  }              &
  {\bf Generation of snapshot history files} \\
\hline
  history\_freq\_opt                                               &
  [`never'],`nstep', `nyear', `nmonth', `nday', `nhour', `nsecond' &
  units of time for history\_freq \\
\hline
  history\_freq &
  [100000]      &
  number of units between output of snapshot history files \\
\hline
  history\_outfile &
  [`unknown']      &
  root filename with path of history file output
  (suffixes will be added) \\
\hline
  history\_fmt   &
  [`bin'],`nc'   &
  format for history files (binary or netCDF) \\
\hline
  history\_contents             &
  [`history\_contents'] &
  input file containing names of fields requested to be output \\
\hline
  / &
    &
    \\
\hline
\end{tabular}
\end{table}


\begin{table}[!h]\caption{Currently available history fields}
\label{tab:histfields}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf Name}        &
  {\bf Units}       &
  {\bf Description} \\
\hline
  SHGT           &
  cm             &
  surface height \\
\hline
  UBTROP                      &
  cm/s                        &
  barotropic `zonal' velocity \\
\hline
  VBTROP                           &
  cm/s                             &
  barotropic `meridional' velocity \\
\hline
  UVEL             &
  cm/s             &
  `zonal' velocity \\
\hline
  VVEL                  &
  cm/s                  &
  `meridional' velocity \\
\hline
  TEMP                  &
  ${\ }^\circ C$        &
  potential temperature \\
\hline
  SALT      &
  g/g (msu) &
  salinity  \\
\hline
  SUF        &
  $cm^2/s^2$ &
  surface velocity flux in U direction  \\
\hline
  SVF        &
  $cm^2/s^2$ &
  surface velocity flux in V direction  \\
\hline
  SHF       &
  $W/m^2$   &
  surface heat flux  \\
\hline
  SFWF      &
  m/year    &
  surface fresh water flux  \\
\hline
  SOLAR     &
  $W/m^2$   &
  solar short wave flux at surface  \\
\hline
\end{tabular}
\end{table}

\newpage
\subsection{Movie files }\label{sec:output-movie}

One of the most exciting aspects of ocean simulation is the
opportunity to visualize and animate the evolution of the
model variables in time and space. Making movies that
progress smoothly requires either output of model variables
frequently enough to avoid jerkiness or temporal interpolation
of model variables to similarly frequent intervals.  Experience
has shown that a snapshot every three days (see {\tt movie\_freq})
gives satisfactory results. Any variable can be output, but to
reduce archiving cost and retrieval time, movie
files typically contain only a few two-dimensional arrays, such
as sea-surface temperature, salinity and height, and a few
sub-surface variables.  The choice of fields is made through
an input movie contents file containing the names (one per
line) of the fields requested.  A sample file is included
with a list of available fields; the user may modify this
list to choose the desired fields.  If a field does not appear
in the list of available fields, the user may add fields by
modifying the source code as described in the Reference
Manual.

\begin{table}[h]\caption{Movie file namelist}\label{tab:nmlmovie}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf \&movie\_nml} &
  {\bf  }            &
  {\bf generation of snapshot movie files} \\
\hline
  movie\_freq\_opt                                               &
  [`never'], `nstep', `nyear',`nmonth',`nday', `nhour',`nsecond' &
  units of time for movie\_freq \\
\hline
  movie\_freq &
  [100000]    &
  number of units between output of movie files \\
\hline
  movie\_outfile &
  ['unknown']    &
  root filename with path of movie file output
  (suffixes will be added) \\
\hline
  movie\_fmt   &
  [`bin'],`nc' &
  format for movie file output (binary or netCDF) \\
\hline
  movie\_contents             &
  [`sample\_movie\_contents'] &
  input file containing names of fields requested
  for movie output \\
\hline
  / &
    &
    \\
\hline
\end{tabular}
\end{table}

\begin{table}[h]\caption{Currently available movie fields}
\label{tab:moviefields}
\begin{tabular}{|p{1in}|p{1in}|p{2.25in}|}
\hline
  {\bf Name}        &
  {\bf Units}       &
  {\bf Description} \\
\hline
  SHGT           &
  cm             &
  surface height \\
\hline
  UTRANS                                  &
  $cm^2/s$                                &
  vertically integrated `zonal' transport \\
\hline
  VTRANS                                       &
  $cm^2/s$                                     &
  vertically integrated `meridional' transport \\
\hline
  TEMP1\_2                                       &
  ${\rm }^\circ C$                               &
  potential temperature averaged over levels 1,2 \\
\hline
  SALT1\_2                          &
  g/g (msu)                         &
  salinity averaged over levels 1,2 \\
\hline
  TEMP6                            &
  ${\rm }^\circ C$                 &
  potential temperature at level 6 \\
\hline
  SALT6               &
  g/g (msu)           &
  salinity at level 6 \\
\hline
  VORT                          &
  1/s                           &
  relative vorticity at surface \\
\hline
\end{tabular}
\end{table}

\newpage
\subsection{Current meters, drifters and hydrographic sections.}
\label{sec:output-cmeters}

Versions of these exist for some machines but these are not
yet included in the present version of the code. They will be
added soon.