--- manual/s_phys_pkgs/diagnostics.tex	2004/01/28 21:00:10	1.1
+++ manual/s_phys_pkgs/diagnostics.tex	2004/10/18 19:43:56	1.7
@@ -1,15 +1,34 @@
-\section{Diagnostics-Flexible model infrastructure for diagnostic (instananeous or time averaged) output}
+\section{Diagnostics--A Flexible Infrastructure}
+\label{sec:pkg:diagnostics}
+\begin{rawhtml}
+<!-- CMIREDIR:package_diagnostics: -->
+\end{rawhtml}
 
 \subsection{Introduction}
 
-This section of the documentation describes the Diagnostics Utilities available within the GCM.  
-In addition to
-a description on how to set and extract diagnostic quantities, this document also provides a
-comprehensive list of all available diagnostic quantities and a short description of how they are
-computed.  It should be noted that this document is not intended to be a complete documentation
-of the various packages used in the GCM, and the reader should
-refer to original publications for further insight.
-
+\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 
+\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 
+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.
 
 \subsection{Equations}
 Not relevant.
@@ -17,35 +36,16 @@
 \subsection{Key Subroutines and Parameters}
 \label{sec:diagnostics:diagover}
 
-A large selection of model diagnostics is available in the GCM.  At the time of
-this writing there are 92 different diagnostic quantities which can be enabled for an
-experiment.  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}).
-The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within the
-GCM.  Diagnostics are internally referred to by their associated number in the Diagnostic
-Menu.  Once a diagnostic is enabled, the GCM will continually increment an array
-specifically allocated for that diagnostic whenever the associated process for the diagnostic is
-computed.  Separate arrays are used both for the diagnostic quantity and its diagnostic counter
-which records how many times each diagnostic quantity has been computed.  In addition 
-special diagnostics, called
-``Counter Diagnostics'', records the frequency of diagnostic updates separately for each 
-model grid location.
-
-The diagnostics are computed at various times and places within the GCM.  
-Some diagnostics are computed on the geophysical A-grid (such as 
-those within the Physics routines), while others are computed on the C-grid 
-(those computed during the dynamics time-stepping).  Some diagnostics are 
-scalars, while others are vectors.  Each of these possibilities requires
-separate tasks for A-grid to C-grid transformations and coordinate transformations.  Due
-to this complexity, and since the specific diagnostics enabled are User determined at the
-time of the run, 
-a diagnostic parameter has been developed and implemented into the GCM, defined as GDIAG,
-which contains information concerning various grid attributes of each diagnostic.  The GDIAG
-array 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}.
+\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}
@@ -64,9 +64,8 @@
   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 Point            \\ \hline
-  parse(3)   & $\rightarrow$ R &  Computed on the Rotated Grid      \\ 
-             & $\rightarrow$ G &  Computed on the Geophysical Grid  \\ \hline
+             & $\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
@@ -77,107 +76,194 @@
 \end{center}
 \end{table}
 
+
+\noindent
 As an example, consider a diagnostic whose associated GDIAG parameter is equal
-to ``UUR 002''.  From GDIAG we can determine that this diagnostic is a 
-U-vector component located at the C-grid U-point within the Rotated framework.
+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,
-rotated or geophysical, A-Grid or C-grid, etc.) defined internally.  The Output routines
-use this information in order to determine
-what type of rotations and/or transformations need to be performed.  Thus, all Diagnostic
-interpolations are done at the time of output rather than during each model dynamic step.
-In this way the User now has more flexibility
-in determining the type of gridded data which is output.
+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, and retrieve model diagnostics, and may be called from any user-supplied application
-and/or output routine.  The available utilities and the CALL sequences are listed below.
+clear, write and retrieve model diagnostics, and may be called from any routine.  
+The available utilities and the CALL sequences are listed below.
 
 
-{\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 useful when
-called from either user application routines or user output routines, and 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:
+\noindent
+{\bf fill\_diagnostics}:  This routine will increment the specified diagnostic
+quantity with a field sent through the argument list.
 
+
+\noindent
 \begin{tabbing}
 XXXXXXXXX\=XXXXXX\= \kill
-\>        CALL SETDIAG (NUM) \\
+\>        call fill\_diagnostics (myThid, chardiag, levflg, nlevs, \\
+                bibjflg, bi, bj, arrayin) \\
 \\
-where \>  NUM   \>= Diagnostic number from menu \\
+where \>  myThid   \>= Current Process(or) \\
+      \>  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. \\
+      \>  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 \\
+      \>           \>    AND that we have been sent a local array \\
+      \>           \>    AND that the array has the 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 \\
 \end{tabbing}
 
 
-{\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 an
-application routine as well.  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
+{\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:
 
+\noindent
 \begin{tabbing}
 XXXXXXXXX\=XXXXXX\= \kill
-\>        CALL GETDIAG (LEV,NUM,QTMP,UNDEF) \\
+\>        call setdiag (num) \\
 \\
-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 \>  num   \>= Diagnostic number from menu \\
 \end{tabbing}
 
-{\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
+{\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 CLRDIAG (NUM) \\
+\>        call getdiag (lev,num,qtmp,undef) \\
 \\
-where \>  NUM   \>= Diagnostic number from menu \\
+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 \\
 \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 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:
-
-
+\noindent
 \begin{tabbing}
 XXXXXXXXX\=XXXXXX\= \kill
-\>        CALL ZAPDIAG (NUM) \\
+\>        call clrdiag (num) \\
 \\
-where \>  NUM   \>= Diagnostic number from menu \\
+where \>  num   \>= Diagnostic number from menu \\
 \end{tabbing}
 
-{\bf DIAGSIZE}:  We end 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 DIAG COMMON, having the form:
+\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:
 
+\noindent
 \begin{tabbing}
 XXXXXXXXX\=XXXXXX\= \kill
-\>        COMMON /DIAG/ NDIAG\_MAX,QDIAG(IM,JM,1) \\
+\>        call zapdiag (NUM) \\
 \\
+where \>  num   \>= Diagnostic number from menu \\
 \end{tabbing}
 
-where NDIAG\_MAX 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
-specific diagnostic types.
-In order to minimize the maximum memory requirement used by the model,
-the default GCM executable is compiled with room for only one horizontal
-diagnostic array, as shown in the above example.  
-In order for the User to enable more than 1 two-dimensional diagnostic,
-the size of the DIAG COMMON must be expanded to accomodate the desired diagnostics.
+
+\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)
+
+\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{FORWARD\_STEP}{pkg-diagnostics-diagnostics_SIZE.h}, or by allowing the 
-shell script (???????) to make this
-change based on the choice of diagnostic output made in the namelist.
+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:
+
+\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:
+
+\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, \ \\
+   levels(1,2) = 1.,2.,3.,4.,5., \ \\
+   fields(1,2) = 'THETA   ','SALT    ', \ \\
+   filename(2) = 'diagout2', \ \\
+ $\&$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 
+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,
+and the names of diagnostics quantities are THETA and SALT.
+
+\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 
+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
+desired for diagnostic output is computed. 
 
 \newpage
 
@@ -620,9 +706,8 @@
 {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t)
 \]
 where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the 
-output frequency of the diagnositc, and $\Delta t$ is
-the timestep over which the diagnostic is updated.  For further information on how
-to set the diagnostic output frequency {\bf NQDIAG}, please see Part III, A User's Guide.
+output frequency of the diagnostic, and $\Delta t$ is
+the timestep over which the diagnostic is updated.  
 
 {\bf 1)  \underline {UFLUX} Surface Zonal Wind Stress on the Atmosphere ($Newton/m^2$) } 
 
