.. _model-diagnostics-and-output:

Model diagnostics and 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.

Output formats
===============

POP 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. Restart files are always written in full
double-precision (64-bit) format. By default, other output is written in
single precision (32-bit) format.

The advantages and disadvantages of using netCDF and binary output
formats are discussed in the following sections.

POP2 supports a compile-time option to create double-precison
time-averaged ("tavg") history files, which are often useful for
debugging purposes and in the evaluation of successful ports to new
machines.

To invoke the double-precision tavg option, compile POP2 must be compiled with the -DTAVG\_R8 option.


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.

POP2 supports parallel netCDF I/O through the use of its PIO library.


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 :ref:`Input/Output section<input-output>`.

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.

File-naming conventions
========================

All output file names have the form:
``root-filename.runid.time-indicator.output-format``. Here
``root-filename`` is a name defined by the user through namelist input
for each file type, ```runid`` <node33.html#sec:op-timemanager>`__ is a
character identifier for the run sequence, ``time-indicator`` depends on
the output frequency chosen and ``output-format`` is either 'nc' for
netCDF files or 'bin' for binary files.If the output file is written at
a frequency of ``nday, nmonth`` or ``nyear``, the ``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 ``nstep`` steps, the ``time-indicator`` is
the step number.

A convention has been developed for naming POP output files in which the
root filenames for *restart, time-averaged history, snapshot history,*
and *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 ``root-filename`` must be distinct
for each type of output file. Because '.' is used to delimit ``runid``
in file names and '/' is reserved as a separator in Unix path names,
neither should be used within ``runid``.

The CIME scripts automatically generate POP2 output filenames that
conform with the naming conventions, which, when written in the
syntax of the LANL conventions, can be described as:
``$CASE.pop.root-filename.time-indicator.output-format``

``$CASE`` is the CIME "case name" assigned to a given CIME run.

``root-filename`` values are chosen to be the same as
LANL values whenever possible; unfortunately, the convention is in
direct conflict with two of the LANL settings. 
``root-filename`` is 'h' (*history*) for time-averaged history files
created by the tavg.F90 module, and 's' (*snapshot*) for history files
created by the history.F90 module. For diagnostics output files,
``root-filename`` is a two-character string beginning with the first
character 'd', with the second character intended to indicate the type
of diagnostics output file.

The full POP2 convention for ``root-filename`` is:

-  ***'dd'***   diag\_outfile
-  ***'dt'***   diag\_transport\_outfile
-  ***'dv'***   diag\_velocity\_outfile
-  ***'h'***     tavg\_outfile
-  ***'m'***   movie\_outfile
-  ***'r'***     restart\_outfile
-  ***'s'***     history\_outfile

The ``time-indicator`` takes various forms, depending on the
contents of the output file.

The full convention for ``time-indicator`` is as follows, and is
automatically generated by the POP2 code, depending on the
frequency of the file:

-  ***'yyyy-mm-dd-sssss'***   'nhour', 'nsecond', or 'nstep' frequency
-  ***'yyyy-mm-dd'***             daily frequency
-  ***'yyyy-mm'***                   monthly frequency
-  ***'yyyy'***                           annual frequency


Model 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
`log file <node32.html#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 ``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 ``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
``diag_outfile, diag_transport_outfile``.

Model diagnotics are controlled by the 
`diagnostics_nml <http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/modelnl/nl_pop2.html#diag>`_ namelist.

Tracer budget diagnostics are controlled by the 
`budget_diagnostics_nml <http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/modelnl/nl_pop2.html#budget_diag>`_ namelist.


Transport diagnostics
----------------------

Computing transport diagnostics requires an input file describing the
requested transports. A sample transport input file is provided with the
LANL distribution. The transport input file must contain the number of
transport regions in the first record. Each following record must
contain 6 integers ``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 *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').

Table: **Table:** Transport descriptions

+------------+------------+------------+------------+------------+------------+---------------+-----------------------------+
| **imin**   | **imax**   | **jmin**   | **jmax**   | **kmin**   | **kmax**   | **section**   | **label**                   |
+------------+------------+------------+------------+------------+------------+---------------+-----------------------------+
| 64         | 64         | 1          | 128        | 1          | 20         | merid         | sample meridional section   |
+------------+------------+------------+------------+------------+------------+---------------+-----------------------------+
| 1          | 192        | 64         | 64         | 1          | 10         | zonal         | sample zonal section        |
+------------+------------+------------+------------+------------+------------+---------------+-----------------------------+


