--- manual/s_outp_pkgs/text/diagnostics.tex	2005/07/18 20:45:27	1.1
+++ manual/s_outp_pkgs/text/diagnostics.tex	2006/04/06 00:46:13	1.4
@@ -1,195 +1,207 @@
-\subsection{Diagnostics--A Flexible Infrastructure}
+\section{Diagnostics--A Flexible Infrastructure}
 \label{sec:pkg:diagnostics}
 \begin{rawhtml}
 <!-- CMIREDIR:package_diagnostics: -->
 \end{rawhtml}
 
-\subsubsection{Introduction}
+\subsection{Introduction}
 
 \noindent
-This section of the documentation describes the Diagnostics package available within 
-the GCM.  A large selection of model diagnostics is available for output.  
-In addition to the diagnostic quantities pre-defined in the GCM, there exists
-the option, in any experiment, to define a new diagnostic quantity and include it
-as part of the diagnostic output with the addition of a single subroutine call in the
-routine where the field is computed. As a matter of philosophy, no diagnostic is enabled 
-as default, thus each user must specify the exact diagnostic information required for an 
-experiment.  This is accomplished by enabling the specific diagnostic of interest cataloged 
-in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). Instructions for enabling
-diagnostic output and defining new diagnostic quantities are found in Section 
+This section of the documentation describes the Diagnostics package
+available within the GCM.  A large selection of model diagnostics is
+available for output.  In addition to the diagnostic quantities
+pre-defined in the GCM, there exists the option, in any experiment, to
+define a new diagnostic quantity and include it as part of the
+diagnostic output with the addition of a single subroutine call in the
+routine where the field is computed. As a matter of philosophy, no
+diagnostic is enabled as default, thus each user must specify the
+exact diagnostic information required for an experiment.  This is
+accomplished by enabling the specific diagnostic of interest cataloged
+in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}).
+Instructions for enabling diagnostic output and defining new
+diagnostic quantities are found in Section
 \ref{sec:diagnostics:usersguide} of this document.
 
 \noindent
-The Diagnostic Menu in this section of the manual is a listing of diagnostic quantities available 
-within the main (dynamics) part of the GCM. Additional diagnostic quantities, defined within the
-different GCM packages, are available and are listed in the diagnostic menu subsection of 
-the manual section associated with each relevant package. Once a diagnostic is enabled, the 
-GCM will continually increment an array specifically allocated for that diagnostic whenever the 
-appropriate quantity is computed.  A counter is defined which records how many times each diagnostic 
-quantity has been incremented.  Several special diagnostics are included in the menu. Quantities 
-refered to as ``Counter Diagnostics'', are defined for selected diagnostics which record the 
-frequency at which a diagnostic is incremented separately for each model grid location.
-Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate
-defining new diagnostics for a particular experiment.
+The Diagnostic Menu in this section of the manual is a listing of
+diagnostic quantities available within the main (dynamics) part of the
+GCM. Additional diagnostic quantities, defined within the different
+GCM packages, are available and are listed in the diagnostic menu
+subsection of the manual section associated with each relevant
+package. Once a diagnostic is enabled, the GCM will continually
+increment an array specifically allocated for that diagnostic whenever
+the appropriate quantity is computed.  A counter is defined which
+records how many times each diagnostic quantity has been incremented.
+Several special diagnostics are included in the menu. Quantities
+refered to as ``Counter Diagnostics'', are defined for selected
+diagnostics which record the frequency at which a diagnostic is
+incremented separately for each model grid location.  Quantitied
+refered to as ``User Diagnostics'' are included in the menu to
+facilitate defining new diagnostics for a particular experiment.
 
-\subsubsection{Equations}
+\subsection{Equations}
 Not relevant.
 
-\subsubsection{Key Subroutines and Parameters}
+\subsection{Key Subroutines and Parameters}
 \label{sec:diagnostics:diagover}
 
 \noindent
