--- manual/s_phys_pkgs/diagnostics.tex	2005/07/14 19:18:01	1.9
+++ manual/s_phys_pkgs/diagnostics.tex	2005/07/15 18:58:21	1.11
@@ -20,12 +20,14 @@
 \ref{sec:diagnostics:usersguide} of this document.
 
 \noindent
-The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within 
-the GCM. 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 
+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.
@@ -37,117 +39,87 @@
 \label{sec:diagnostics:diagover}
 
 \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{table}
-\caption{Diagnostic Parsing Array}
-\label{tab:diagnostics:gdiag.tabl}
-\begin{center}
-\begin{tabular}{ |c|c|l| }
-\hline
-\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
-\end{tabular}
-\addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
-\end{center}
-\end{table}
-
-
-\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.
-
-
-\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 
-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 
-is output.
-
-
-\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 fill\_diagnostics}:  This routine will increment the specified diagnostic
-quantity with a field sent through the argument list.
-
+{\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 fill\_diagnostics (myThid, chardiag, levflg, nlevs, \\
-                bibjflg, bi, bj, arrayin) \\
+\>        call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\
+\>              bibjflg, bi, bj, myThid) \\
 \\
-where \>  myThid   \>= Current Process(or) \\
+where \>  arrayin  \>= Field to increment diagnostics array \\
       \>  chardiag \>= Character *8 expression for diag to fill \\
       \>  levflg   \>= Integer flag for vertical levels: \\
-      \>           \> 0 indicates multiple levels incremented in qdiag \\
-      \>           \> non-0 (any integer) - WHICH single level to increment. \\
-      \>           \> negative integer - the input data array is single-leveled \\
-      \>           \> positive integer - the input data array is multi-leveled \\
-      \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg <> 0) \\
-      \>           \> positive: fill in "nlevs" levels in the same order as \\
-      \>           \> the input array \\
-      \>           \> negative: fill in -nlevs levels in reverse order. \\
+      \>           \>= 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 \\
-      \>           \> 3 indicates that the bi-bj loop is done OUTSIDE \\
+      \>           \>= 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 \\
-      \>  arrayin  \>= Field to increment diagnostics array \\
+      \>  myThid   \>= Current Thread number \\
 \end{tabbing}
 
+\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
-{\bf setdiag}:  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
-between the user and the desired diagnostic.  The diagnostic is referenced by its diagnostic
-number from the menu, and its calling sequence is given by:
+\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 setdiag (num) \\
+\> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid )
 \\
-where \>  num   \>= Diagnostic number from menu \\
+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
@@ -161,344 +133,674 @@
 \noindent
 \begin{tabbing}
 XXXXXXXXX\=XXXXXX\= \kill
-\>        call getdiag (lev,num,qtmp,undef) \\
+\>        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\
 \\
-where \>  lev   \>= Model Level at which the diagnostic is desired \\
-      \>  num   \>= Diagnostic number from menu \\
-      \>  qtmp  \>= Time-Averaged Diagnostic Output \\
-      \>  undef \>= Fill value to be used when diagnostic is undefined \\
+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 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\_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 clrdiag (num) \\
+\>        call diagnostics\_add2list( diagNum,diagName, diagCode, \\
+\>        diagUnits, diagTitle, myThid ) \\
 \\
-where \>  num   \>= Diagnostic number from menu \\
+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 zapdiag}:  This entry into subroutine SETDIAG disables model diagnostics, meaning 
-that the diagnostic is no longer available to the user.  The memory previously allocated 
-to the diagnostic is released when ZAPDIAG is invoked.  The calling sequence is given by:
+{\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 zapdiag (NUM) \\
+\>        call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\
 \\
-where \>  num   \>= Diagnostic number from menu \\
+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{table}
+\caption{Diagnostic Parsing Array}
+\label{tab:diagnostics:gdiag.tabl}
+\begin{center}
+\begin{tabular}{ |c|c|l| }
+\hline
+\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
+\end{tabular}
+\addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
+\end{center}
+\end{table}
 
-\subsection{Usage Notes}
-\label{sec:diagnostics:usersguide}
 
 \noindent
-We begin this section with a discussion on the manner in which computer 
-memory is allocated for diagnostics. 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)
+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.
 
 \noindent