POP2 is capable of computing transport diagnostics, such as
meridional overturning circulation, northward termperature and salt
transports, and zonal averages on an auxilary latitudinal grid. 

The `transports_nml <http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/modelnl/nl_pop2.html#transport>`_ 
namelist controls the creation of these diagnostics.

The auxilary latitudinal grid choices have the following definitions:

-  **'southern'** 
   assumes that the model grid is regular lat-lon in the
   Southern Hemisphere only and uses it identically in the Southern
   Hemisphere. it is flipped across the Equator and padded at northern
   high latitudes if necessary.

-  **'full'** 
   assumes that the entire model grid is regular lat-lon.
   simply copies this grid into the axilary grid arrays.

-  **'user'** 
   allows the user to specify an equally-spaced grid,
   starting at lat\_aux\_begin and ending at lat\_aux\_end. the grid
   dimension/resolution is specified with n\_lat\_aux\_grid.
   lat\_aux\_begin and lat\_aux\_end specify the egde coordinates in
   degrees north.

The following are the resolution-specific transport contents files for
POP2. CIME scripts automatically use the appropriate
resolution-specific transport contents file based upon the resolution
specified in the ``create_newcase`` command.

To customize a transport contents file for your own research, copy the
appropriate resolution-specific contents file from your CESM
distribution into your $CASE/SourceMods/src.pop2 directory, modify it to
suit your needs, and then run your case.

**gx1v6:**

::

    11
     297  297   24   47    1   60 merid  Drake Passage
      65   76  103  103    1   60 zonal  Mozambique Channel
     198  202  333  333    1   60 zonal  Bering Strait
     242  248  372  372    1   60 zonal  Northwest Passage
     131  131  164  167    1   60 merid  Indonesian Throughflow I
     138  161  156  156    1   60 zonal  Indonesian Throughflow II
     284  284  264  270    1   60 merid  Florida Strait
     289  292  258  258    1   60 zonal  Windward Passage I
     292  292  257  258    1   60 merid  Windward Passage II
      32   32  290  295    1   60 merid  Gibraltar
     234  234  373  380    1   60 merid  Nares Strait

**gx3v7:**

::

    4
      93   93   10   17    1   60 merid  Drake Passage
      61   64   84   84    1   60 zonal  Bering Strait
      45   45   32   38    1   60 merid  Indonesian Throughflow
      89   89   71   73    1   60 merid  Florida Strait

**tx0.1v2:**