-There are several utilities within the GCM available to users to enable, disable,
-clear, write and retrieve model diagnostics, and may be called from any routine.  
-The available utilities and the CALL sequences are listed below.
-
-\noindent
-{\bf diagnostics\_fill}:  This is the main user interface routine to the diagnostics
-package. This routine will increment the specified diagnostic quantity with a field 
-sent through the argument list.
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>        call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\
-\>              bibjflg, bi, bj, myThid) \\
-\\
-where \>  arrayin  \>= Field to increment diagnostics array \\
-      \>  chardiag \>= Character *8 expression for diag to fill \\
-      \>  levflg   \>= Integer flag for vertical levels: \\
-      \>           \>= 0 indicates multiple (nlevs) levels incremented \\
-      \>           \>= -1 indicates multiple (nlevs) levels incremented, \\
-      \>           \> but in reverse vertical order \\
-      \>           \> positive integer - WHICH single level to increment. \\
-      \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg gt 0) \\
-      \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\
-      \>           \>= 0 indicates that the bi-bj loop must be done here \\
-      \>           \>= 1 indicates that the bi-bj loop is done OUTSIDE \\
-      \>           \>= 2 indicates that the bi-bj loop is done OUTSIDE \\
-      \>           \>    AND that we have been sent a local array \\
-      \>           \>    AND that the array has the shadow regions \\
-      \>           \>= 3 indicates that the bi-bj loop is done OUTSIDE \\
-      \>           \>    AND that we have been sent a local array \\
-      \>           \>    AND that the array has no shadow regions \\
-      \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\
-      \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\
-      \>  myThid   \>= Current Thread number \\
-\end{tabbing}
+There are several utilities within the GCM available to users to
+enable, disable, clear, write and retrieve model diagnostics, and may
+be called from any routine.  The available utilities and the CALL
+sequences are listed below.
+
+\noindent
+{\bf diagnostics\_fill}: This is the main user interface routine to
+the diagnostics package. This routine will increment the specified
+diagnostic quantity with a field sent through the argument list.
+
+\begin{verbatim}
+        call diagnostics_fill(
+       &      arrayin, chardiag, levflg, nlevs,
+       &      bibjflg, bi, bj, myThid )
+
+     where:
+        arrayin  = Field to increment diagnostics array
+        chardiag = Character *8 expression for diag to fill
+        levflg   = Integer flag for vertical levels:
+                 = 0 indicates multiple (nlevs) levels incremented
+                 = -1 indicates multiple (nlevs) levels incremented,
+                     but in reverse vertical order
+                     positive integer - WHICH single level to increment.
+        nlevs    = indicates Number of levels to be filled (1 if levflg gt 0)
+        bibjflg  = Integer flag to indicate instructions for bi bj loop
+                 = 0 indicates that the bi-bj loop must be done here
+                 = 1 indicates that the bi-bj loop is done OUTSIDE
+                 = 2 indicates that the bi-bj loop is done OUTSIDE
+                     AND that we have been sent a local array
+                     AND that the array has the shadow regions
+                 = 3 indicates that the bi-bj loop is done OUTSIDE
+                     AND that we have been sent a local array
+                     AND that the array has no shadow regions
+        bi       = X-direction process(or) number - used for bibjflg=1-3
+        bj       = Y-direction process(or) number - used for bibjflg=1-3
+        myThid   = Current Thread number
+\end{verbatim}
 
 \noindent
 {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to
 diagnostics\_fill which performs the same functions and has an additional option
 to scale the field before filling or raise the field to a power before filling.
 
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>        call diagnostics\_scale\_fill (arrayin, scalefactor, power, chardiag, \\
-\>        levflg, nlevs, bibjflg, bi, bj, myThid) \\
-\\
-where \>  All the arguments are the same as for diagnostics\_fill with the addition of: \\
-      \>  scalefactor \>= Factor to scale field \\
-      \>  power       \>= Integer power to which to raise the input field \\
-\end{tabbing}
-
-\noindent
-{\bf diagnostics\_is\_on}: Function call to inquire whether a diagnostic is active
-and can be incremented. Useful when there is a computation that must be done locally
-before a call to diagnostics\_fill. The call sequence:
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\> flag = diagnostics\_is\_on( diagName, myThid )
-\\
-where \>  diagName \>= Character *8 expression for diagnostic \\
-      \>  myThid   \>= Current Thread number \\
-\end{tabbing}
-
-\noindent
-{\bf diagnostics\_get\_pointers}:  This subroutine retrieves the value of a the diagnostics
-pointers that other routines require as input - can be useful if the diagnostics common
-blocks are not local to a routine.
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid )
-\\
-where \>  diagName \>= Character *8 expression of diagnostic \\
-      \>  ipoint   \>= Pointer into qdiag array - from idiag array in common \\
-      \>  jpoint   \>= Pointer into diagnostics menu - from jdiag array in common \\
-      \>  myThid   \>= Current Thread number \\
-\end{tabbing}
-
-\noindent
-{\bf getdiag}:  This subroutine retrieves the value of a model diagnostic.  This routine 
-is particulary useful when called from a user output routine, although it can be called 
-from any routine.  This routine returns the time-averaged value of the diagnostic by
-dividing the current accumulated diagnostic value by its corresponding counter.  This 
-routine does not change the value of the diagnostic itself, that is, it does not replace 
-the diagnostic with its time-average.  The calling sequence for this routine is givin by:
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\
-\\
-where \>  lev     \>= Model Level at which the diagnostic is desired \\
-      \>  undef   \>= Fill value to be used when diagnostic is undefined \\
-      \>  qtmp    \>= Time-Averaged Diagnostic Output \\
-      \>  ipoint  \>= Pointer into qdiag array - from idiag array in common \\
-      \>  mate    \>= Diagnostic mate pointer number \\
-      \>  bi      \>= X-direction process(or) number \\
-      \>  bj      \>= Y-direction process(or) number \\
-      \>  myThid  \>= Current Thread number \\
-\end{tabbing}
-
-\noindent
-{\bf diagnostics\_add2list}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning 
-that space is allocated for the diagnostic and the model routines will increment the 
-diagnostic value during execution.  This routine is the underlying interface routine
-for defining a new permanent diagnostic in the main model or in a package.  The calling sequence is:
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>        call diagnostics\_add2list( diagNum,diagName, diagCode, \\
-\>        diagUnits, diagTitle, myThid ) \\
-\\
-where \> diagNum   \>=Diagnostic number - Output from routine \\
-      \> diagName  \>=character*8 diagnostic name \\
-      \> diagCode  \>=character*16 parsing code (see description of gdiag below) \\
-      \> diagUnits \>=Diagnostic units (character*16) \\
-      \> diagTitle \>=Diagnostic title or long name (up to character*80) \\
-      \> myThid    \>=Current Thread number \\
-\end{tabbing}
-
-\noindent
-{\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is
-particularly useful when called from user output routines to re-initialize diagnostics 
-during the run.  The calling sequence is:
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>        call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\
-\\
-where \>  jpoint \>= Diagnostic number from menu - from jdiag array \\
-          ipoint \>= Pointer number into qdiag array - from idiag array \\
-      \>  myThid \>=Current Thread number \\
-\end{tabbing}
-
-\noindent
-The diagnostics are computed at various times and places within the GCM. Because the
-MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,
-corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars, 
-while others are components of vectors. An internal array is defined which contains 
-information concerning various grid attributes of each diagnostic. The GDIAG
-array (in common block \\diagnostics in file DIAGNOSTICS.h) is internally defined as a 
-character*8 variable, and is equivalenced to a character*1 "parse" array in output in 
-order to extract the grid-attribute information.  The GDIAG array is described in 
-Table \ref{tab:diagnostics:gdiag.tabl}.
+\begin{verbatim}
+        call diagnostics_scale_fill(
+       &         arrayin, scalefactor, power, chardiag,
+       &         levflg, nlevs, bibjflg, bi, bj, myThid )
+
+     where all the arguments are the same as for diagnostics_fill with 
+     the addition of:
+        scalefactor = Factor to scale field
+        power       = Integer power to which to raise the input field
+\end{verbatim}
+
+\noindent
+{\bf diagnostics\_is\_on}: Function call to inquire whether a
+diagnostic is active and can be incremented. Useful when there is a
+computation that must be done locally before a call to
+diagnostics\_fill. The call sequence:
+
+\begin{verbatim}
+        flag = diagnostics_is_on( diagName, myThid )
+
+     where:
+        diagName = Character *8 expression for diagnostic
+        myThid   = Current Thread number
+\end{verbatim}
+
+\noindent
+{\bf diagnostics\_get\_pointers}: This subroutine retrieves the value
+of a the diagnostics pointers that other routines require as input -
+can be useful if the diagnostics common blocks are not local to a
+routine.
+
+\begin{verbatim}
+        call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid )
+
+     where:
+        diagName = Character *8 expression of diagnostic
+        ipoint   = Pointer into qdiag array - from idiag array in common
+        jpoint   = Pointer into diagnostics menu - from jdiag array in common
+        myThid   = Current Thread number
+\end{verbatim}
+
+\noindent
+{\bf getdiag}: This subroutine retrieves the value of a model
+diagnostic.  This routine is particulary useful when called from a
+user output routine, although it can be called from any routine.  This
+routine returns the time-averaged value of the diagnostic by dividing
+the current accumulated diagnostic value by its corresponding counter.
+This routine does not change the value of the diagnostic itself, that
+is, it does not replace the diagnostic with its time-average.  The
+calling sequence for this routine is givin by:
+
+\begin{verbatim}
+        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid)
+
+     where:
+        lev     = Model Level at which the diagnostic is desired
+        undef   = Fill value to be used when diagnostic is undefined
+        qtmp    = Time-Averaged Diagnostic Output
+        ipoint  = Pointer into qdiag array - from idiag array in common
+        mate    = Diagnostic mate pointer number
+        bi      = X-direction process(or) number
+        bj      = Y-direction process(or) number
+        myThid  = Current Thread number
+\end{verbatim}
+
+\noindent 
+{\bf diagnostics\_add2list}: This subroutine enables a diagnostic from
+the Diagnostic Menu, meaning that space is allocated for the
+diagnostic and the model routines will increment the diagnostic value
+during execution.  This routine is the underlying interface routine
+for defining a new permanent diagnostic in the main model or in a
+package.  The calling sequence is:
+
+\begin{verbatim}
+       call diagnostics_add2list( diagNum,diagName, diagCode,
+                                  diagUnits, diagTitle, myThid )
+
+     where:
+       diagNum   = Diagnostic number - Output from routine
+       diagName  = character*8 diagnostic name
+       diagCode  = character*16 parsing code (see description of gdiag below)
+       diagUnits = Diagnostic units (character*16)
+       diagTitle = Diagnostic title or long name (up to character*80)
+       myThid    = Current Thread number
+\end{verbatim}
+
+\noindent
+{\bf clrdiag}: This subroutine initializes the values of model
+diagnostics to zero, and is particularly useful when called from user
+output routines to re-initialize diagnostics during the run.  The
+calling sequence is:
+
+\begin{verbatim}
+        call diagnostics_clrdiag (jpoint, ipoint, myThid)
+
+     where:
+        jpoint = Diagnostic number from menu - from jdiag array
+        ipoint = Pointer number into qdiag array - from idiag array
+        myThid = Current Thread number
+\end{verbatim}
+
+\noindent
+The diagnostics are computed at various times and places within the
+GCM. Because MITgcm may employ a staggered grid, diagnostics may be
+computed at grid box centers, corners, or edges, and at the middle or
+edge in the vertical. Some diagnostics are scalars, while others are
+components of vectors. An internal array is defined which contains
+information concerning various grid attributes of each diagnostic. The
+GDIAG array (in common block {\tt diagnostics} in file {\tt
+  DIAGNOSTICS.h}) is internally defined as a character*8 variable, and
+is equivalenced to a character*1 "parse" array in output in order to
+extract the grid-attribute information.  The GDIAG array is described
+in Table \ref{tab:diagnostics:gdiag.tabl}.
 
 \begin{table}
 \caption{Diagnostic Parsing Array}