-where numdiags is an Integer variable which should be set equal to the number of 
-enabled diagnostics, and qdiag is a three-dimensional array.  The first two-dimensions 
-of qdiag correspond to the horizontal dimension of a given diagnostic, while 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 1. In order for the User to enable more than 1 two-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.
-This is illustrated in the example below:
+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 
+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 
+is output.
+
+\subsection{Usage Notes}
+\label{sec:diagnostics:usersguide}
 
 \noindent
 To use the diagnostics package, other than enabling it in packages.conf
-and turning the usediagnostics flag in data.pkg to .TRUE., a namelist
-must be supplied in the run directory called data.diagnostics. The namelist
-will activate a user-defined list of diagnostics quantities to be computed,
-specify the frequency of output, the number of levels, and the name of
-up to 10 separate output files. A sample data.diagnostics namelist file:
+and turning the usediagnostics flag in 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:
 
 \noindent
 $\#$ Diagnostic Package Choices \\
  $\&$diagnostics\_list \\
-  frequency(1) = 10, \ \\
-   levels(1,1) = 1.,2.,3.,4.,5., \ \\
-   fields(1,1) = 'UVEL    ','VVEL    ', \ \\
-   filename(1) = 'diagout1', \ \\
-  frequency(2) = 100, \ \\
+  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) = 'THETA   ','SALT    ', \ \\
-   filename(2) = 'diagout2', \ \\
+   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 10 time steps
-(frequency is 10), they will write fields which are multiple-level 
-fields and output levels 1-5. The names of diagnostics quantities are 
+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 100 time steps,
-they include fields which are multiple-level fields, levels output are 1-5,
+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$.
+
+\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 setting one of the fields slots to either UDIAG1 through 
+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. These are listed in the diagnostics menu. The second step is to
-add a call to fill\_diagnostics from the subroutine in which the quantity
+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}
+
+
 \newpage
 
 \subsubsection{GCM Diagnostic Menu}
 \label{sec:diagnostics:menu}
 
-\begin{tabular}{lllll}
+\begin{tabular}{llll}
 \hline\hline
-N & NAME & UNITS & LEVELS & DESCRIPTION \\
+ NAME & UNITS & LEVELS & DESCRIPTION \\
 \hline
 
 &\\
-84 & SDIAG1   &             &    1  
+ SDIAG1   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-1} 
          \end{minipage}\\
-85 & SDIAG2   &             &    1  
+ SDIAG2   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-2} 
          \end{minipage}\\
-86 & UDIAG1   &             &    Nrphys
+ UDIAG1   &             &    Nrphys
          &\begin{minipage}[t]{3in}
           {User-Defined Upper-Air Diagnostic-1} 
          \end{minipage}\\
-87 & UDIAG2   &             &    Nrphys
+ UDIAG2   &             &    Nrphys
          &\begin{minipage}[t]{3in}
           {User-Defined Upper-Air Diagnostic-2} 
          \end{minipage}\\
-124& SDIAG3   &             &    1  
+ SDIAG3   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-3} 
          \end{minipage}\\
-125& SDIAG4   &             &    1  
+ SDIAG4   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-4} 
          \end{minipage}\\
-126& SDIAG5   &             &    1  
+ SDIAG5   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-5} 
          \end{minipage}\\
-127& SDIAG6   &             &    1  
+ SDIAG6   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-6} 
          \end{minipage}\\
-128& SDIAG7   &             &    1  
+ SDIAG7   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-7} 
          \end{minipage}\\
-129& SDIAG8   &             &    1  
+ SDIAG8   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-8} 
          \end{minipage}\\