::

    141
     436  436  287  521    1   42 merid  ACC-Drake
     292  292 1418 1443    1   42 merid  Florida Strait
     230  256 1403 1403    1   42 zonal  Yucatan Passage (Zonal)
     256  256 1404 1406    1   42 merid  Yucatan Passage (Merid)
     332  357 1369 1369    1   42 zonal  Jamaica Channel
     350  367 1385 1385    1   42 zonal  Windward Passage
     414  428 1369 1369    1   42 zonal  Mona Passage
     442  470 1366 1366    1   42 zonal  Anegada+Virgin Passage
     470  482 1356 1356    1   42 zonal  Antigua (Zonal)
     469  469 1357 1357    1   42 merid  Antigua (Merid)
     483  483 1348 1356    1   42 merid  Guadeloupe Passage
     486  486 1340 1347    1   42 merid  Dominica Passage
     487  487 1332 1337    1   42 merid  Martinique Passage (Merid)
     488  489 1331 1331    1   42 zonal  Martinique Passage (Zonal)
     491  491 1324 1329    1   42 merid  St Lucia Channel
     489  489 1317 1322    1   42 merid  St Vincent Passage
     484  484 1305 1316    1   42 merid  Grenadines (Merid)
     485  488 1316 1316    1   42 zonal  Grenadines (Zonal)
     484  484 1290 1304    1   42 merid  Trinidad
     470  470 1290 1366    1   42 merid  Antilles Inflow
     300  313 1458 1458    1   42 zonal  Grand Bahama
     320  320 1442 1460    1   42 merid  NW Providence Channel
     324  324 1409 1427    1   42 merid  Old Bahama Channel
     368  368 1385 1397    1   42 merid  Great Inagua
     452  452 1368 1524    1   42 merid  St Thomas-Bermuda
     452  452 1524 1669    1   42 merid  Bermuda-Yarmouth
    2929 2947 1979 1979    1   42 zonal  Bering Strait
    3141 3141 2239 2284    1   42 merid  Amundsen Gulf
    3032 3072 2328 2328    1   42 zonal  MClure Strait
    3104 3111 2361 2361    1   42 zonal  Prince of Wales Strait
    3021 3030 2368 2368    1   42 zonal  Fitzwilliam Strait
    3000 3000 2369 2385    1   42 merid  Ballantyne Strait
    2983 2993 2386 2386    1   42 zonal  Wilkins Strait
     623  623 2377 2398    1   42 merid  Gustaf Adolf Strait
     608  608 2382 2400    1   42 merid  Hazen Strait (Merid)
     605  608 2381 2381    1   42 zonal  Hazen Strait (Zonal)
     603  623 2377 2377    1   42 zonal  MacLean Strait
     638  662 2362 2362    1   42 zonal  Peary Channel
     665  665 2348 2358    1   42 merid  Axel Heiber Island
     630  630 2348 2354    1   42 merid  Hassel Sound
     616  621 2332 2332    1   42 zonal  Hendricksen Strait
     599  613 2320 2320    1   42 zonal  Belcher Channel
     619  634 2320 2320    1   42 zonal  Norweigan Bay
     584  584 2323 2337    1   42 merid  Penny Strait
     578  590 2370 2370    1   42 zonal  Desbarats Strait
     559  559 2363 2375    1   42 merid  Byam Martin Channel
     540  540 2368 2375    1   42 merid  Byam Channel
     542  542 2339 2361    1   42 merid  Austin Channel
     550  550 2316 2324    1   42 merid  McDougall Sound
     595  598 2294 2294    1   42 zonal  Cardigan Strait
     554  554 2287 2298    1   42 merid  Wellington Channel
     619  619 2240 2248    1   42 merid  Glacier Strait
     609  617 2238 2238    1   42 zonal  Lady Ann Strait
     582  582 2202 2231    1   42 merid  Lancaster Sound
     576  576 2171 2181    1   42 merid  Pond Inlet
     539  539 2253 2268    1   42 merid  Prince Regent Inlet
     538  555 2275 2275    1   42 zonal  Barrow Strait
     518  518 2299 2311    1   42 merid  Peel Sound
     516  546 2326 2326    1   42 zonal  East Viscount Melville
     501  501 2338 2363    1   42 merid  McClintock Channel
     501  537 2375 2375    1   42 zonal  West Viscount Melville
     366  375 2351 2351    1   42 zonal  Dolphin and Union Strait
     385  385 2295 2307    1   42 merid  Victoria Strait
     386  386 2283 2289    1   42 merid  James Ross Strait
     687  687 2248 2258    1   42 merid  Robeson Channel
     583  656 2010 2010    1   42 zonal  Davis Strait
     522  522 1920 1951    1   42 merid  Hudson Bay
     867  867 1941 2003    1   42 merid  Denmark Strait
     911 1107 1907 1907    1   42 zonal  Iceland-Norway
     921 1022 2215 2215    1   42 zonal  Fram Strait
    1097 1388 2211 2211    1   42 zonal  Barents Sea
    2241 2241  958 1096    1   42 merid  Indonesian Throughflow
    1380 1380  810  833    1   42 merid  Agulhas
    1477 1540 1005 1005    1   42 zonal  Mozambique Channel
    2125 2135 1196 1196    1   42 zonal  Malacca Strait
    2144 2195 1171 1171    1   42 zonal  Karimata Strait
    2158 2158 1121 1124    1   42 merid  Sunda Strait
    2225 2225 1111 1150    1   42 merid  Java Sea
    2255 2261 1095 1095    1   42 zonal  Lombok Strait
    2292 2295 1096 1096    1   42 zonal  Sape Strait
    2292 2292 1088 1095    1   42 merid  Sumba Passage
    2298 2298 1096 1126    1   42 merid  Flores Sea
    2275 2297 1175 1175    1   42 zonal  Makassar Strait
    2350 2350 1092 1100    1   42 merid  Ombai Strait
    2351 2351 1100 1103    1   42 merid  Unknown Strait (Merid)
    2352 2359 1103 1103    1   42 zonal  Unknown Strait (Zonal)
    2275 2297 1175 1175    1   42 zonal  Makassar Strait
    2364 2364 1097 1103    1   42 merid  Wetar Strait
    2373 2410 1098 1098    1   42 zonal  Banda-Timor Seas (Zonal)
    2410 2410 1099 1100    1   42 merid  Banda-Timor Seas (Merid)
    2411 2478 1101 1101    1   42 zonal  Arafura Sea
    2419 2428 1111 1111    1   42 zonal  Tanimbar (Zonal)
    2428 2428 1112 1124    1   42 merid  Tanimbar (Merid)
    2428 2428 1127 1145    1   42 merid  Kai
    2408 2428 1145 1145    1   42 zonal  Ceram Sea
    2403 2403 1152 1162    1   42 merid  Misool
    2404 2404 1165 1180    1   42 merid  Dampier Strait
    2380 2404 1180 1180    1   42 zonal  Halmahera Sea
    2381 2398 1166 1166    1   42 zonal  Ceram Sea (Zonal)
    2398 2398 1162 1166    1   42 merid  Ceram Sea (Merid)
    2376 2376 1170 1175    1   42 zonal  Obi Strait
    2363 2375 1164 1164    1   42 zonal  Mangole (Zonal)
    2375 2375 1165 1166    1   42 merid  Mangole (Merid)
    2361 2361 1151 1158    1   42 merid  Sanana
    2371 2380 1150 1150    1   42 zonal  Buru
    2317 2344 1164 1164    1   42 zonal  Banggai
    2352 2376 1197 1197    1   42 zonal  Molucca Sea
    2352 2352 1198 1218    1   42 merid  Southeast Celebes Sea (Merid)
    2353 2356 1218 1218    1   42 zonal  Southeast Celebes Sea (Zonal)
    2356 2356 1218 1241    1   42 merid  Northeast Celebes Sea
    2368 2380 1203 1203    1   42 zonal  Talaud (Zonal)
    2367 2367 1203 1223    1   42 merid  Talaud (Merid)
    2362 2368 1227 1227    1   42 zonal  Mindanao (Zonal)
    2361 2361 1227 1247    1   42 merid  Mindanao (Merid)
    2293 2293 1236 1247    1   42 merid  Sulu Archipelago (Merid)
    2294 2320 1247 1247    1   42 zonal  Sulu Archipelago (Zonal)
    2273 2273 1249 1266    1   42 merid  Balabac Strait
    2296 2296 1296 1301    1   42 merid  Linapacan Strait (Merid)
    2297 2300 1301 1301    1   42 zonal  Linapacan Strait (Zonal)
    2300 2311 1306 1306    1   42 zonal  Mindoro Strait
    2313 2320 1302 1302    1   42 zonal  Tablas Strait (Zonal)
    2312 2312 1303 1306    1   42 merid  Tablas Strait (Merid)
    2332 2332 1268 1274    1   42 merid  Bohol Sea
    2183 2299 1345 1345    1   42 zonal  South China Sea
    2525 2525 1074 1090    1   42 merid  Torres Strait
    2309 2309 1372 1408    1   42 merid  Luzon Strait
    2302 2302 1426 1463    1   42 merid  Taiwan Strait
    2318 2338 1434 1434    1   42 zonal  Ryuku1
    2339 2354 1434 1434    1   42 zonal  Ryuku2 (Zonal)
    2354 2354 1435 1438    1   42 merid  Ryuku2 (Merid)
    2354 2354 1435 1454    1   42 merid  Ryuku3 (Merid)
    2355 2378 1454 1454    1   42 zonal  Ryuku3 (Zonal)
    2383 2383 1461 1476    1   42 merid  Ryuku4 (Merid)
    2384 2393 1476 1476    1   42 zonal  Ryuku4 (Zonal)
    2397 2405 1479 1479    1   42 zonal  Tokara Strait (Zonal)
    2405 2405 1480 1499    1   42 merid  Tokara Strait (Merid)
    2407 2407 1500 1509    1   42 merid  Ohsumi Strait
    2396 2396 1532 1546    1   42 merid  Southern Korea Strait
    2396 2396 1547 1557    1   42 merid  Northern Korea Strait
    2508 2508 1618 1622    1   42 merid  Tsugaru Strait
    2527 2527 1667 1675    1   42 merid  La Perouse Strait


