--- manual/s_outp_pkgs/text/diagnostics.tex	2006/04/18 15:59:40	1.7
+++ manual/s_outp_pkgs/text/diagnostics.tex	2011/06/14 00:16:23	1.10
@@ -33,10 +33,10 @@
 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
+referred 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
+incremented separately for each model grid location.  Quantities
+referred to as ``User Diagnostics'' are included in the menu to
 facilitate defining new diagnostics for a particular experiment.
 
 \subsection{Equations}
@@ -52,156 +52,217 @@
 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
+{\bf DIAGNOSTICS\_ADDTOLIST}
+(\filelink{pkg/diagnostics/diagnostics\_addtolist.F}{pkg-diagnostics-diagnostics\_addtolist.F}):
+%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_ADDTOLIST (
+     O     diagNum,
+     I     diagName, diagCode, diagUnits, diagTitle, diagMate,
+     I     myThid )
+
+     where:
+       diagNum   = diagnostic Id number - Output from routine
+       diagName  = name of diagnostic to declare
+       diagCode  = parser code for this diagnostic
+       diagUnits = field units for this diagnostic
+       diagTitle = field description for this diagnostic
+       diagMate  = diagnostic mate number
+       myThid    = my Thread Id number
+
+\end{verbatim}
+
+
+\noindent
+{\bf DIAGNOSTICS\_FILL}
+(\filelink{pkg/diagnostics/diagnostics\_fill.F}{pkg-diagnostics-diagnostics\_fill.F}):
+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 )
+        CALL DIAGNOSTICS_FILL(
+       I             inpFld, diagName,
+       I             kLev, 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
+        inpFld   = Field to increment diagnostics array
+        diagName = diagnostic identificator name (8 characters long)
+        kLev     = Integer flag for vertical levels:
+                   > 0 (any integer): WHICH single level to increment in qdiag.
+                   0,-1 to increment "nLevs" levels in qdiag,
+                   0 : fill-in in the same order as the input array
+                   -1: fill-in in reverse order.
+        nLevs    = indicates Number of levels of the input field array
+                   (whether to fill-in all the levels (kLev<1) or just one (kLev>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
+                      AND that we have been sent a local array (with overlap regions)
+                      (local array here means that it has no bi-bj dimensions)
                  = 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
+                      AND that we have been sent a local array
+                      AND that the array has no overlap region (interior only)
+                   NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter
+        bi       = X-direction tile number - used for bibjFlg=1-3
+        bj       = Y-direction tile number - used for bibjFlg=1-3
+        myThid   =  my thread Id 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
+{\bf DIAGNOSTICS\_SCALE\_FILL}
+(\filelink{pkg/diagnostics/diagnostics\_scale\_fill.F}{pkg-diagnostics-diagnostics\_scale\_fill.F}):
+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.
 
 \begin{verbatim}
-        call diagnostics_scale_fill(
-       &         arrayin, scalefactor, power, chardiag,
-       &         levflg, nlevs, bibjflg, bi, bj, myThid )
+        CALL DIAGNOSTICS_SCALE_FILL(
+       I             inpFld, scaleFact, power, diagName,
+       I             kLev, nLevs, bibjFlg, bi, bj, myThid )
+
 
-     where all the arguments are the same as for diagnostics_fill with 
+     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
+        scaleFact   = Scaling factor to apply to the input field product
+        power       = Integer power to which to raise the input field (before scaling)
 \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:
+{\bf DIAGNOSTICS\_FRACT\_FILL}
+(\filelink{pkg/diagnostics/diagnostics\_fract\_fill.F}{pkg-diagnostics-diagnostics\_fract\_fill.F}):
+This is a specific alternative routine to DIAGNOSTICS\_[SCALE]\_FILL
+for the case of a diagnostics which is associated to
+a fraction-weight factor (referred to as the diagnostics "counter mate").
+This fraction-weight field is expected to vary during the simulation
+and is provided as argument to DIAGNOSTICS\_FRACT\_FILL
+in order to perform fraction-weighted time-average diagnostics.
+Note that the fraction-weight field has to correspond to the diagnostics
+counter-mate which has to be filled independently with a call to DIAGNOSTICS\_FILL.
 
 \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.
+        CALL DIAGNOSTICS_FRACT_FILL(
+       I             inpFld, fractFld, scaleFact, power, diagName,
+       I             kLev, nLevs, bibjFlg, bi, bj, myThid )
 
-\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
+     where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with
+     the addition of:
+        fractFld    = fraction used for weighted average diagnostics
 \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:
+{\bf DIAGNOSTICS\_IS\_ON}: Function call to inquire whether a
+diagnostic is active and should be incremented. Useful when there is a
+computation that must be done locally before a call to
+DIAGNOSTICS\_FILL. The call sequence:
 
 \begin{verbatim}
-       call diagnostics_add2list( diagNum,diagName, diagCode,
-                                  diagUnits, diagTitle, myThid )
+        flag = DIAGNOSTICS_IS_ON( diagName, 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
+        diagName = diagnostic identificator name (8 characters long)
+        myThid   = my thread Id 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:
+{\bf DIAGNOSTICS\_COUNT}
+(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
+This subroutine increments the diagnostics counter only.
+In general, the diagnostics counter is incremented at the same time as the
+diagnostics is filled, by calling DIAGNOSTICS\_FILL.
+However, there are few cases where the counter is not incremented
+during the filling (e.g., when the filling is done level per level but
+level 1 is skipped) and needs to be done explicitly with a call to subroutine
+DIAGNOSTICS\_COUNT. The call sequence is:
 
 \begin{verbatim}
-        call diagnostics_clrdiag (jpoint, ipoint, myThid)
+        CALL DIAGNOSTICS_COUNT(
+       I                        diagName, bi, bj, 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}.
+        diagName  = name of diagnostic to increment the counter
+        bi        = X-direction tile number, or 0 if called outside bi,bj loops
+        bj        = Y-direction tile number, or 0 if called outside bi,bj loops
+        myThid    = my thread Id number
+
+\end{verbatim}
+
+%\noindent
+%{\bf DIAGNOSTICS\_GET\_POINTERS}
+%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
+%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(
+%     I                       diagName, listId,
+%     O                       ndId, ip,
+%     I                       myThid )
+%
+%     where:
+%        diagName = diagnostic identificator name (8 characters long)
+%        listId   = list number that specifies the output frequency
+%        ndId     = diagnostics  Id number (in available diagnostics list)
+%        ip       = diagnostics  pointer to storage array
+%        myThid   = my Thread Id number
+%\end{verbatim}
+%
+%\noindent
+%{\bf GETDIAG}
+%%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
+%This subroutine retrieves the value of a model diagnostic.
+%This routine is particularly 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(
+%       I             levreal, undef,
+%       O             qtmp,
+%       I             ndId, mate, ip, im, 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
+%        ndId    = diagnostics  Id number (in available diagnostics list)
+%        mate    = counter diagnostic number if any ; 0 otherwise
+%        ip      = pointer to storage array location for diag.
+%        im      = pointer to storage array location for mate
+%        bi      = X-direction tile number
+%        bj      = Y-direction tile number
+%        myThid  = my thread Id number
+%\end{verbatim}
+%
+%\noindent
+%{\bf DIAGNOSTICS\_CLRDIAG}
+%(\filelink{pkg/diagnostics/diagnostics\_clear.F}{pkg-diagnostics-diagnostics\_clear.F}):
+%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 ( ipt, nLev, myThid )
+%
+%     where:
+%        ipt    :: diagnostic pointer to storage array
+%        nLev   :: number of levels (in storage array) to reset
+%        myThid :: my Thread Id number
+%\end{verbatim}
 
 \begin{table}
 \caption{Diagnostic Parsing Array}
@@ -209,77 +270,124 @@
 \begin{center}
 \begin{tabular}{ |c|c|l| }
 \hline
-\multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\ 
+\multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\
 \hline
 \hline
 Array & Value & Description \\
 \hline
-  parse(1)   & $\rightarrow$ S &  Scalar Diagnostic                 \\ 
-             & $\rightarrow$ U &  U-vector component Diagnostic     \\ 
-             & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline
-  parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\ 
-             & $\rightarrow$ V &  C-Grid V-Point                    \\ 
-             & $\rightarrow$ M &  C-Grid Mass Point                 \\ 
-             & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
-  parse(3)   & $\rightarrow$ R &  Not Currently in Use              \\ \hline
-  parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
-  parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\
-             & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
-  parse(6-8) & $\rightarrow$ C &  3-digit integer corresponding to  \\
-             &                 &  vector or counter component mate  \\ \hline
+ parse(1)  & $\rightarrow$ S &  Scalar Diagnostic                 \\
+           & $\rightarrow$ U &  U-vector component Diagnostic     \\
+           & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline
+ parse(2)  & $\rightarrow$ U &  C-Grid U-Point                    \\
+           & $\rightarrow$ V &  C-Grid V-Point                    \\
+           & $\rightarrow$ M &  C-Grid Mass Point                 \\
+           & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
+ parse(3)  & $\rightarrow$   &  Used for Level Integrated output: cumulate levels \\
+           & $\rightarrow$ r &  same but cumulate product by model level thickness \\
+           & $\rightarrow$ R &  same but cumulate product by hFac \& level thickness \\ \hline
+ parse(4)  & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
+ parse(5)  & $\rightarrow$ C &  with Counter array                \\
+           & $\rightarrow$ P &  post-processed (not filled up) from other diags \\
+           & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
+ parse(6-8)&                 &  retired, formerly: 3-digit mate number \\ \hline
+ parse(9)  & $\rightarrow$ U &  model-level plus 1/2  \\
+           & $\rightarrow$ M &  model-level middle  \\
+           & $\rightarrow$ L &  model-level minus 1/2  \\ \hline
+ parse(10) & $\rightarrow$ 0 &  levels = 0  \\
+           & $\rightarrow$ 1 &  levels = 1  \\
+           & $\rightarrow$ R &  levels = Nr  \\
+           & $\rightarrow$ L &  levels = MAX(Nr,NrPhys)  \\
+           & $\rightarrow$ M &  levels = MAX(Nr,NrPhys) - 1  \\
+           & $\rightarrow$ G &  levels = Ground\_level Number \\
+           & $\rightarrow$ I &  levels = sea-Ice\_level Number \\
+           & $\rightarrow$ X &  free levels option (need to be set explicitly)\\ \hline
 \end{tabular}
 \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
 \end{center}
 \end{table}
 
+\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*16 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}.
 
 \noindent
 As an example, consider a diagnostic whose associated GDIAG parameter is equal
-to ``UU  002''.  From GDIAG we can determine that this diagnostic is a 
-U-vector component located at the C-grid U-point.
-Its corresponding V-component diagnostic is located in Diagnostic \# 002.
+to ``UUR\hspace{5mm}MR''.  From GDIAG we can determine that this diagnostic is a
+U-vector component located at the C-grid U-point, model mid-level (M)
+with Nr levels (last R).
 
 \noindent
 In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,
-C-grid location, etc.) defined internally.  The Output routines use this information 
-in order to determine what type of transformations need to be performed.  Any 
+C-grid location, etc.) defined internally.  The Output routines use this information
+in order to determine what type of transformations need to be performed.  Any
 interpolations are done at the time of output rather than during each model step.
-In this way the User has flexibility in determining the type of gridded data which 
+In this way the User has flexibility in determining the type of gridded data which
 is output.
 
+%\newpage
 \subsection{Usage Notes}
 \label{sec:diagnostics:usersguide}
 
+\subsubsection{Using available diagnostics}
 \noindent
-To use the diagnostics package, other than enabling it in packages.conf
-and turning the usediagnostics flag in data.pkg to .TRUE., there are two
+To use the diagnostics package, other than enabling it in {\tt packages.conf}
+and turning the {\tt useDiagnostics} flag in {\tt data.pkg} to .TRUE., there are two
 further steps the user must take to enable the diagnostics package for
 output of quantities that are already defined in the GCM under an experiment's
-configuration of packages.  A namelist must be supplied in the run directory 
-called data.diagnostics, and the file DIAGNOSTICS\_SIZE.h must be included in the 
-code directory.  The steps for defining a new (permanent or experiment-specific 
-temporary) diagnostic quantity will be outlined later. 
-
-\noindent The namelist will activate a user-defined list of diagnostics quantities 
-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:
+configuration of packages.
+A parameter file {\tt data.diagnostics} must be supplied in the run directory,
+and the file DIAGNOSTICS\_SIZE.h must be included in the
+code directory.  The steps for defining a new (permanent or experiment-specific
+temporary) diagnostic quantity will be outlined later.
+
+\noindent The namelist in parameter file {\tt data.diagnostics} will activate
+a user-defined list of diagnostics quantities 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 {\tt data.diagnostics} namelist file:
 
 \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 
+#--------------------
+#  dumpAtLast (logical): always write output at the end of simulation (default=F)
+#  diag_mnc   (logical): write to NetCDF files (default=useMNC)
+#--for each output-stream:
+#  fileName(n) : prefix of the output file name (max 80c long) for outp.stream n
+#  frequency(n):< 0 : write snap-shot output every |frequency| seconds
+#               > 0 : write time-average output every frequency seconds
+#  timePhase(n)     : write at time = timePhase + multiple of |frequency|
+#    averagingFreq  : frequency (in s) for periodic averaging interval
+#    averagingPhase : phase     (in s) for periodic averaging interval
+#    repeatCycle    : number of averaging intervals in 1 cycle
+#  levels(:,n) : list of levels to write to file (Notes: declared as REAL)
+#                when this entry is missing, select all common levels of this list
+#  fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n
+#                (see "available_diagnostics.log" file for the full list of diags)
+#  missing_value(n) : missing value for real-type fields in output file "n"
+#  fileFlags(n)     : specific code (8c string) for output file "n"
+#--------------------
+ &DIAGNOSTICS_LIST
+  fields(1:2,1) = 'UVEL    ','VVEL    ',
+   levels(1:5,1) = 1.,2.,3.,4.,5.,
+   filename(1) = 'diagout1',
+  frequency(1) = 86400.,
+  fields(1:3,2) = 'THETA   ','SALT    ',
+   filename(2) = 'diagout2',
+  fileflags(2) = ' P1     ',
+  frequency(2) = 3600.,
+ &
+
+ &DIAG_STATIS_PARMS
+ &
 \end{verbatim}
 
 \noindent
@@ -290,24 +398,25 @@
 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.
+with all levels, 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
+experiment.  This is accomplished 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.
+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}.\\
+\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:\\
 \begin{verbatim}
-      common /diagnostics/
-     &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
+      _RL  qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy)
+      _RL  qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy)
+      COMMON / DIAG_STORE_R / qdiag, qSdiag
 \end{verbatim}
 \noindent
 The first two-dimensions of qdiag correspond to the horizontal