-130& SDIAG9   &             &    1  
+ SDIAG9   &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-9} 
          \end{minipage}\\
-131& SDIAG10  &             &    1  
+ SDIAG10  &             &    1  
          &\begin{minipage}[t]{3in}
           {User-Defined Surface Diagnostic-1-} 
          \end{minipage}\\
-132& UDIAG3   &             &    Nrphys  
+ UDIAG3   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-3} 
          \end{minipage}\\
-133& UDIAG4   &             &    Nrphys  
+ UDIAG4   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-4} 
          \end{minipage}\\
-134& UDIAG5   &             &    Nrphys  
+ UDIAG5   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-5} 
          \end{minipage}\\
-135& UDIAG6   &             &    Nrphys  
+ UDIAG6   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-6} 
          \end{minipage}\\
-136& UDIAG7   &             &    Nrphys  
+ UDIAG7   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-7} 
          \end{minipage}\\
-137& UDIAG8   &             &    Nrphys  
+ UDIAG8   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-8} 
          \end{minipage}\\
-138& UDIAG9   &             &    Nrphys  
+ UDIAG9   &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-9} 
          \end{minipage}\\
-139& UDIAG10  &             &    Nrphys  
+ UDIAG10  &             &    Nrphys  
          &\begin{minipage}[t]{3in}
           {User-Defined Multi-Level Diagnostic-10} 
          \end{minipage}\\
+ SDIAGC   &             &    1  
+         &\begin{minipage}[t]{3in}
+          {User-Defined Counted Surface Diagnostic} 
+         \end{minipage}\\
+ SDIAGCC  &             &    1  
+         &\begin{minipage}[t]{3in}
+          {User-Defined Counted Surface Diagnostic Counter} 
+         \end{minipage}\\
+ ETAN     & $(hPa,m)$ &    1
+         &\begin{minipage}[t]{3in}
+          {Perturbation of Surface (pressure, height)} 
+         \end{minipage}\\
+ ETANSQ   & $(hPa^2,m^2)$ & 1
+         &\begin{minipage}[t]{3in}
+          {Square of Perturbation of Surface (pressure, height)} 
+         \end{minipage}\\
+ DETADT2  & ${r-unit}^2/s^2$ & 1
+         &\begin{minipage}[t]{3in}
+          {Square of Eta (Surf.P,SSH) Tendency} 
+         \end{minipage}\\
+ THETA    & $deg K$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Potential Temperature} 
+         \end{minipage}\\
+ SST      & $deg K$ & 1
+         &\begin{minipage}[t]{3in}
+          {Sea Surface Temperature} 
+         \end{minipage}\\
+ SALT     & $g/kg$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Salt (or Water Vapor Mixing Ratio)} 
+         \end{minipage}\\
+ SSS      & $g/kg$ & 1
+         &\begin{minipage}[t]{3in}
+          {Sea Surface Salinity} 
+         \end{minipage}\\
+ SALTanom & $g/kg$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Salt anomaly (=SALT-35)} 
+         \end{minipage}\\
 \end{tabular}
 \vspace{1.5in}
 \vfill
 
 \newpage
 \vspace*{\fill}
-\begin{tabular}{lllll}
+\begin{tabular}{llll}
 \hline\hline
-N & NAME & UNITS & LEVELS & DESCRIPTION \\
+ NAME & UNITS & LEVELS & DESCRIPTION \\
 \hline
 
 &\\
-238& ETAN     & $(hPa,m)$ &    1
-         &\begin{minipage}[t]{3in}
-          {Perturbation of Surface (pressure, height)} 
-         \end{minipage}\\
-239& ETANSQ   & $(hPa^2,m^2)$ & 1
-         &\begin{minipage}[t]{3in}
-          {Square of Perturbation of Surface (pressure, height)} 
-         \end{minipage}\\
-240& THETA    & $deg K$ & Nr
+ UVEL     & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
-          {Potential Temperature} 
+          {U-Velocity} 
          \end{minipage}\\
