/[MITgcm]/manual/s_outp_pkgs/text/diagnostics.tex
ViewVC logotype

Diff of /manual/s_outp_pkgs/text/diagnostics.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.1 by molod, Mon Jul 18 20:45:27 2005 UTC revision 1.10 by jmc, Tue Jun 14 00:16:23 2011 UTC
# Line 1  Line 1 
1  \subsection{Diagnostics--A Flexible Infrastructure}  \section{Diagnostics--A Flexible Infrastructure}
2  \label{sec:pkg:diagnostics}  \label{sec:pkg:diagnostics}
3  \begin{rawhtml}  \begin{rawhtml}
4  <!-- CMIREDIR:package_diagnostics: -->  <!-- CMIREDIR:package_diagnostics: -->
5  \end{rawhtml}  \end{rawhtml}
6    
7  \subsubsection{Introduction}  \subsection{Introduction}
8    
9  \noindent  \noindent
10  This section of the documentation describes the Diagnostics package available within  This section of the documentation describes the Diagnostics package
11  the GCM.  A large selection of model diagnostics is available for output.    available within the GCM.  A large selection of model diagnostics is
12  In addition to the diagnostic quantities pre-defined in the GCM, there exists  available for output.  In addition to the diagnostic quantities
13  the option, in any experiment, to define a new diagnostic quantity and include it  pre-defined in the GCM, there exists the option, in any experiment, to
14  as part of the diagnostic output with the addition of a single subroutine call in the  define a new diagnostic quantity and include it as part of the
15  routine where the field is computed. As a matter of philosophy, no diagnostic is enabled  diagnostic output with the addition of a single subroutine call in the
16  as default, thus each user must specify the exact diagnostic information required for an  routine where the field is computed. As a matter of philosophy, no
17  experiment.  This is accomplished by enabling the specific diagnostic of interest cataloged  diagnostic is enabled as default, thus each user must specify the
18  in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). Instructions for enabling  exact diagnostic information required for an experiment.  This is
19  diagnostic output and defining new diagnostic quantities are found in Section  accomplished by enabling the specific diagnostic of interest cataloged
20    in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}).
21    Instructions for enabling diagnostic output and defining new
22    diagnostic quantities are found in Section
23  \ref{sec:diagnostics:usersguide} of this document.  \ref{sec:diagnostics:usersguide} of this document.
24    
25  \noindent  \noindent
26  The Diagnostic Menu in this section of the manual is a listing of diagnostic quantities available  The Diagnostic Menu in this section of the manual is a listing of
27  within the main (dynamics) part of the GCM. Additional diagnostic quantities, defined within the  diagnostic quantities available within the main (dynamics) part of the
28  different GCM packages, are available and are listed in the diagnostic menu subsection of  GCM. Additional diagnostic quantities, defined within the different
29  the manual section associated with each relevant package. Once a diagnostic is enabled, the  GCM packages, are available and are listed in the diagnostic menu
30  GCM will continually increment an array specifically allocated for that diagnostic whenever the  subsection of the manual section associated with each relevant
31  appropriate quantity is computed.  A counter is defined which records how many times each diagnostic  package. Once a diagnostic is enabled, the GCM will continually
32  quantity has been incremented.  Several special diagnostics are included in the menu. Quantities  increment an array specifically allocated for that diagnostic whenever
33  refered to as ``Counter Diagnostics'', are defined for selected diagnostics which record the  the appropriate quantity is computed.  A counter is defined which
34  frequency at which a diagnostic is incremented separately for each model grid location.  records how many times each diagnostic quantity has been incremented.
35  Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate  Several special diagnostics are included in the menu. Quantities
36  defining new diagnostics for a particular experiment.  referred to as ``Counter Diagnostics'', are defined for selected
37    diagnostics which record the frequency at which a diagnostic is
38    incremented separately for each model grid location.  Quantities
39    referred to as ``User Diagnostics'' are included in the menu to
40    facilitate defining new diagnostics for a particular experiment.
41    
42  \subsubsection{Equations}  \subsection{Equations}
43  Not relevant.  Not relevant.
44    
45  \subsubsection{Key Subroutines and Parameters}  \subsection{Key Subroutines and Parameters}
46  \label{sec:diagnostics:diagover}  \label{sec:diagnostics:diagover}
47    
48  \noindent  \noindent
49  There are several utilities within the GCM available to users to enable, disable,  There are several utilities within the GCM available to users to
50  clear, write and retrieve model diagnostics, and may be called from any routine.    enable, disable, clear, write and retrieve model diagnostics, and may
51  The available utilities and the CALL sequences are listed below.  be called from any routine.  The available utilities and the CALL
52    sequences are listed below.
53  \noindent  
54  {\bf diagnostics\_fill}:  This is the main user interface routine to the diagnostics  \noindent
55  package. This routine will increment the specified diagnostic quantity with a field  {\bf DIAGNOSTICS\_ADDTOLIST}
56  sent through the argument list.  (\filelink{pkg/diagnostics/diagnostics\_addtolist.F}{pkg-diagnostics-diagnostics\_addtolist.F}):
57    %This subroutine enables a diagnostic from the Diagnostic Menu,
58  \noindent  %meaning that space is allocated for the
59  \begin{tabbing}  %diagnostic and the model routines will increment the diagnostic value
60  XXXXXXXXX\=XXXXXX\= \kill  %during execution.
61  \>        call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\  This routine is the underlying interface routine for defining a new permanent
62  \>              bibjflg, bi, bj, myThid) \\  diagnostic in the main model or in a package. The calling sequence is:
63  \\  
64  where \>  arrayin  \>= Field to increment diagnostics array \\  \begin{verbatim}
65        \>  chardiag \>= Character *8 expression for diag to fill \\         CALL DIAGNOSTICS_ADDTOLIST (
66        \>  levflg   \>= Integer flag for vertical levels: \\       O     diagNum,
67        \>           \>= 0 indicates multiple (nlevs) levels incremented \\       I     diagName, diagCode, diagUnits, diagTitle, diagMate,
68        \>           \>= -1 indicates multiple (nlevs) levels incremented, \\       I     myThid )
69        \>           \> but in reverse vertical order \\  
70        \>           \> positive integer - WHICH single level to increment. \\       where:
71        \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg gt 0) \\         diagNum   = diagnostic Id number - Output from routine
72        \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\         diagName  = name of diagnostic to declare
73        \>           \>= 0 indicates that the bi-bj loop must be done here \\         diagCode  = parser code for this diagnostic
74        \>           \>= 1 indicates that the bi-bj loop is done OUTSIDE \\         diagUnits = field units for this diagnostic
75        \>           \>= 2 indicates that the bi-bj loop is done OUTSIDE \\         diagTitle = field description for this diagnostic
76        \>           \>    AND that we have been sent a local array \\         diagMate  = diagnostic mate number
77        \>           \>    AND that the array has the shadow regions \\         myThid    = my Thread Id number
78        \>           \>= 3 indicates that the bi-bj loop is done OUTSIDE \\  
79        \>           \>    AND that we have been sent a local array \\  \end{verbatim}
80        \>           \>    AND that the array has no shadow regions \\  
81        \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\  
82        \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\  \noindent
83        \>  myThid   \>= Current Thread number \\  {\bf DIAGNOSTICS\_FILL}
84  \end{tabbing}  (\filelink{pkg/diagnostics/diagnostics\_fill.F}{pkg-diagnostics-diagnostics\_fill.F}):
85    This is the main user interface routine to the diagnostics package.
86  \noindent  This routine will increment the specified
87  {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to  diagnostic quantity with a field sent through the argument list.
88  diagnostics\_fill which performs the same functions and has an additional option  
89    \begin{verbatim}
90            CALL DIAGNOSTICS_FILL(
91           I             inpFld, diagName,
92           I             kLev, nLevs, bibjFlg, bi, bj, myThid )
93    
94         where:
95            inpFld   = Field to increment diagnostics array
96            diagName = diagnostic identificator name (8 characters long)
97            kLev     = Integer flag for vertical levels:
98                       > 0 (any integer): WHICH single level to increment in qdiag.
99                       0,-1 to increment "nLevs" levels in qdiag,
100                       0 : fill-in in the same order as the input array
101                       -1: fill-in in reverse order.
102            nLevs    = indicates Number of levels of the input field array
103                       (whether to fill-in all the levels (kLev<1) or just one (kLev>0))
104            bibjFlg  = Integer flag to indicate instructions for bi bj loop
105                     = 0 indicates that the bi-bj loop must be done here
106                     = 1 indicates that the bi-bj loop is done OUTSIDE
107                     = 2 indicates that the bi-bj loop is done OUTSIDE
108                          AND that we have been sent a local array (with overlap regions)
109                          (local array here means that it has no bi-bj dimensions)
110                     = 3 indicates that the bi-bj loop is done OUTSIDE
111                          AND that we have been sent a local array
112                          AND that the array has no overlap region (interior only)
113                       NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter
114            bi       = X-direction tile number - used for bibjFlg=1-3
115            bj       = Y-direction tile number - used for bibjFlg=1-3
116            myThid   =  my thread Id number
117    \end{verbatim}
118    
119    \noindent
120    {\bf DIAGNOSTICS\_SCALE\_FILL}
121    (\filelink{pkg/diagnostics/diagnostics\_scale\_fill.F}{pkg-diagnostics-diagnostics\_scale\_fill.F}):
122    This is a possible alternative routine to
123    DIAGNOSTICS\_FILL which performs the same functions and has an additional option
124  to scale the field before filling or raise the field to a power before filling.  to scale the field before filling or raise the field to a power before filling.
125    
126  \noindent  \begin{verbatim}
127  \begin{tabbing}          CALL DIAGNOSTICS_SCALE_FILL(
128  XXXXXXXXX\=XXXXXX\= \kill         I             inpFld, scaleFact, power, diagName,
129  \>        call diagnostics\_scale\_fill (arrayin, scalefactor, power, chardiag, \\         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
130  \>        levflg, nlevs, bibjflg, bi, bj, myThid) \\  
131  \\  
132  where \>  All the arguments are the same as for diagnostics\_fill with the addition of: \\       where all the arguments are the same as for DIAGNOSTICS_FILL with
133        \>  scalefactor \>= Factor to scale field \\       the addition of:
134        \>  power       \>= Integer power to which to raise the input field \\          scaleFact   = Scaling factor to apply to the input field product
135  \end{tabbing}          power       = Integer power to which to raise the input field (before scaling)
136    \end{verbatim}
137  \noindent  
138  {\bf diagnostics\_is\_on}: Function call to inquire whether a diagnostic is active  \noindent
139  and can be incremented. Useful when there is a computation that must be done locally  {\bf DIAGNOSTICS\_FRACT\_FILL}
140  before a call to diagnostics\_fill. The call sequence:  (\filelink{pkg/diagnostics/diagnostics\_fract\_fill.F}{pkg-diagnostics-diagnostics\_fract\_fill.F}):
141    This is a specific alternative routine to DIAGNOSTICS\_[SCALE]\_FILL
142  \noindent  for the case of a diagnostics which is associated to
143  \begin{tabbing}  a fraction-weight factor (referred to as the diagnostics "counter mate").
144  XXXXXXXXX\=XXXXXX\= \kill  This fraction-weight field is expected to vary during the simulation
145  \> flag = diagnostics\_is\_on( diagName, myThid )  and is provided as argument to DIAGNOSTICS\_FRACT\_FILL
146  \\  in order to perform fraction-weighted time-average diagnostics.
147  where \>  diagName \>= Character *8 expression for diagnostic \\  Note that the fraction-weight field has to correspond to the diagnostics
148        \>  myThid   \>= Current Thread number \\  counter-mate which has to be filled independently with a call to DIAGNOSTICS\_FILL.
149  \end{tabbing}  
150    \begin{verbatim}
151  \noindent          CALL DIAGNOSTICS_FRACT_FILL(
152  {\bf diagnostics\_get\_pointers}:  This subroutine retrieves the value of a the diagnostics         I             inpFld, fractFld, scaleFact, power, diagName,
153  pointers that other routines require as input - can be useful if the diagnostics common         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
154  blocks are not local to a routine.  
155    
156  \noindent       where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with
157  \begin{tabbing}       the addition of:
158  XXXXXXXXX\=XXXXXX\= \kill          fractFld    = fraction used for weighted average diagnostics
159  \> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid )  \end{verbatim}
160  \\  
161  where \>  diagName \>= Character *8 expression of diagnostic \\  \noindent
162        \>  ipoint   \>= Pointer into qdiag array - from idiag array in common \\  {\bf DIAGNOSTICS\_IS\_ON}: Function call to inquire whether a
163        \>  jpoint   \>= Pointer into diagnostics menu - from jdiag array in common \\  diagnostic is active and should be incremented. Useful when there is a
164        \>  myThid   \>= Current Thread number \\  computation that must be done locally before a call to
165  \end{tabbing}  DIAGNOSTICS\_FILL. The call sequence:
166    
167  \noindent  \begin{verbatim}
168  {\bf getdiag}:  This subroutine retrieves the value of a model diagnostic.  This routine          flag = DIAGNOSTICS_IS_ON( diagName, myThid )
169  is particulary useful when called from a user output routine, although it can be called  
170  from any routine.  This routine returns the time-averaged value of the diagnostic by       where:
171  dividing the current accumulated diagnostic value by its corresponding counter.  This          diagName = diagnostic identificator name (8 characters long)
172  routine does not change the value of the diagnostic itself, that is, it does not replace          myThid   = my thread Id number
173  the diagnostic with its time-average.  The calling sequence for this routine is givin by:  \end{verbatim}
174    
175  \noindent  \noindent
176  \begin{tabbing}  {\bf DIAGNOSTICS\_COUNT}
177  XXXXXXXXX\=XXXXXX\= \kill  (\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
178  \>        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\  This subroutine increments the diagnostics counter only.
179  \\  In general, the diagnostics counter is incremented at the same time as the
180  where \>  lev     \>= Model Level at which the diagnostic is desired \\  diagnostics is filled, by calling DIAGNOSTICS\_FILL.
181        \>  undef   \>= Fill value to be used when diagnostic is undefined \\  However, there are few cases where the counter is not incremented
182        \>  qtmp    \>= Time-Averaged Diagnostic Output \\  during the filling (e.g., when the filling is done level per level but
183        \>  ipoint  \>= Pointer into qdiag array - from idiag array in common \\  level 1 is skipped) and needs to be done explicitly with a call to subroutine
184        \>  mate    \>= Diagnostic mate pointer number \\  DIAGNOSTICS\_COUNT. The call sequence is:
185        \>  bi      \>= X-direction process(or) number \\  
186        \>  bj      \>= Y-direction process(or) number \\  \begin{verbatim}
187        \>  myThid  \>= Current Thread number \\          CALL DIAGNOSTICS_COUNT(
188  \end{tabbing}         I                        diagName, bi, bj, myThid )
189    
190  \noindent       where:
191  {\bf diagnostics\_add2list}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning          diagName  = name of diagnostic to increment the counter
192  that space is allocated for the diagnostic and the model routines will increment the          bi        = X-direction tile number, or 0 if called outside bi,bj loops
193  diagnostic value during execution.  This routine is the underlying interface routine          bj        = Y-direction tile number, or 0 if called outside bi,bj loops
194  for defining a new permanent diagnostic in the main model or in a package.  The calling sequence is:          myThid    = my thread Id number
195    
196  \noindent  \end{verbatim}
197  \begin{tabbing}  
198  XXXXXXXXX\=XXXXXX\= \kill  %\noindent
199  \>        call diagnostics\_add2list( diagNum,diagName, diagCode, \\  %{\bf DIAGNOSTICS\_GET\_POINTERS}
200  \>        diagUnits, diagTitle, myThid ) \\  %(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
201  \\  %This subroutine retrieves the value of a the diagnostics pointers
202  where \> diagNum   \>=Diagnostic number - Output from routine \\  %that other routines require as input - can be useful if the diagnostics common
203        \> diagName  \>=character*8 diagnostic name \\  %blocks are not local to a routine.
204        \> diagCode  \>=character*16 parsing code (see description of gdiag below) \\  %
205        \> diagUnits \>=Diagnostic units (character*16) \\  %\begin{verbatim}
206        \> diagTitle \>=Diagnostic title or long name (up to character*80) \\  %        CALL DIAGNOSTICS_GET_POINTERS(
207        \> myThid    \>=Current Thread number \\  %     I                       diagName, listId,
208  \end{tabbing}  %     O                       ndId, ip,
209    %     I                       myThid )
210  \noindent  %
211  {\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is  %     where:
212  particularly useful when called from user output routines to re-initialize diagnostics  %        diagName = diagnostic identificator name (8 characters long)
213  during the run.  The calling sequence is:  %        listId   = list number that specifies the output frequency
214    %        ndId     = diagnostics  Id number (in available diagnostics list)
215  \noindent  %        ip       = diagnostics  pointer to storage array
216  \begin{tabbing}  %        myThid   = my Thread Id number
217  XXXXXXXXX\=XXXXXX\= \kill  %\end{verbatim}
218  \>        call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\  %
219  \\  %\noindent
220  where \>  jpoint \>= Diagnostic number from menu - from jdiag array \\  %{\bf GETDIAG}
221            ipoint \>= Pointer number into qdiag array - from idiag array \\  %%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
222        \>  myThid \>=Current Thread number \\  %This subroutine retrieves the value of a model diagnostic.
223  \end{tabbing}  %This routine is particularly useful when called from a
224    %user output routine, although it can be called from any routine.  This
225  \noindent  %routine returns the time-averaged value of the diagnostic by dividing
226  The diagnostics are computed at various times and places within the GCM. Because the  %the current accumulated diagnostic value by its corresponding counter.
227  MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,  %This routine does not change the value of the diagnostic itself, that
228  corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars,  %is, it does not replace the diagnostic with its time-average.  The
229  while others are components of vectors. An internal array is defined which contains  %%calling sequence for this routine is givin by:
230  information concerning various grid attributes of each diagnostic. The GDIAG  %
231  array (in common block \\diagnostics in file DIAGNOSTICS.h) is internally defined as a  %\begin{verbatim}
232  character*8 variable, and is equivalenced to a character*1 "parse" array in output in  %        CALL GETDIAG(
233  order to extract the grid-attribute information.  The GDIAG array is described in  %       I             levreal, undef,
234  Table \ref{tab:diagnostics:gdiag.tabl}.  %       O             qtmp,
235    %       I             ndId, mate, ip, im, bi, bj, myThid )
236    %
237    %     where:
238    %%        lev     = Model Level at which the diagnostic is desired
239    %        undef   = Fill value to be used when diagnostic is undefined
240    %        qtmp    = Time-Averaged Diagnostic Output
241    %        ndId    = diagnostics  Id number (in available diagnostics list)
242    %        mate    = counter diagnostic number if any ; 0 otherwise
243    %        ip      = pointer to storage array location for diag.
244    %        im      = pointer to storage array location for mate
245    %        bi      = X-direction tile number
246    %        bj      = Y-direction tile number
247    %        myThid  = my thread Id number
248    %\end{verbatim}
249    %
250    %\noindent
251    %{\bf DIAGNOSTICS\_CLRDIAG}
252    %(\filelink{pkg/diagnostics/diagnostics\_clear.F}{pkg-diagnostics-diagnostics\_clear.F}):
253    %This subroutine initializes the values of model
254    %diagnostics to zero, and is particularly useful when called from user
255    %output routines to re-initialize diagnostics during the run.
256    %The calling sequence is:
257    %
258    %\begin{verbatim}
259    %        CALL DIAGNOSTICS_CLRDIAG ( ipt, nLev, myThid )
260    %
261    %     where:
262    %        ipt    :: diagnostic pointer to storage array
263    %        nLev   :: number of levels (in storage array) to reset
264    %        myThid :: my Thread Id number
265    %\end{verbatim}
266    
267  \begin{table}  \begin{table}
268  \caption{Diagnostic Parsing Array}  \caption{Diagnostic Parsing Array}
# Line 197  Table \ref{tab:diagnostics:gdiag.tabl}. Line 270  Table \ref{tab:diagnostics:gdiag.tabl}.
270  \begin{center}  \begin{center}
271  \begin{tabular}{ |c|c|l| }  \begin{tabular}{ |c|c|l| }
272  \hline  \hline
273  \multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\  \multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\
274  \hline  \hline
275  \hline  \hline
276  Array & Value & Description \\  Array & Value & Description \\
277  \hline  \hline
278    parse(1)   & $\rightarrow$ S &  Scalar Diagnostic                 \\   parse(1)  & $\rightarrow$ S &  Scalar Diagnostic                 \\
279               & $\rightarrow$ U &  U-vector component Diagnostic     \\             & $\rightarrow$ U &  U-vector component Diagnostic     \\
280               & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline             & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline
281    parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\   parse(2)  & $\rightarrow$ U &  C-Grid U-Point                    \\
282               & $\rightarrow$ V &  C-Grid V-Point                    \\             & $\rightarrow$ V &  C-Grid V-Point                    \\
283               & $\rightarrow$ M &  C-Grid Mass Point                 \\             & $\rightarrow$ M &  C-Grid Mass Point                 \\
284               & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline             & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
285    parse(3)   & $\rightarrow$ R &  Not Currently in Use              \\ \hline   parse(3)  & $\rightarrow$   &  Used for Level Integrated output: cumulate levels \\
286    parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline             & $\rightarrow$ r &  same but cumulate product by model level thickness \\
287    parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\             & $\rightarrow$ R &  same but cumulate product by hFac \& level thickness \\ \hline
288               & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline   parse(4)  & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
289    parse(6-8) & $\rightarrow$ C &  3-digit integer corresponding to  \\   parse(5)  & $\rightarrow$ C &  with Counter array                \\
290               &                 &  vector or counter component mate  \\ \hline             & $\rightarrow$ P &  post-processed (not filled up) from other diags \\
291               & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
292     parse(6-8)&                 &  retired, formerly: 3-digit mate number \\ \hline
293     parse(9)  & $\rightarrow$ U &  model-level plus 1/2  \\
294               & $\rightarrow$ M &  model-level middle  \\
295               & $\rightarrow$ L &  model-level minus 1/2  \\ \hline
296     parse(10) & $\rightarrow$ 0 &  levels = 0  \\
297               & $\rightarrow$ 1 &  levels = 1  \\
298               & $\rightarrow$ R &  levels = Nr  \\
299               & $\rightarrow$ L &  levels = MAX(Nr,NrPhys)  \\
300               & $\rightarrow$ M &  levels = MAX(Nr,NrPhys) - 1  \\
301               & $\rightarrow$ G &  levels = Ground\_level Number \\
302               & $\rightarrow$ I &  levels = sea-Ice\_level Number \\
303               & $\rightarrow$ X &  free levels option (need to be set explicitly)\\ \hline
304  \end{tabular}  \end{tabular}
305  \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}  \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
306  \end{center}  \end{center}
307  \end{table}  \end{table}
308    
309    \noindent
310    The diagnostics are computed at various times and places within the
311    GCM. Because MITgcm may employ a staggered grid, diagnostics may be
312    computed at grid box centers, corners, or edges, and at the middle or
313    edge in the vertical. Some diagnostics are scalars, while others are
314    components of vectors. An internal array is defined which contains
315    information concerning various grid attributes of each diagnostic. The
316    GDIAG array (in common block {\tt diagnostics} in file {\tt
317      DIAGNOSTICS.h}) is internally defined as a character*16 variable, and
318    is equivalenced to a character*1 "parse" array in output in order to
319    extract the grid-attribute information.  The GDIAG array is described
320    in Table \ref{tab:diagnostics:gdiag.tabl}.
321    
322  \noindent  \noindent
323  As an example, consider a diagnostic whose associated GDIAG parameter is equal  As an example, consider a diagnostic whose associated GDIAG parameter is equal
324  to ``UU  002''.  From GDIAG we can determine that this diagnostic is a  to ``UUR\hspace{5mm}MR''.  From GDIAG we can determine that this diagnostic is a
325  U-vector component located at the C-grid U-point.  U-vector component located at the C-grid U-point, model mid-level (M)
326  Its corresponding V-component diagnostic is located in Diagnostic \# 002.  with Nr levels (last R).
327    
328  \noindent  \noindent
329  In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,  In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,
330  C-grid location, etc.) defined internally.  The Output routines use this information  C-grid location, etc.) defined internally.  The Output routines use this information
331  in order to determine what type of transformations need to be performed.  Any  in order to determine what type of transformations need to be performed.  Any
332  interpolations are done at the time of output rather than during each model step.  interpolations are done at the time of output rather than during each model step.
333  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
334  is output.  is output.
335    
336  \subsubsection{Usage Notes}  %\newpage
337    \subsection{Usage Notes}
338  \label{sec:diagnostics:usersguide}  \label{sec:diagnostics:usersguide}
339    
340    \subsubsection{Using available diagnostics}
341  \noindent  \noindent
342  To use the diagnostics package, other than enabling it in packages.conf  To use the diagnostics package, other than enabling it in {\tt packages.conf}
343  and turning the usediagnostics flag in data.pkg to .TRUE., there are two  and turning the {\tt useDiagnostics} flag in {\tt data.pkg} to .TRUE., there are two
344  further steps the user must take to enable the diagnostics package for  further steps the user must take to enable the diagnostics package for
345  output of quantities that are already defined in the GCM under an experiment's  output of quantities that are already defined in the GCM under an experiment's
346  configuration of packages.  A namelist must be supplied in the run directory  configuration of packages.
347  called data.diagnostics, and the file DIAGNOSTICS\_SIZE.h must be included in the  A parameter file {\tt data.diagnostics} must be supplied in the run directory,
348  code directory.  The steps for defining a new (permanent or experiment-specific  and the file DIAGNOSTICS\_SIZE.h must be included in the
349  temporary) diagnostic quantity will be outlined later.  code directory.  The steps for defining a new (permanent or experiment-specific
350    temporary) diagnostic quantity will be outlined later.
351  \noindent The namelist will activate a user-defined list of diagnostics quantities  
352  to be computed, specify the frequency and type of output, the number of levels, and  \noindent The namelist in parameter file {\tt data.diagnostics} will activate
353  the name of all the separate output files. A sample data.diagnostics namelist file:  a user-defined list of diagnostics quantities to be computed,
354    specify the frequency and type of output, the number of levels, and
355  \noindent  the name of all the separate output files.
356  $\#$ Diagnostic Package Choices \\  A sample {\tt data.diagnostics} namelist file:
357   $\&$diagnostics\_list \\  
358    frequency(1) = 86400., \ \\  \begin{verbatim}
359     levels(1,1) = 1., \ \\  # Diagnostic Package Choices
360     fields(1,1) = 'RSURF   ', \ \\  #--------------------
361     filename(1) = 'surface', \ \\  #  dumpAtLast (logical): always write output at the end of simulation (default=F)
362    frequency(2) = 86400., \ \\  #  diag_mnc   (logical): write to NetCDF files (default=useMNC)
363     levels(1,2) = 1.,2.,3.,4.,5., \ \\  #--for each output-stream:
364     fields(1,2) = 'UVEL    ','VVEL    ', \ \\  #  fileName(n) : prefix of the output file name (max 80c long) for outp.stream n
365     filename(2) = 'diagout1', \ \\  #  frequency(n):< 0 : write snap-shot output every |frequency| seconds
366    frequency(3) = 3600., \ \\  #               > 0 : write time-average output every frequency seconds
367     fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', \ \\  #  timePhase(n)     : write at time = timePhase + multiple of |frequency|
368     filename(3) = 'diagout2', \ \\  #    averagingFreq  : frequency (in s) for periodic averaging interval
369    fileflags(3) = ' P1     ', \ \\  #    averagingPhase : phase     (in s) for periodic averaging interval
370   $\&$end \ \\  #    repeatCycle    : number of averaging intervals in 1 cycle
371    #  levels(:,n) : list of levels to write to file (Notes: declared as REAL)
372  \noindent  #                when this entry is missing, select all common levels of this list
373  In this example, there are two output files that will be generated  #  fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n
374  for each tile and for each output time. The first set of output files  #                (see "available_diagnostics.log" file for the full list of diags)
375  has the prefix diagout1, does time averaging every 86400. seconds,  #  missing_value(n) : missing value for real-type fields in output file "n"
376  (frequency is 86400.), and will write fields which are multiple-level  #  fileFlags(n)     : specific code (8c string) for output file "n"
377  fields at output levels 1-5. The names of diagnostics quantities are  #--------------------
378  UVEL and VVEL.  The second set of output files   &DIAGNOSTICS_LIST
379  has the prefix diagout2, does time averaging every 3600. seconds,    fields(1:2,1) = 'UVEL    ','VVEL    ',
380  includes fields which are multiple-level fields, levels output are 1-5,     levels(1:5,1) = 1.,2.,3.,4.,5.,
381  and the names of diagnostics quantities are THETA and SALT.     filename(1) = 'diagout1',
382      frequency(1) = 86400.,
383  \noindent    fields(1:3,2) = 'THETA   ','SALT    ',
384  The user must assure that enough computer memory is allocated for the diagnostics     filename(2) = 'diagout2',
385  and the output streams selected for a particular experiment.  This is acomplished by    fileflags(2) = ' P1     ',
386  modifying the file DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.    frequency(2) = 3600.,
387  The parameters that should be checked are called numdiags, numlists, numperlist, and   &
388  diagSt\_size.  
389     &DIAG_STATIS_PARMS
390  \noindent numdiags (and diagSt\_size): \\   &
391  \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG  \end{verbatim}
392  which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\  
393    \noindent
394    In this example, there are two output files that will be generated for
395    each tile and for each output time. The first set of output files has
396    the prefix diagout1, does time averaging every 86400. seconds,
397    (frequency is 86400.), and will write fields which are multiple-level
398    fields at output levels 1-5. The names of diagnostics quantities are
399    UVEL and VVEL.  The second set of output files has the prefix
400    diagout2, does time averaging every 3600. seconds, includes fields
401    with all levels, and the names of diagnostics quantities are THETA and SALT.
402    
403    \noindent
404    The user must assure that enough computer memory is allocated for the
405    diagnostics and the output streams selected for a particular
406    experiment.  This is accomplished by modifying the file
407    DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
408    The parameters that should be checked are called numDiags, numLists,
409    numperList, and diagSt\_size.
410    
411    \noindent numDiags (and diagSt\_size): \\
412    \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG
413    which is located in the file
414    \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}
415  and has the form:\\  and has the form:\\
416  common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) \\  \begin{verbatim}
417  \noindent        _RL  qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy)
418  The first two-dimensions of qdiag correspond to the horizontal dimension of a given diagnostic,        _RL  qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy)
419  and the third dimension of qdiag is used to identify diagnostic fields and levels combined. In        COMMON / DIAG_STORE_R / qdiag, qSdiag
420  order to minimize the memory requirement of the model for diagnostics, the default GCM  \end{verbatim}
421  executable is compiled with room for only one horizontal diagnostic array, or with  \noindent
422  numdiags set to Nr. In order for the User to enable more than 1 three-dimensional diagnostic,  The first two-dimensions of qdiag correspond to the horizontal
423  the size of the diagnostics common must be expanded to accomodate the desired diagnostics.  dimension of a given diagnostic, and the third dimension of qdiag is
424  This can be accomplished by manually changing the parameter numdiags in the  used to identify diagnostic fields and levels combined. In order to
425  file \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.  minimize the memory requirement of the model for diagnostics, the
426  numdiags should be set greater than or equal to the sum of all the diagnostics activated  default GCM executable is compiled with room for only one horizontal
427  for output each multiplied by the number of levels defined for that diagnostic quantity.  diagnostic array, or with numDiags set to Nr. In order for the User to
428  For the above example, there are 4 multiple level fields, which the diagnostics menu  enable more than 1 three-dimensional diagnostic, the size of the
429  (see below) indicates are defined at the GCM vertical resolution, Nr. The value of  diagnostics common must be expanded to accommodate the desired
430  numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to 4*Nr, or, say 40 if $Nr=10$.  diagnostics.  This can be accomplished by manually changing the
431    parameter numDiags in the file
432  \noindent numlists and numperlist: \\  \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
433  \noindent The parameter numlists must be set greater than or equal to the number of  numDiags should be set greater than or equal to the sum of all the
434  separate output streams that the user specifies in the namelist file data.diagnostics.  diagnostics activated for output each multiplied by the number of
435  The parameter numperlist corresponds to the number of diagnostics requested in each  levels defined for that diagnostic quantity.  For the above example,
436  output stream.  there are 4 multiple level fields, which the diagnostics menu (see
437    below) indicates are defined at the GCM vertical resolution, Nr. The
438  \noindent  value of numDiags in DIAGNOSTICS\_SIZE.h would therefore be equal to
439  In order to define and include as part of the diagnostic output any field  4*Nr, or, say 40 if $Nr=10$.
440  that is desired for a particular experiment, two steps must be taken. The  
441  first is to enable the ``User Diagnostic'' in data.diagnostics. This is  \noindent numLists and numperList: \\
442  accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through  \noindent The parameter numLists must be set greater than or equal to
443  UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level  the number of separate output streams that the user specifies in the
444  fields) to the data.diagnostics namelist in one of the output streams. These  namelist file data.diagnostics.  The parameter numperList corresponds
445  fields are listed in the diagnostics menu. The second step is to  to the maximum number of diagnostics requested per output streams.
446  add a call to diagnostics\_fill from the subroutine in which the quantity  
447  desired for diagnostic output is computed.  \subsubsection{Adding new diagnostics to the code}
448    
449  \noindent  \noindent
450  In order to add a new diagnostic to the permanent set of diagnostics that the  In order to define and include as part of the diagnostic output any
451  main model or any package contains as part of its diagnostics menu, the subroutine  field that is desired for a particular experiment, two steps must be
452  diagnostics\_add2list should be called during the initialization phase of the  taken. The first is to enable the ``User Diagnostic'' in
453  main model or package. For the main model, the call should be made from  {\tt data.diagnostics}. This is accomplished by adding one of the ``User
454  subroutine diagnostics\_main\_init, and for a package, the call should probably  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
455  be made from somewhere in the packages\_init\_fixed sequence (probaby from inside  fields, or SDIAG1 through SDIAG10 for single level fields) to the
456  the particular package's init\_fixed routine). A typical code sequence to set the  data.diagnostics namelist in one of the output streams. These fields
457  input arguments to diagnostics\_add2list would look like:  are listed in the diagnostics menu. The second step is to add a call
458    to DIAGNOSTICS\_FILL from the subroutine in which the quantity desired
459  \noindent  for diagnostic output is computed.
460  \begin{tabbing}  
461  XXXXXXXXX\=XXXXXX\= \kill  \noindent
462  \>      diagName  = 'THETA   ' \\  In order to add a new diagnostic to the permanent set of diagnostics
463  \>      diagTitle = 'Potential Temperature (degC,K)' \\  that the main model or any package contains as part of its diagnostics
464  \>      diagUnits = 'Degrees K       ' \\  menu, the subroutine DIAGNOSTICS\_ADDTOLIST should be called during the
465  \>      diagCode  = 'SM      MR      ' \\  initialization phase of the main model or package. For the main model,
466  \>      CALL DIAGNOSTICS\_ADD2LIST( diagNum, \\  the call should be made from subroutine DIAGNOSTICS\_MAIN\_INIT, and
467  \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\  for a package, the call should probably be made from
468  \\  %somewhere in the PACKAGES\_INIT\_FIXED sequence (probably
469  \end{tabbing}  from inside the particular package's init\_fixed routine.
470    A typical code sequence to set the
471  \noindent If the new diagnostic quantity is associated with either a vector  input arguments to DIAGNOSTICS\_ADDTOLIST would look like:
472  pair or a diagnostic counter, the diagCode argument must be filled with the  
473  proper index for the ``mate''. The output argument from diagnostics\_add2list  \begin{verbatim}
474  that is called diagNum here contains a running total of the number of diagnostics        diagName  = 'RHOAnoma'
475  defined in the code up to any point during the run. The sequence number for the        diagTitle = 'Density Anomaly (=Rho-rhoConst)'
476  next two diagnostics defined (the two components of the vector pair, for instance)        diagUnits = 'kg/m^3          '
477  will be diagNum+1 and diagNum+2. The definition of the first component of the vector        diagCode  = 'SMR     MR      '
478  pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2.        CALL DIAGNOSTICS\_ADDTOLIST( diagNum,
479  Since the subroutine increments diagNum, the definition of the second component of       I          diagName, diagCode, diagUnits, diagTitle, 0, myThid )
480  the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for  \end{verbatim}
481  this case would look like:  
482    \noindent If the new diagnostic quantity is associated with either a
483  \noindent  vector pair or a diagnostic counter, the diagMate argument must be
484  \begin{tabbing}  provided with the proper index corresponding to the ``mate''.
485  XXXXXXXXX\=XXXXXX\= \kill  The output argument from DIAGNOSTICS\_ADDTOLIST that is called diagNum here
486  \>      diagName  = 'UVEL    ' \\  contains a running total of the number of diagnostics defined in the code up to
487  \>      diagTitle = 'Zonal Velocity                ' \\  any point during the run. The sequence number for the next two
488  \>      diagUnits = 'm / sec         ' \\  diagnostics defined (the two components of the vector pair, for
489  \>      diagCode  = 'SM      MR      ' \\  instance) will be diagNum+1 and diagNum+2. The definition of the first
490  \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' \\  component of the vector pair must fill the ``mate'' segment of the
491  \>      call diagnostics\_add2list( diagNum, \\  diagCode as diagnostic number diagNum+2.  Since the subroutine
492  \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\  increments diagNum, the definition of the second component of the
493  \>      diagName  = 'VVEL    ' \\  vector fills the ``mate'' part of diagCode with diagNum. A code
494  \>      diagTitle = 'Meridional Velocity           ' \\  sequence for this case would look like:
495  \>      diagUnits = 'm / sec         ' \\  
496  \>      diagCode  = 'SM      MR      ' \\  \begin{verbatim}
497  \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' \\        diagName  = 'UVEL    '
498  \>      call diagnostics\_add2list( diagNum, \\        diagTitle = 'Zonal Component of Velocity (m/s)'
499  \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\        diagUnits = 'm/s             '
500  \\        diagCode  = 'UUR     MR      '
501  \end{tabbing}        diagMate  = diagNum + 2
502          CALL DIAGNOSTICS_ADDTOLIST( diagNum,
503         I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
504    
505          diagName  = 'VVEL    '
506          diagTitle = 'Meridional Component of Velocity (m/s)'
507          diagUnits = 'm/s             '
508          diagCode  = 'VVR     MR      '
509          diagMate  = diagNum
510          CALL DIAGNOSTICS_ADDTOLIST( diagNum,
511         I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
512    \end{verbatim}
513    
514  \input{part7/diagnostics-menu.tex}  \input{s_outp_pkgs/text/diagnostics-menu.tex}
515    
516  \newpage  \newpage
517  \noindent For a list of the diagnostic fields available in the  \noindent For a list of the diagnostic fields available in the
518  different MITgcm packages, follow the link to the diagnostics menu  different MITgcm packages, follow the link to the diagnostics menu
519  in the manual section describing the package:  in the manual section describing the package:
520    
521  \filelink{part6/fizhi-diagnostics-menu.tex}{pkg-fizhi-fizhi-diagnostics-menu.tex}  \begin{itemize}
522    \item aim: \ref{sec:pkg:aim:diagnostics}
523    \item exf: \ref{sec:pkg:exf:diagnostics}
524    \item gchem: \ref{sec:pkg:gchem:diagnostics}
525    \item generic\_advdiff: \ref{sec:pkg:gad:diagnostics}
526    \item gridalt: \ref{sec:pkg:gridalt:diagnostics}
527    \item gmredi: \ref{sec:pkg:gmredi:diagnostics}
528    \item fizhi: \ref{sec:pkg:fizhi:diagnostics}
529    \item kpp: \ref{sec:pkg:kpp:diagnostics}
530    \item land: \ref{sec:pkg:land:diagnostics}
531    \item mom\_common: \ref{sec:pkg:mom_common:diagnostics}
532    \item obcs: \ref{sec:pkg:obcs:diagnostics}
533    \item thsice: \ref{sec:pkg:thsice:diagnostics}
534    \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}
535    \item ptracers: \ref{sec:pkg:ptracers:diagnostics}
536    \end{itemize}
537    
538  \subsubsection{Dos and Donts}  \subsection{Dos and Donts}
539    
540  \subsubsection{Diagnostics Reference}  \subsection{Diagnostics Reference}
541    
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.10
  ViewVC Help
Powered by ViewVC 1.1.22