@@ -235,7 +247,7 @@
 In this way the User has flexibility in determining the type of gridded data which 
 is output.
 
-\subsubsection{Usage Notes}
+\subsection{Usage Notes}
 \label{sec:diagnostics:usersguide}
 
 \noindent
@@ -252,131 +264,139 @@
 to be computed, specify the frequency and type of output, the number of levels, and 
 the name of all the separate output files. A sample data.diagnostics namelist file:
 
-\noindent
-$\#$ Diagnostic Package Choices \\
- $\&$diagnostics\_list \\
-  frequency(1) = 86400., \ \\
-   levels(1,1) = 1., \ \\
-   fields(1,1) = 'RSURF   ', \ \\
-   filename(1) = 'surface', \ \\
-  frequency(2) = 86400., \ \\
-   levels(1,2) = 1.,2.,3.,4.,5., \ \\
-   fields(1,2) = 'UVEL    ','VVEL    ', \ \\
-   filename(2) = 'diagout1', \ \\
-  frequency(3) = 3600., \ \\
-   fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', \ \\
-   filename(3) = 'diagout2', \ \\
-  fileflags(3) = ' P1     ', \ \\
- $\&$end \ \\
-
-\noindent
-In this example, there are two output files that will be generated
-for each tile and for each output time. The first set of output files
-has the prefix diagout1, does time averaging every 86400. seconds,
-(frequency is 86400.), and will write fields which are multiple-level 
-fields at output levels 1-5. The names of diagnostics quantities are 
-UVEL and VVEL.  The second set of output files
-has the prefix diagout2, does time averaging every 3600. seconds,
-includes fields which are multiple-level fields, levels output are 1-5,
-and the names of diagnostics quantities are THETA and SALT.
-
-\noindent
-The user must assure that enough computer memory is allocated for the diagnostics 
-and the output streams selected for a particular experiment.  This is acomplished by
-modifying the file DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
-The parameters that should be checked are called numdiags, numlists, numperlist, and
-diagSt\_size. 
+\begin{verbatim}
+# Diagnostic Package Choices
+ &diagnostics\_list
+  frequency(1) = 86400., 
+   levels(1,1) = 1., 
+   fields(1,1) = 'RSURF   ', 
+   filename(1) = 'surface', 
+  frequency(2) = 86400., 
+   levels(1,2) = 1.,2.,3.,4.,5., 
+   fields(1,2) = 'UVEL    ','VVEL    ', 
+   filename(2) = 'diagout1', 
+  frequency(3) = 3600., 
+   fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', 
+   filename(3) = 'diagout2', 
+  fileflags(3) = ' P1     ', 
+ &end 
+\end{verbatim}
+
+\noindent
+In this example, there are two output files that will be generated for
+each tile and for each output time. The first set of output files has
+the prefix diagout1, does time averaging every 86400. seconds,
+(frequency is 86400.), and will write fields which are multiple-level
+fields at output levels 1-5. The names of diagnostics quantities are
+UVEL and VVEL.  The second set of output files has the prefix
+diagout2, does time averaging every 3600. seconds, includes fields
+which are multiple-level fields, levels output are 1-5, and the names
+of diagnostics quantities are THETA and SALT.
+
+\noindent
+The user must assure that enough computer memory is allocated for the
+diagnostics and the output streams selected for a particular
+experiment.  This is acomplished by modifying the file
+DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
+The parameters that should be checked are called numdiags, numlists,
+numperlist, and diagSt\_size.
 
 \noindent numdiags (and diagSt\_size): \\
 \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG 
 which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\
 and has the form:\\