-241& SALT     & $g/kg$ & Nr
+ VVEL     & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
-          {Salt (or Water Vapor Mixing Ratio)} 
+          {V-Velocity} 
          \end{minipage}\\
-242& UVEL     & $m/sec$ & Nr
+ UVEL\_k2  & $m/sec$ & 1
          &\begin{minipage}[t]{3in}
           {U-Velocity} 
          \end{minipage}\\
-243& VVEL     & $m/sec$ & Nr
+ VVEL\_k2  & $m/sec$ & 1
          &\begin{minipage}[t]{3in}
           {V-Velocity} 
          \end{minipage}\\
-244& WVEL     & $m/sec$ & Nr
+ WVEL     & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical-Velocity} 
          \end{minipage}\\
-245& THETASQ  & $deg^2$ & Nr
+ THETASQ  & $deg^2$ & Nr
          &\begin{minipage}[t]{3in}
           {Square of Potential Temperature} 
          \end{minipage}\\
-246& SALTSQ   & $g^2/{kg}^2$ & Nr
+ SALTSQ   & $g^2/{kg}^2$ & Nr
          &\begin{minipage}[t]{3in}
           {Square of Salt (or Water Vapor Mixing Ratio)} 
          \end{minipage}\\
-247& UVELSQ   & $m^2/sec^2$ & Nr
+ SALTSQan & $g^2/{kg}^2$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Square of Salt anomaly (=SALT-35)} 
+         \end{minipage}\\
+ UVELSQ   & $m^2/sec^2$ & Nr
          &\begin{minipage}[t]{3in}
           {Square of U-Velocity} 
          \end{minipage}\\
-248& VVELSQ   & $m^2/sec^2$ & Nr
+ VVELSQ   & $m^2/sec^2$ & Nr
          &\begin{minipage}[t]{3in}
           {Square of V-Velocity} 
          \end{minipage}\\
-249& WVELSQ   & $m^2/sec^2$ & Nr
+ WVELSQ   & $m^2/sec^2$ & Nr
          &\begin{minipage}[t]{3in}
           {Square of Vertical-Velocity} 
          \end{minipage}\\
-250& UVELVVEL & $m^2/sec^2$ & Nr
+ UV\_VEL\_C & $m^2/sec^2$ & Nr
          &\begin{minipage}[t]{3in}
-          {Meridional Transport of Zonal Momentum} 
+          {Meridional Transport of Zonal Momentum (cell center)} 
          \end{minipage}\\
-251& UVELMASS & $m/sec$ & Nr
+ UV\_VEL\_Z & $m^2/sec^2$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Meridional Transport of Zonal Momentum (corner)} 
+         \end{minipage}\\
+ WU\_VEL   & $m^2/sec^2$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Vertical Transport of Zonal Momentum (cell center)} 
+         \end{minipage}\\
+ WV\_VEL   & $m^2/sec^2$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Vertical Transport of Meridional Momentum (cell center)} 
+         \end{minipage}\\
+ UVELMASS & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Zonal Mass-Weighted Component of Velocity} 
          \end{minipage}\\
-252& VVELMASS & $m/sec$ & Nr
+ VVELMASS & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Meridional Mass-Weighted Component of Velocity} 
          \end{minipage}\\
-253& WVELMASS & $m/sec$ & Nr
+ WVELMASS & $m/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical Mass-Weighted Component of Velocity} 
          \end{minipage}\\
-254& UTHMASS  & $m-deg/sec$ & Nr
+ UTHMASS  & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Zonal Mass-Weight Transp of Pot Temp} 
          \end{minipage}\\
-255& VTHMASS  & $m-deg/sec$ & Nr
+ VTHMASS  & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Meridional Mass-Weight Transp of Pot Temp} 
          \end{minipage}\\