Model output files
===================

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.


Time-averaged history files
---------------------------

The time-averaged history-file ("tavg") module provides:

-  support for the creation of multiple, simultaneous output streams
   generated during a single model run
-  "timeseries files," which are output files containing multiple time
   levels per file.
-  an "offset" date specification, which allows finer control over the
   tavg\_freq and tavg\_freq\_opt options described below.
-  the option for a "one-time header," in which all time-invariant
   information is written into the first tavg file of each stream, at
   the beginning of each run segment, and then omitted from all
   subsequent files in that stream for the remainder of the run segment.
-  support for `double-precision tavg output files <node27.html>`__

POP2 supports the creation of a maximum of four
concurrent tavg output streams, with a hard limit of nine streams
possible if the tavg module is appropriately modified. Options for each
of the streams is set individually, using array syntax in the namelist.

The first character of each line in the ``tavg_contents``
file is either a comment character or an integer in the interval [1,4].
The next two characters must be blank; the remaining characters on the
line spell out the short name of a requested variable.

If the leading character is a comment character -- either the pound sign
(#) or the exclamation point (!) -- then the entire line is treated as a
comment. If the leading character on the line is an integer, it
identifies the number of the output stream in which the requested field
will appear. Each requested tavg output field may be assigned to only
one stream; assigning the same field to more than one stream will result
in the model ignoring it and all subsequent requests. Similarly,
duplicate requests of the same field within the same stream will be
eliminated. In all cases, a summary of field and stream assignments is
printed in the output log file, which allows the user to confirm which
fields will be written to which stream.

Output filenames for the each stream are determined from within the
tavg module, incorporating the stream number into the output
filename in all but the first stream. This seemingly inconsistent
treatment of tavg output filenames was chosen based on the requirement
for backwards-compatability in filenames. For example, a one-stream case
would generate tavg output files of the form ``$CASE.pop.h.*``; an
N-stream case would generate tavg output files of the form
``$CASE.pop.h.*, $CASE.pop.h2.*, ..., $CASE.pop.hN.*``

Most of the tavg namelist variables are now arrays of length
(``max_avail_tavg_streams``), which allows the user to set controls for
each tavg history-file stream on a stream-by-stream basis.

In the table below, any array element that is undefined in the 
POP namelist file is set to the default value identified in curly
braces.

The `tavg_nml <http://www.cesm.ucar.edu/models/cesm1.2/cesm/doc/modelnl/nl_pop2.html#tavg>`_ namelist
controls how time average files are created.

Table: **Table:** Current available tavg fields

+-------------------+----------------------------+-------------------------------------------------------------+
| **Name**          | **Units**                  | **Description**                                             |
+-------------------+----------------------------+-------------------------------------------------------------+
| SHF               | *W/m\ :sup:`2`*            | Surface Heat Flux                                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| SFWF              | *mm/day*                   | Surface Freshwater Flux (p-e)                               |
+-------------------+----------------------------+-------------------------------------------------------------+
| SSH               | *cm*                       | Sea Surface Height                                          |
+-------------------+----------------------------+-------------------------------------------------------------+
| SSH2              | *cm\ :sup:`2`*             | SSH\ :sup:`2`                                               |
+-------------------+----------------------------+-------------------------------------------------------------+
| H3                | unitless                   | *(Δ:sub:`x`\ (SSH)):sup:`2` + (Δ:sub:`y`\ (SSH)):sup:`2`*   |
+-------------------+----------------------------+-------------------------------------------------------------+
| TAUX              | *dyne/cm\ :sup:`2`*        | Zonal windstress                                            |
+-------------------+----------------------------+-------------------------------------------------------------+
| TAUY              | *dyne/cm\ :sup:`2`*        | Meridional windstress                                       |
+-------------------+----------------------------+-------------------------------------------------------------+
| UVEL              | *cm/s*                     | Zonal Velocity                                              |
+-------------------+----------------------------+-------------------------------------------------------------+
| VVEL              | *cm/s*                     | Meridional Velocity                                         |
+-------------------+----------------------------+-------------------------------------------------------------+
| KE                | *cm\ :sup:`2`/s:sup:`2`*   | Horizontal Kinetic Energy (U:sup:`2` + V\ :sup:`2`)/2       |
+-------------------+----------------------------+-------------------------------------------------------------+
| TEMP              | *:sup:`o`\ C*              | Potential Temperature                                       |
+-------------------+----------------------------+-------------------------------------------------------------+
| SALT              | *g/g*                      | Salinity                                                    |
+-------------------+----------------------------+-------------------------------------------------------------+
| TEMP2             | *:sup:`o`\ C\ :sup:`2`*    | Temperature\ :sup:`2`                                       |
+-------------------+----------------------------+-------------------------------------------------------------+
| SALT2             | *(g/g):sup:`2`*            | Salt\ :sup:`2`                                              |
+-------------------+----------------------------+-------------------------------------------------------------+
| UET               | *:sup:`o`\ C/s*            | East Flux of Heat                                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| VNT               | *:sup:`o`\ C/s*            | North Flux of Heat                                          |
+-------------------+----------------------------+-------------------------------------------------------------+
| WTT               | *:sup:`o`\ C/s*            | Top Flux of Heat                                            |
+-------------------+----------------------------+-------------------------------------------------------------+
| UES               | *g/g/s*                    | East Flux of Salt                                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| VNS               | *g/g/s*                    | North Flux of Salt                                          |
+-------------------+----------------------------+-------------------------------------------------------------+
| WTS               | *g/g/s*                    | Top Flux of Salt                                            |
+-------------------+----------------------------+-------------------------------------------------------------+
| UEU               | *cm/s\ :sup:`2`*           | East Flux of Zonal Momentum                                 |
+-------------------+----------------------------+-------------------------------------------------------------+
| VNU               | *cm/s\ :sup:`2`*           | North Flux of Zonal Momentum                                |
+-------------------+----------------------------+-------------------------------------------------------------+
| UEV               | *cm/s\ :sup:`2`*           | East Flux of Meridional Momentum                            |
+-------------------+----------------------------+-------------------------------------------------------------+
| VNV               | *cm/s\ :sup:`2`*           | North Flux of Meridional Momentum                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| PV                | *1/s*                      | Potential Vorticity                                         |
+-------------------+----------------------------+-------------------------------------------------------------+
| Q                 | *g/cm\ :sup:`4`*           | z-derivative of potential density                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| PD                | *g/cm\ :sup:`3`*           | Potential density referenced to surface                     |
+-------------------+----------------------------+-------------------------------------------------------------+
| UDP               | *erg*                      | Pressure work                                               |
+-------------------+----------------------------+-------------------------------------------------------------+
| PEC               | *g/cm\ :sup:`3`*           | Potential energy release due to convection                  |
+-------------------+----------------------------+-------------------------------------------------------------+
| NCNV              | *adjustments/s*            | Convective adjustments per second                           |
+-------------------+----------------------------+-------------------------------------------------------------+
| WTU               | *cm/s\ :sup:`2`*           | Top flux of Zonal Momentum                                  |
+-------------------+----------------------------+-------------------------------------------------------------+
| WTV               | *cm/s\ :sup:`2`*           | Top flux of Meridional Momentum                             |
+-------------------+----------------------------+-------------------------------------------------------------+
| ST                | *:sup:`o`\ Cg/g*           | Temperature\*Salinity                                       |
+-------------------+----------------------------+-------------------------------------------------------------+
| RHO               | *g/cm\ :sup:`3`*           | In-situ density                                             |
+-------------------+----------------------------+-------------------------------------------------------------+


**Table:** Additional available tavg fields
**Name**
**Units**
**Description**

"QFLUX",
"*Watts/m\ :sup:`2`*",
"Internal Ocean Heat Flux Due to Ice Formation; heat of fusion > 0 or ice-melting potential < 0",

"BSF",
"*Sv*",
"Barotropic Stream Function",

"TFW\_T",
"*Watts/m\ :sup:`2`*",
"T flux due to freshwater flux",

"TFW\_S",
"*kg/m\ :sup:`2`/s*",
"S flux due to freshwater flux (kg of salt/m^2/s)",

"RESID\_T",
"*Watts/m\ :sup:`2`*",
"Free-Surface Residual Flux (T)",

"RESID\_S",
"*kg/m\ :sup:`2`/s*",
"Free-Surface Residual Flux (S)",

"QSW\_HTP",
"*Watts/m\ :sup:`2`*",
"Solar Short-Wave Heat Flux in top layer",

"QSW\_HBL",
"*Watts/m\ :sup:`2`*",
"Solar Short-Wave Heat Flux in boundary layer",

"SHF\_QSW",
"*Watts/m\ :sup:`2`*",
"Solar Short-Wave Heat Flux",

"PREC\_F",
"*kg/m\ :sup:`2`/s*",
"Precipitation Flux from Coupler (rain+snow)",

"SNOW\_F",
"*kg/m\ :sup:`2`/s*",
"Snow Flux from Coupler",

"EVAP\_F",
"*kg/m\ :sup:`2`/s*",
"Evaporation Flux from Coupler",

"MELT\_F",
"*kg/m\ :sup:`2`/s*",
"Melt Flux from Coupler",

"ROFF\_F",
"*kg/m\ :sup:`2`/s*",
"Runoff Flux from Coupler",

"IOFF\_F",
"*kg/m\ :sup:`2`/s*",
"Ice Flux from Coupler due to Land-Model Snow Capping",

"SALT\_F",
"*kg/m\ :sup:`2`/s*",
"Salt Flux from Coupler (kg of salt/m^2/s)",

"SENH\_F",
"*kg/m\ :sup:`2`/s*",
"Sensible Heat Flux from Coupler",

"LWUP\_F",
"*Watts/m\ :sup:`2`*",
"Longwave Heat Flux (up) from Coupler",

"LWDN\_F",
"*Watts/m\ :sup:`2`*",
"Longwave Heat Flux (down) from Coupler",

"MELTH\_F",
"*Watts/m\ :sup:`2`*",
"Melt Heat Flux from Coupler",

"IFRAC",
"*unitless fraction*",
"Ice Fraction from Coupler",

"HMXL and HMXL\_2",
"*cm*",
"Mixed-Layer Depth",

"XMXL and XMXL\_2",
"*cm*",
"Maximum Mixed-Layer Depth",

"TMXL",
"*cm*",
"Minimum Mixed-Layer Depth",

"HBLT",
"*cm*",
"Boundary-Layer Depth",

"XBLT",
"*cm*",
"Maximum Boundary-Layer Depth",

"TBLT",
"*cm*",
"Minimum Boundary-Layer Depth",

"FW",
"*cm/s*",
"Freshwater Flux",

"ADVT",
"*cm/\ :sup:`o`\ C/s*",
"Vertically-Integrated T Advection Tendency",

"ADVS",
"*cm g/km/s*",
"Vertically-Integrated S Advection Tendency",

"dTEMP\_POS\_2D",
"*:sup:`o`\ C*",
"max positive column temperature timestep diff",

"dTEMP\_NEG\_2D",
"*:sup:`o`\ C*",
"max negative column temperature timestep diff",

"KAPPA\_ISOP",
"*cm\ :sup:`2`/s*",
"Isopycnal diffusion coefficient",

"KAPPA\_THIC",
"*cm\ :sup:`2`/s*",
"Thickness diffusion coefficient",

"HOR\_DIFF",
"*cm\ :sup:`2`/s*",
"Horizontal diffusion coefficient",

"DIA\_DEPTH",
"*cm*",
"Depth of the Diabatic Region at the Surface",

"TLT",
"*cm*",
"Transition Layer Thickness",

"INT\_DEPTH",
"*cm*",
"Depth at which the Interior Region Starts",

"UISOP",
"*cm/s*",
"Bolus Velocity in grid-x direction (diagnostic)",

"VISOP",
"*cm/s*",
"Bolus Velocity in grid-y direction (diagnostic)",

"WISOP",
"*cm/s*",
"Vertical Bolus Velocity (diagnostic)",

"ADVT\_ISOP",
"*cm/\ :sup:`o`\ C/s*",
"Vertically-Integrated T Eddy-Induced Advection Tendency (diagnostic)",

"ADVS\_ISOP",
"*cm g/km/s*",
"Vertically-Integrated S Eddy-Induced Advection Tendency (diagnostic)",

"VNT\_ISOP",
"*:sup:`o`\ C/s*",
"Heat Flux Tendency in grid-y Dir due to Eddy-Induced Vel (diagnostic)",

"VNS\_ISOP",
"*g/km/s*",
"Salt Flux Tendency in grid-y Dir due to Eddy-Induced Vel (diagnostic)",

"KVMIX",
"*cm\ :sup:`2`/s*",
"Vertical diabatic diffusivity due to background or Tidal Mixing + background",

"KVMIX\_M",
"*cm\ :sup:`2`/s*",
"Vertical viscosity due to background or Tidal Mixing + background",

"TPOWER",
"*erg/s*",
"Energy Used by Vertical Mixing",

"VVC\_BCK",
"*cm\ :sup:`2`/s*",
"Vertical viscosity due to background",

"USUBM",
"*cm/s*",
"Submeso velocity in grid-x direction (diagnostic)",

"VSUBM",
"*cm/s*",
"Submeso velocity in grid-y direction (diagnostic)",

"WSUBM",
"*cm/s*",
"Vertical submeso velocity (diagnostic)",

"ADVT\_SUBM",
"*cm/\ :sup:`o`\ C/s*",
"Vertically-Integrated T submeso Advection Tendency (diagnostic)",

"ADVS\_SUBM",
"*cm g/km/s*",
"Vertically-Integrated S submeso Advection Tendency (diagnostic)",

"VNT\_SUBM",
"*:sup:`o`\ C/s*",
"Heat Flux Tendency in grid-y Dir due to submeso Vel (diagnostic)",

"VNS\_SUBM",
"*:sup:`o`\ C/s*",
"Salt Flux Tendency in grid-y Dir due to submeso Vel (diagnostic)",

"HLS\_SUBM",
"*cm*",
"Horizontal length scale used in submeso",

"VDC\_T",
"*cm\ :sup:`2`/s*",
"total diabatic vertical TEMP diffusivity",

"VDC\_S",
"*cm\ :sup:`2`/s*",
"total diabatic vertical SALT diffusivity",

"UVEL2",
"*cm\ :sup:`2`/s:sup:`2`*",
"Velocity in grid-x direction",

"VVEL2",
"*cm\ :sup:`2`/s:sup:`2`*",
"Velocity in grid-y direction",

"WVEL2",
"*cm\ :sup:`2`/s:sup:`2`*",
"Vertical Velocity\ :sup:`2`",

"RHO\_VINT",
"*g/cm\ :sup:`2`*",
"Vertical Integral of In-Situ Density",

"SFWF\_WRST",
"*kg/m\ :sup:`2`/s*",
"Virtual Salt Flux due to weak restoring",

"TAUX2",
"*dyne\ :sup:`2`/cm:sup:`4`*",
"Windstress\ :sup:`2` in grid-x direction",

"TAUY2",
"*dyne\ :sup:`2`/cm:sup:`4`*",
"Windstress\ :sup:`2` in grid-y direction",

"SSH2",
"*cm\ :sup:`2`*",
"SSH\ :sup:`2`",

"VVC",
"*cm\ :sup:`2`/s*",
"total vertical momentum viscosity",

"VDC\_BCK",
"*cm\ :sup:`2`/s*",
"Vertical diabatic diffusivity due to background",

Note that we append "\_2" to a variable name in order to write that
variable to two tavg output files; this convention can be extended to
more than two streams in a similar fashion.

To customize tavg output in your run:

-  > ``create_newcase -case $CASE ...`` per the instructions
-  > cd $CASE
-  > cd $CASE/SourceMods/src.pop2
-  > cp $CCSMROOT/models/ocn/pop2/input\_templates/$RES\_tavg\_contents
   .
-  > edit $RES\_tavg\_contents -- comment out, activate, or change
   streams according the the instructions above.

then continue with the CIME $CASE configure, build, and run procedure.


Snapshot history files
-----------------------

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).