-common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) \\
-\noindent
-The first two-dimensions of qdiag correspond to the horizontal dimension of a given diagnostic, 
-and the third dimension of qdiag is used to identify diagnostic fields and levels combined. In 
-order to minimize the memory requirement of the model for diagnostics, the default GCM 
-executable is compiled with room for only one horizontal diagnostic array, or with
-numdiags set to Nr. In order for the User to enable more than 1 three-dimensional diagnostic,
-the size of the diagnostics common must be expanded to accomodate the desired diagnostics.
-This can be accomplished by manually changing the parameter numdiags in the
-file \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
-numdiags should be set greater than or equal to the sum of all the diagnostics activated
-for output each multiplied by the number of levels defined for that diagnostic quantity.
-For the above example, there are 4 multiple level fields, which the diagnostics menu
-(see below) indicates are defined at the GCM vertical resolution, Nr. The value of
-numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to 4*Nr, or, say 40 if $Nr=10$.
+\begin{verbatim}
+      common /diagnostics/
+     &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
+\end{verbatim}
+\noindent
+The first two-dimensions of qdiag correspond to the horizontal
+dimension of a given diagnostic, and the third dimension of qdiag is
+used to identify diagnostic fields and levels combined. In order to
+minimize the memory requirement of the model for diagnostics, the
+default GCM executable is compiled with room for only one horizontal
+diagnostic array, or with numdiags set to Nr. In order for the User to
+enable more than 1 three-dimensional diagnostic, the size of the
+diagnostics common must be expanded to accomodate the desired
+diagnostics.  This can be accomplished by manually changing the
+parameter numdiags in the file
+\filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
+numdiags should be set greater than or equal to the sum of all the
+diagnostics activated for output each multiplied by the number of
+levels defined for that diagnostic quantity.  For the above example,
+there are 4 multiple level fields, which the diagnostics menu (see
+below) indicates are defined at the GCM vertical resolution, Nr. The
+value of numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to
+4*Nr, or, say 40 if $Nr=10$.
 
 \noindent numlists and numperlist: \\