-256& WTHMASS  & $m-deg/sec$ & Nr
+ WTHMASS  & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical Mass-Weight Transp of Pot Temp} 
          \end{minipage}\\
-257& USLTMASS & $m-kg/sec-kg$ & Nr
+ USLTMASS & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Zonal Mass-Weight Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-258& VSLTMASS & $m-kg/sec-kg$ & Nr
+ VSLTMASS & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Meridional Mass-Weight Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-259& WSLTMASS & $m-kg/sec-kg$ & Nr
+ WSLTMASS & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical Mass-Weight Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-260& UVELTH   & $m-deg/sec$ & Nr
+ UVELTH   & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Zonal Transp of Pot Temp} 
          \end{minipage}\\
-261& VVELTH   & $m-deg/sec$ & Nr
+ VVELTH   & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Meridional Transp of Pot Temp} 
          \end{minipage}\\
-262& WVELTH   & $m-deg/sec$ & Nr
+ WVELTH   & $m-deg/sec$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical Transp of Pot Temp} 
          \end{minipage}\\
-263& UVELSLT  & $m-kg/sec-kg$ & Nr
+ UVELSLT  & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Zonal Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-264& VVELSLT  & $m-kg/sec-kg$ & Nr
+ VVELSLT  & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Meridional Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-265& WVELSLT  & $m-kg/sec-kg$ & Nr
+ WVELSLT  & $m-kg/sec-kg$ & Nr
          &\begin{minipage}[t]{3in}
           {Vertical Transp of Salt (or W.Vap Mix Rat.)} 
          \end{minipage}\\
-275& WSLTMASS & $m-kg/sec-kg$ & Nr
+\end{tabular}
+\vspace{1.5in}
+\vfill
+
+\newpage
+\vspace*{\fill}
+\begin{tabular}{llll}
+\hline\hline
+ NAME & UNITS & LEVELS & DESCRIPTION \\
+\hline
+
+&\\
+ RHOAnoma & $kg/m^3  $  &  Nr  
          &\begin{minipage}[t]{3in}
-          {Vertical Mass-Weight Transp of Salt (or W.Vap Mix Rat.)} 
+          {Density Anomaly (=Rho-rhoConst)}
+         \end{minipage}\\
+ RHOANOSQ & $kg^2/m^6$  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Square of Density Anomaly (=(Rho-rhoConst))}
+         \end{minipage}\\
+ URHOMASS & $kg/m^2/s$  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Zonal Transport of Density}
+         \end{minipage}\\
+ VRHOMASS & $kg/m^2/s$  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Meridional Transport of Density}
+         \end{minipage}\\
+ WRHOMASS & $kg/m^2/s$  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Vertical Transport of Potential Density}
+         \end{minipage}\\
+ PHIHYD   & $m^2/s^2 $  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Hydrostatic (ocean) pressure / (atmos) geo-Potential}
+         \end{minipage}\\
+ PHIHYDSQ & $m^4/s^4 $  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Square of Hyd. (ocean) press / (atmos) geoPotential}
+         \end{minipage}\\
+ PHIBOT   & $m^2/s^2 $  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {ocean bottom pressure / top. atmos geo-Potential}
+         \end{minipage}\\
+ PHIBOTSQ & $m^4/s^4 $  &  Nr  
+         &\begin{minipage}[t]{3in}
+          {Square of ocean bottom pressure / top. geo-Potential}
+         \end{minipage}\\
+ DRHODR   & $kg/m^3/{r-unit}$ & Nr
+         &\begin{minipage}[t]{3in}
+          {Stratification: d.Sigma/dr} 
          \end{minipage}\\
-298& VISCA4   & $m^4/sec$ & 1
+ VISCA4   & $m^4/sec$ & 1
          &\begin{minipage}[t]{3in}
           {Biharmonic Viscosity Coefficient} 
          \end{minipage}\\