**Table:** History file namelist
**&history\_nml**
**Generation of snapshot history files**
history\_freq\_opt
['never'],'nstep', 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond'
units of time for history\_freq
history\_freq
[100000]
number of units between output of snapshot history files
history\_outfile
['unknown']
root filename with path of history file output (suffixes will be added)
history\_fmt
['bin'],'nc'
format for history files (binary or netCDF)
history\_contents
['history\_contents']
input file containing names of fields requested to be output
/


**Table:** Currently available history fields
**Name**
**Units**
**Description**
SHGT
*cm*
surface height
UBTROP
*cm/s*
barotropic 'zonal' velocity
VBTROP
*cm/s*
barotropic 'meridional' velocity
UVEL
*cm/s*
'zonal' velocity
VVEL
*cm/s*
'meridional' velocity
TEMP
*° C*
potential temperature
SALT
*g/g* (msu)
salinity
SUF
cm\ :sup:`2`/s:sup:`2`
surface velocity flux in U direction
SVF
cm\ :sup:`2`/s:sup:`2`
surface velocity flux in V direction
SHF
W/m\ :sup:`2`
surface heat flux
SFWF
*m/year*
surface fresh water flux
SOLAR
W/m\ :sup:`2`
solar short wave flux at surface


Movie files
------------

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
``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.

**Table:** Movie file namelist
**&movie\_nml**
**generation of snapshot movie files**
movie\_freq\_opt
['never'], 'nstep', 'nyear','nmonth','nday', 'nhour','nsecond'
units of time for movie\_freq
movie\_freq
[100000]
number of units between output of movie files
movie\_outfile
['unknown']
root filename with path of movie file output (suffixes will be added)
movie\_fmt
['bin'],'nc'
format for movie file output (binary or netCDF)
movie\_contents
['sample\_movie\_contents']
input file containing names of fields requested for movie output
/

**Table:** Currently available movie fields
**Name**
**Units**
**Description**
SHGT
*cm*
surface height
UTRANS
*cm\ :sup:`2`/s*
vertically integrated 'zonal' transport
VTRANS
*cm\ :sup:`2`/s*
vertically integrated 'meridional' transport
TEMP1\_2
*:sup:`°`\ C*
potential temperature averaged over levels 1,2
SALT1\_2
*g/g* (msu)
salinity averaged over levels 1,2
TEMP6
*:sup:`°`\ C*
potential temperature at level 6
SALT6
*g/g* (msu)
salinity at level 6
VORT
1/\ *s*
relative vorticity at surface

POP2 does not support for current meters, drifters, or hydrographic sections.