@@ -315,63 +424,66 @@
 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
+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 common must be expanded to accommodate the desired
 diagnostics.  This can be accomplished by manually changing the
-parameter numdiags in the file
+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
+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
+value of numDiags 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
+\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.
+namelist file data.diagnostics.  The parameter numperList corresponds
+to the maximum number of diagnostics requested per output streams.
+
+\subsubsection{Adding new diagnostics to the code}
 
 \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
+{\tt 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
+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
+menu, the subroutine DIAGNOSTICS\_ADDTOLIST 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:
+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 (probably
+from inside the particular package's init\_fixed routine.
+A typical code sequence to set the
+input arguments to DIAGNOSTICS\_ADDTOLIST would look like:
 
 \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 )
+      diagName  = 'RHOAnoma'
+      diagTitle = 'Density Anomaly (=Rho-rhoConst)'
+      diagUnits = 'kg/m^3          '
+      diagCode  = 'SMR     MR      '
+      CALL DIAGNOSTICS\_ADDTOLIST( diagNum,
+     I          diagName, diagCode, diagUnits, diagTitle, 0, 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
+vector pair or a diagnostic counter, the diagMate argument must be
+provided with the proper index corresponding to the ``mate''.
+The output argument from DIAGNOSTICS\_ADDTOLIST 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
@@ -382,23 +494,24 @@
 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 ) 
+      diagName  = 'UVEL    '
+      diagTitle = 'Zonal Component of Velocity (m/s)'
+      diagUnits = 'm/s             '
+      diagCode  = 'UUR     MR      '
+      diagMate  = diagNum + 2
+      CALL DIAGNOSTICS_ADDTOLIST( diagNum,
+     I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
+
+      diagName  = 'VVEL    '
+      diagTitle = 'Meridional Component of Velocity (m/s)'
+      diagUnits = 'm/s             '
+      diagCode  = 'VVR     MR      '
+      diagMate  = diagNum
+      CALL DIAGNOSTICS_ADDTOLIST( diagNum,
+     I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
 \end{verbatim}
 
-\input{part7/diagnostics-menu.tex}
+\input{s_outp_pkgs/text/diagnostics-menu.tex}
 
 \newpage
 \noindent For a list of the diagnostic fields available in the