-299& VISCAH   & $m^2/sec$ & 1
+ VISCAH   & $m^2/sec$ & 1
          &\begin{minipage}[t]{3in}
           {Harmonic Viscosity Coefficient} 
          \end{minipage}\\
-300& DRHODR   & $kg/m^3/{r-unit}$ & Nr
+ TAUX     & $N/m^2        $ & 1 
          &\begin{minipage}[t]{3in}
-          {Stratification: d.Sigma/dr} 
+          {zonal surface wind stress, >0 increases uVel}
          \end{minipage}\\
-301& DETADT2  & ${r-unit}^2/s^2$ & 1
+ TAUY     & $N/m^2        $ & 1 
          &\begin{minipage}[t]{3in}
-          {Square of Eta (Surf.P,SSH) Tendency} 
+          {meridional surf. wind stress, >0 increases vVel}
+         \end{minipage}\\
+ TFLUX    & $W/m^2        $ & 1 
+         &\begin{minipage}[t]{3in}
+          {net surface heat flux, >0 increases theta}
+         \end{minipage}\\
+ TRELAX   & $W/m^2        $ & 1 
+         &\begin{minipage}[t]{3in}
+          {surface temperature relaxation, >0 increases theta}
+         \end{minipage}\\
+ TICE     & $W/m^2        $ & 1 
+         &\begin{minipage}[t]{3in}
+          {heat from melt/freeze of sea-ice, >0 increases theta}
+         \end{minipage}\\
+ SFLUX    & $g/m^2/s      $ & 1 
+         &\begin{minipage}[t]{3in}
+          {net surface salt flux, >0 increases salt}
+         \end{minipage}\\
+ SRELAX   & $g/m^2/s      $ & 1 
+         &\begin{minipage}[t]{3in}
+          {surface salinity relaxation, >0 increases salt}
+         \end{minipage}\\
+ PRESSURE & $Pa           $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Atmospheric Pressure (Pa)}
+         \end{minipage}\\
+ ADVr\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical   Advective Flux of Pot.Temperature}
+         \end{minipage}\\
+ ADVx\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Zonal      Advective Flux of Pot.Temperature}
+         \end{minipage}\\
+ ADVy\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Meridional Advective Flux of Pot.Temperature}
+         \end{minipage}\\
+ DFrE\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical Diffusive Flux of Pot.Temperature (Explicit part)}
+         \end{minipage}\\
+ DIFx\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Zonal      Diffusive Flux of Pot.Temperature}
+         \end{minipage}\\
+ DIFy\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Meridional Diffusive Flux of Pot.Temperature}
+         \end{minipage}\\
+ DFrI\_TH  & $K.Pa.m^2/s   $ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical Diffusive Flux of Pot.Temperature (Implicit part)}
+         \end{minipage}\\
+ ADVr\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical   Advective Flux of Water-Vapor}
+         \end{minipage}\\
+ ADVx\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Zonal      Advective Flux of Water-Vapor}
+         \end{minipage}\\
+ ADVy\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Meridional Advective Flux of Water-Vapor}
+         \end{minipage}\\
+\end{tabular}
+\vspace{1.5in}
+\vfill
+
+\newpage
+\vspace*{\fill}
+\begin{tabular}{llll}
+\hline\hline
+ NAME & UNITS & LEVELS & DESCRIPTION \\
+\hline
+
+&\\
+ DFrE\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical Diffusive Flux of Water-Vapor (Explicit part)}
+         \end{minipage}\\
+ DIFx\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Zonal      Diffusive Flux of Water-Vapor}
+         \end{minipage}\\
+ DIFy\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Meridional Diffusive Flux of Water-Vapor}
+         \end{minipage}\\
+ DFrI\_SLT & $g/kg.Pa.m^2/s$ & Nr 
+         &\begin{minipage}[t]{3in}
+          {Vertical Diffusive Flux of Water-Vapor (Implicit part)}
          \end{minipage}\\
 \end{tabular}
 \vspace{1.5in}