-\noindent The parameter numlists must be set greater than or equal to the number of
-separate output streams that the user specifies in the namelist file data.diagnostics.
-The parameter numperlist corresponds to the number of diagnostics requested in each
-output stream.
-
-\noindent
-In order to define and include as part of the diagnostic output any field
-that is desired for a particular experiment, two steps must be taken. The
-first is to enable the ``User Diagnostic'' in data.diagnostics. This is
-accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through 
-UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level
-fields) to the data.diagnostics namelist in one of the output streams. These 
-fields are listed in the diagnostics menu. The second step is to
-add a call to diagnostics\_fill from the subroutine in which the quantity
-desired for diagnostic output is computed. 
-
-\noindent
-In order to add a new diagnostic to the permanent set of diagnostics that the
-main model or any package contains as part of its diagnostics menu, the subroutine
-diagnostics\_add2list should be called during the initialization phase of the
-main model or package. For the main model, the call should be made from
-subroutine diagnostics\_main\_init, and for a package, the call should probably
-be made from somewhere in the packages\_init\_fixed sequence (probaby from inside
-the particular package's init\_fixed routine). A typical code sequence to set the
+\noindent The parameter numlists must be set greater than or equal to
+the number of separate output streams that the user specifies in the
+namelist file data.diagnostics.  The parameter numperlist corresponds
+to the number of diagnostics requested in each output stream.
+
+\noindent
+In order to define and include as part of the diagnostic output any
+field that is desired for a particular experiment, two steps must be
+taken. The first is to enable the ``User Diagnostic'' in
+data.diagnostics. This is accomplished by adding one of the ``User
+Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
+fields, or SDIAG1 through SDIAG10 for single level fields) to the
+data.diagnostics namelist in one of the output streams. These fields
+are listed in the diagnostics menu. The second step is to add a call
+to diagnostics\_fill from the subroutine in which the quantity desired
+for diagnostic output is computed.
+
+\noindent
+In order to add a new diagnostic to the permanent set of diagnostics
+that the main model or any package contains as part of its diagnostics
+menu, the subroutine diagnostics\_add2list should be called during the
+initialization phase of the main model or package. For the main model,
+the call should be made from subroutine diagnostics\_main\_init, and
+for a package, the call should probably be made from somewhere in the
+packages\_init\_fixed sequence (probaby from inside the particular
+package's init\_fixed routine). A typical code sequence to set the
 input arguments to diagnostics\_add2list would look like:
 
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>      diagName  = 'THETA   ' \\
-\>      diagTitle = 'Potential Temperature (degC,K)' \\
-\>      diagUnits = 'Degrees K       ' \\
-\>      diagCode  = 'SM      MR      ' \\
-\>      CALL DIAGNOSTICS\_ADD2LIST( diagNum, \\
-\>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
-\\
-\end{tabbing}
-
-\noindent If the new diagnostic quantity is associated with either a vector
-pair or a diagnostic counter, the diagCode argument must be filled with the
-proper index for the ``mate''. The output argument from diagnostics\_add2list
-that is called diagNum here contains a running total of the number of diagnostics
-defined in the code up to any point during the run. The sequence number for the
-next two diagnostics defined (the two components of the vector pair, for instance)
-will be diagNum+1 and diagNum+2. The definition of the first component of the vector
-pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2. 
-Since the subroutine increments diagNum, the definition of the second component of 
-the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for 
-this case would look like:
-
-\noindent
-\begin{tabbing}
-XXXXXXXXX\=XXXXXX\= \kill
-\>      diagName  = 'UVEL    ' \\
-\>      diagTitle = 'Zonal Velocity                ' \\
-\>      diagUnits = 'm / sec         ' \\
-\>      diagCode  = 'SM      MR      ' \\
-\>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' \\
-\>      call diagnostics\_add2list( diagNum, \\
-\>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
-\>      diagName  = 'VVEL    ' \\
-\>      diagTitle = 'Meridional Velocity           ' \\
-\>      diagUnits = 'm / sec         ' \\
-\>      diagCode  = 'SM      MR      ' \\
-\>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' \\
-\>      call diagnostics\_add2list( diagNum, \\
-\>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
-\\
-\end{tabbing}
+\begin{verbatim}
+      diagName  = 'THETA   '
+      diagTitle = 'Potential Temperature (degC,K)'
+      diagUnits = 'Degrees K       '
+      diagCode  = 'SM      MR      '
+      CALL DIAGNOSTICS\_ADD2LIST( diagNum,
+     I          diagName, diagCode, diagUnits, diagTitle, myThid )
+\end{verbatim}
+
+\noindent If the new diagnostic quantity is associated with either a
+vector pair or a diagnostic counter, the diagCode argument must be
+filled with the proper index for the ``mate''. The output argument
+from diagnostics\_add2list that is called diagNum here contains a
+running total of the number of diagnostics defined in the code up to
+any point during the run. The sequence number for the next two
+diagnostics defined (the two components of the vector pair, for
+instance) will be diagNum+1 and diagNum+2. The definition of the first
+component of the vector pair must fill the ``mate'' segment of the
+diagCode as diagnostic number diagNum+2.  Since the subroutine
+increments diagNum, the definition of the second component of the
+vector fills the ``mate'' part of diagCode with diagNum. A code
+sequence for this case would look like:
+
+\begin{verbatim}
+      diagName  = 'UVEL    ' 
+      diagTitle = 'Zonal Velocity                ' 
+      diagUnits = 'm / sec         ' 
+      diagCode  = 'SM      MR      ' 
+      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' 
+      call diagnostics\_add2list( diagNum, 
+     I          diagName, diagCode, diagUnits, diagTitle, myThid ) 
+      diagName  = 'VVEL    ' 
+      diagTitle = 'Meridional Velocity           ' 
+      diagUnits = 'm / sec         ' 
+      diagCode  = 'SM      MR      ' 
+      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' 
+      call diagnostics\_add2list( diagNum, 
+     I          diagName, diagCode, diagUnits, diagTitle, myThid ) 
+\end{verbatim}
 
 \input{part7/diagnostics-menu.tex}
 
@@ -385,9 +405,21 @@
 different MITgcm packages, follow the link to the diagnostics menu
 in the manual section describing the package:
 
-\filelink{part6/fizhi-diagnostics-menu.tex}{pkg-fizhi-fizhi-diagnostics-menu.tex}
+aim: \ref{sec:pkg:aim:diagnostics}
+exf: \ref{sec:pkg:exf:diagnostics}
+gchem: \ref{sec:pkg:gchem:diagnostics}
+generic_advdiff: \ref{sec:pkg:generic_advdiff:diagnostics}
+gridalt: \ref{sec:pkg:gridalt:diagnostics}
+gmredi: \ref{sec:pkg:gmredi:diagnostics}
+fizhi: \ref{sec:pkg:fizhi:diagnostics}
+kpp: \ref{sec:pkg:kpp:diagnostics}
+land: \ref{sec:pkg:land:diagnostics}
+mom_common: \ref{sec:pkg:mom_common:diagnostics}
+obcs: \ref{sec:pkg:obcs:diagnostics}
+thsice: \ref{sec:pkg:thsice:diagnostics}
+shap_filt: \ref{sec:pkg:shap_filt:diagnostics}
 
-\subsubsection{Dos and Donts}
+\subsection{Dos and Donts}
 
-\subsubsection{Diagnostics Reference}
+\subsection{Diagnostics Reference}
 
