/[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.6 by molod, Thu Apr 6 22:53:32 2006 UTC revision 1.12 by jmc, Wed Jun 12 22:26:48 2013 UTC
# Line 33  increment an array specifically allocate Line 33  increment an array specifically allocate
33  the appropriate quantity is computed.  A counter is defined which  the appropriate quantity is computed.  A counter is defined which
34  records how many times each diagnostic quantity has been incremented.  records how many times each diagnostic quantity has been incremented.
35  Several special diagnostics are included in the menu. Quantities  Several special diagnostics are included in the menu. Quantities
36  refered to as ``Counter Diagnostics'', are defined for selected  referred to as ``Counter Diagnostics'', are defined for selected
37  diagnostics which record the frequency at which a diagnostic is  diagnostics which record the frequency at which a diagnostic is
38  incremented separately for each model grid location.  Quantitied  incremented separately for each model grid location.  Quantities
39  refered to as ``User Diagnostics'' are included in the menu to  referred to as ``User Diagnostics'' are included in the menu to
40  facilitate defining new diagnostics for a particular experiment.  facilitate defining new diagnostics for a particular experiment.
41    
42  \subsection{Equations}  \subsection{Equations}
# Line 52  be called from any routine.  The availab Line 52  be called from any routine.  The availab
52  sequences are listed below.  sequences are listed below.
53    
54  \noindent  \noindent
55  {\bf diagnostics\_fill}: This is the main user interface routine to  {\bf DIAGNOSTICS\_ADDTOLIST}
56  the diagnostics package. This routine will increment the specified  (\filelink{pkg/diagnostics/diagnostics\_addtolist.F}{pkg-diagnostics-diagnostics\_addtolist.F}):
57    %This subroutine enables a diagnostic from the Diagnostic Menu,
58    %meaning that space is allocated for the
59    %diagnostic and the model routines will increment the diagnostic value
60    %during execution.
61    This routine is the underlying interface routine for defining a new permanent
62    diagnostic in the main model or in a package. The calling sequence is:
63    
64    \begin{verbatim}
65           CALL DIAGNOSTICS_ADDTOLIST (
66         O     diagNum,
67         I     diagName, diagCode, diagUnits, diagTitle, diagMate,
68         I     myThid )
69    
70         where:
71           diagNum   = diagnostic Id number - Output from routine
72           diagName  = name of diagnostic to declare
73           diagCode  = parser code for this diagnostic
74           diagUnits = field units for this diagnostic
75           diagTitle = field description for this diagnostic
76           diagMate  = diagnostic mate number
77           myThid    = my Thread Id number
78    
79    \end{verbatim}
80    
81    
82    \noindent
83    {\bf DIAGNOSTICS\_FILL}
84    (\filelink{pkg/diagnostics/diagnostics\_fill.F}{pkg-diagnostics-diagnostics\_fill.F}):
85    This is the main user interface routine to the diagnostics package.
86    This routine will increment the specified
87  diagnostic quantity with a field sent through the argument list.  diagnostic quantity with a field sent through the argument list.
88    
89  \begin{verbatim}  \begin{verbatim}
90          call diagnostics_fill(          CALL DIAGNOSTICS_FILL(
91         &      arrayin, chardiag, levflg, nlevs,         I             inpFld, diagName,
92         &      bibjflg, bi, bj, myThid )         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
93    
94       where:       where:
95          arrayin  = Field to increment diagnostics array          inpFld   = Field to increment diagnostics array
96          chardiag = Character *8 expression for diag to fill          diagName = diagnostic identificator name (8 characters long)
97          levflg   = Integer flag for vertical levels:          kLev     = Integer flag for vertical levels:
98                   = 0 indicates multiple (nlevs) levels incremented                     > 0 (any integer): WHICH single level to increment in qdiag.
99                   = -1 indicates multiple (nlevs) levels incremented,                     0,-1 to increment "nLevs" levels in qdiag,
100                       but in reverse vertical order                     0 : fill-in in the same order as the input array
101                       positive integer - WHICH single level to increment.                     -1: fill-in in reverse order.
102          nlevs    = indicates Number of levels to be filled (1 if levflg gt 0)          nLevs    = indicates Number of levels of the input field array
103          bibjflg  = Integer flag to indicate instructions for bi bj loop                     (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                   = 0 indicates that the bi-bj loop must be done here
106                   = 1 indicates that the bi-bj loop is done OUTSIDE                   = 1 indicates that the bi-bj loop is done OUTSIDE
107                   = 2 indicates that the bi-bj loop is done OUTSIDE                   = 2 indicates that the bi-bj loop is done OUTSIDE
108                       AND that we have been sent a local array                        AND that we have been sent a local array (with overlap regions)
109                       AND that the array has the shadow regions                        (local array here means that it has no bi-bj dimensions)
110                   = 3 indicates that the bi-bj loop is done OUTSIDE                   = 3 indicates that the bi-bj loop is done OUTSIDE
111                       AND that we have been sent a local array                        AND that we have been sent a local array
112                       AND that the array has no shadow regions                        AND that the array has no overlap region (interior only)
113          bi       = X-direction process(or) number - used for bibjflg=1-3                     NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter
114          bj       = Y-direction process(or) number - used for bibjflg=1-3          bi       = X-direction tile number - used for bibjFlg=1-3
115          myThid   = Current Thread number          bj       = Y-direction tile number - used for bibjFlg=1-3
116            myThid   =  my thread Id number
117  \end{verbatim}  \end{verbatim}
118    
119  \noindent  \noindent
120  {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to  {\bf DIAGNOSTICS\_SCALE\_FILL}
121  diagnostics\_fill which performs the same functions and has an additional option  (\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  \begin{verbatim}  \begin{verbatim}
127          call diagnostics_scale_fill(          CALL DIAGNOSTICS_SCALE_FILL(
128         &         arrayin, scalefactor, power, chardiag,         I             inpFld, scaleFact, power, diagName,
129         &         levflg, nlevs, bibjflg, bi, bj, myThid )         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
130    
131    
132       where all the arguments are the same as for diagnostics_fill with       where all the arguments are the same as for DIAGNOSTICS_FILL with
133       the addition of:       the addition of:
134          scalefactor = Factor to scale field          scaleFact   = Scaling factor to apply to the input field product
135          power       = Integer power to which to raise the input field          power       = Integer power to which to raise the input field (after scaling)
136  \end{verbatim}  \end{verbatim}
137    
138  \noindent  \noindent
139  {\bf diagnostics\_is\_on}: Function call to inquire whether a  {\bf DIAGNOSTICS\_FRACT\_FILL}
140  diagnostic is active and can be incremented. Useful when there is a  (\filelink{pkg/diagnostics/diagnostics\_fract\_fill.F}{pkg-diagnostics-diagnostics\_fract\_fill.F}):
141  computation that must be done locally before a call to  This is a specific alternative routine to DIAGNOSTICS\_[SCALE]\_FILL
142  diagnostics\_fill. The call sequence:  for the case of a diagnostics which is associated to
143    a fraction-weight factor (referred to as the diagnostics "counter mate").
144    This fraction-weight field is expected to vary during the simulation
145    and is provided as argument to DIAGNOSTICS\_FRACT\_FILL
146    in order to perform fraction-weighted time-average diagnostics.
147    Note that the fraction-weight field has to correspond to the diagnostics
148    counter-mate which has to be filled independently with a call to DIAGNOSTICS\_FILL.
149    
150  \begin{verbatim}  \begin{verbatim}
151          flag = diagnostics_is_on( diagName, myThid )          CALL DIAGNOSTICS_FRACT_FILL(
152           I             inpFld, fractFld, scaleFact, power, diagName,
153       where:         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
         diagName = Character *8 expression for diagnostic  
         myThid   = Current Thread number  
 \end{verbatim}  
   
 \noindent  
 {\bf diagnostics\_get\_pointers}: This subroutine retrieves the value  
 of a the diagnostics pointers that other routines require as input -  
 can be useful if the diagnostics common blocks are not local to a  
 routine.  
154    
 \begin{verbatim}  
         call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid )  
155    
156       where:       where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with
157          diagName = Character *8 expression of diagnostic       the addition of:
158          ipoint   = Pointer into qdiag array - from idiag array in common          fractFld    = fraction used for weighted average diagnostics
         jpoint   = Pointer into diagnostics menu - from jdiag array in common  
         myThid   = Current Thread number  
159  \end{verbatim}  \end{verbatim}
160    
161  \noindent  \noindent
162  {\bf getdiag}: This subroutine retrieves the value of a model  {\bf DIAGNOSTICS\_IS\_ON}: Function call to inquire whether a
163  diagnostic.  This routine is particulary useful when called from a  diagnostic is active and should be incremented. Useful when there is a
164  user output routine, although it can be called from any routine.  This  computation that must be done locally before a call to
165  routine returns the time-averaged value of the diagnostic by dividing  DIAGNOSTICS\_FILL. The call sequence:
 the current accumulated diagnostic value by its corresponding counter.  
 This routine does not change the value of the diagnostic itself, that  
 is, it does not replace the diagnostic with its time-average.  The  
 calling sequence for this routine is givin by:  
   
 \begin{verbatim}  
         call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid)  
   
      where:  
         lev     = Model Level at which the diagnostic is desired  
         undef   = Fill value to be used when diagnostic is undefined  
         qtmp    = Time-Averaged Diagnostic Output  
         ipoint  = Pointer into qdiag array - from idiag array in common  
         mate    = Diagnostic mate pointer number  
         bi      = X-direction process(or) number  
         bj      = Y-direction process(or) number  
         myThid  = Current Thread number  
 \end{verbatim}  
   
 \noindent  
 {\bf diagnostics\_add2list}: This subroutine enables a diagnostic from  
 the Diagnostic Menu, meaning that space is allocated for the  
 diagnostic and the model routines will increment the diagnostic value  
 during execution.  This routine is the underlying interface routine  
 for defining a new permanent diagnostic in the main model or in a  
 package.  The calling sequence is:  
166    
167  \begin{verbatim}  \begin{verbatim}
168         call diagnostics_add2list( diagNum,diagName, diagCode,          flag = DIAGNOSTICS_IS_ON( diagName, myThid )
                                   diagUnits, diagTitle, myThid )  
169    
170       where:       where:
171         diagNum   = Diagnostic number - Output from routine          diagName = diagnostic identificator name (8 characters long)
172         diagName  = character*8 diagnostic name          myThid   = my thread Id number
        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  
173  \end{verbatim}  \end{verbatim}
174    
175  \noindent  \noindent
176  {\bf clrdiag}: This subroutine initializes the values of model  {\bf DIAGNOSTICS\_COUNT}
177  diagnostics to zero, and is particularly useful when called from user  (\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
178  output routines to re-initialize diagnostics during the run.  The  This subroutine increments the diagnostics counter only.
179  calling sequence is:  In general, the diagnostics counter is incremented at the same time as the
180    diagnostics is filled, by calling DIAGNOSTICS\_FILL.
181    However, there are few cases where the counter is not incremented
182    during the filling (e.g., when the filling is done level per level but
183    level 1 is skipped) and needs to be done explicitly with a call to subroutine
184    DIAGNOSTICS\_COUNT. The call sequence is:
185    
186  \begin{verbatim}  \begin{verbatim}
187          call diagnostics_clrdiag (jpoint, ipoint, myThid)          CALL DIAGNOSTICS_COUNT(
188           I                        diagName, bi, bj, myThid )
189    
190       where:       where:
191          jpoint = Diagnostic number from menu - from jdiag array          diagName  = name of diagnostic to increment the counter
192          ipoint = Pointer number into qdiag array - from idiag array          bi        = X-direction tile number, or 0 if called outside bi,bj loops
193          myThid = Current Thread number          bj        = Y-direction tile number, or 0 if called outside bi,bj loops
194  \end{verbatim}          myThid    = my thread Id number
195    
196  \noindent  \end{verbatim}
197  The diagnostics are computed at various times and places within the  
198  GCM. Because MITgcm may employ a staggered grid, diagnostics may be  %\noindent
199  computed at grid box centers, corners, or edges, and at the middle or  %{\bf DIAGNOSTICS\_GET\_POINTERS}
200  edge in the vertical. Some diagnostics are scalars, while others are  %(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
201  components of vectors. An internal array is defined which contains  %This subroutine retrieves the value of a the diagnostics pointers
202  information concerning various grid attributes of each diagnostic. The  %that other routines require as input - can be useful if the diagnostics common
203  GDIAG array (in common block {\tt diagnostics} in file {\tt  %blocks are not local to a routine.
204    DIAGNOSTICS.h}) is internally defined as a character*8 variable, and  %
205  is equivalenced to a character*1 "parse" array in output in order to  %\begin{verbatim}
206  extract the grid-attribute information.  The GDIAG array is described  %        CALL DIAGNOSTICS_GET_POINTERS(
207  in Table \ref{tab:diagnostics:gdiag.tabl}.  %     I                       diagName, listId,
208    %     O                       ndId, ip,
209    %     I                       myThid )
210    %
211    %     where:
212    %        diagName = diagnostic identificator name (8 characters long)
213    %        listId   = list number that specifies the output frequency
214    %        ndId     = diagnostics  Id number (in available diagnostics list)
215    %        ip       = diagnostics  pointer to storage array
216    %        myThid   = my Thread Id number
217    %\end{verbatim}
218    %
219    %\noindent
220    %{\bf GETDIAG}
221    %%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
222    %This subroutine retrieves the value of a model diagnostic.
223    %This routine is particularly useful when called from a
224    %user output routine, although it can be called from any routine.  This
225    %routine returns the time-averaged value of the diagnostic by dividing
226    %the current accumulated diagnostic value by its corresponding counter.
227    %This routine does not change the value of the diagnostic itself, that
228    %is, it does not replace the diagnostic with its time-average.  The
229    %%calling sequence for this routine is givin by:
230    %
231    %\begin{verbatim}
232    %        CALL GETDIAG(
233    %       I             levreal, undef,
234    %       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 209  in Table \ref{tab:diagnostics:gdiag.tabl Line 270  in 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    %\newpage
337  \subsection{Usage Notes}  \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    the name of all the separate output files.
356    A sample {\tt data.diagnostics} namelist file:
357    
358  \begin{verbatim}  \begin{verbatim}
359  # Diagnostic Package Choices  # Diagnostic Package Choices
360   &diagnostics\_list  #--------------------
361    frequency(1) = 86400.,  #  dumpAtLast (logical): always write output at the end of simulation (default=F)
362     levels(1,1) = 1.,  #  diag_mnc   (logical): write to NetCDF files (default=useMNC)
363     fields(1,1) = 'RSURF   ',  #--for each output-stream:
364     filename(1) = 'surface',  #  fileName(n) : prefix of the output file name (max 80c long) for outp.stream n
365    frequency(2) = 86400.,  #  frequency(n):< 0 : write snap-shot output every |frequency| seconds
366     levels(1,2) = 1.,2.,3.,4.,5.,  #               > 0 : write time-average output every frequency seconds
367     fields(1,2) = 'UVEL    ','VVEL    ',  #  timePhase(n)     : write at time = timePhase + multiple of |frequency|
368     filename(2) = 'diagout1',  #    averagingFreq  : frequency (in s) for periodic averaging interval
369    frequency(3) = 3600.,  #    averagingPhase : phase     (in s) for periodic averaging interval
370     fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE',  #    repeatCycle    : number of averaging intervals in 1 cycle
371     filename(3) = 'diagout2',  #  levels(:,n) : list of levels to write to file (Notes: declared as REAL)
372    fileflags(3) = ' P1     ',  #                when this entry is missing, select all common levels of this list
373   &end  #  fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n
374    #                (see "available_diagnostics.log" file for the full list of diags)
375    #  missing_value(n) : missing value for real-type fields in output file "n"
376    #  fileFlags(n)     : specific code (8c string) for output file "n"
377    #--------------------
378     &DIAGNOSTICS_LIST
379      fields(1:2,1) = 'UVEL    ','VVEL    ',
380       levels(1:5,1) = 1.,2.,3.,4.,5.,
381       filename(1) = 'diagout1',
382      frequency(1) = 86400.,
383      fields(1:2,2) = 'THETA   ','SALT    ',
384       filename(2) = 'diagout2',
385      fileflags(2) = ' P1     ',
386      frequency(2) = 3600.,
387     &
388    
389     &DIAG_STATIS_PARMS
390     &
391  \end{verbatim}  \end{verbatim}
392    
393  \noindent  \noindent
# Line 290  the prefix diagout1, does time averaging Line 398  the prefix diagout1, does time averaging
398  fields at output levels 1-5. The names of diagnostics quantities are  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  UVEL and VVEL.  The second set of output files has the prefix
400  diagout2, does time averaging every 3600. seconds, includes fields  diagout2, does time averaging every 3600. seconds, includes fields
401  which are multiple-level fields, levels output are 1-5, and the names  with all levels, and the names of diagnostics quantities are THETA and SALT.
 of diagnostics quantities are THETA and SALT.  
402    
403  \noindent  \noindent
404  The user must assure that enough computer memory is allocated for the  The user must assure that enough computer memory is allocated for the
405  diagnostics and the output streams selected for a particular  diagnostics and the output streams selected for a particular
406  experiment.  This is acomplished by modifying the file  experiment.  This is accomplished by modifying the file
407  DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.  DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
408  The parameters that should be checked are called numdiags, numlists,  The parameters that should be checked are called numDiags, numLists,
409  numperlist, and diagSt\_size.  numperList, and diagSt\_size.
410    
411  \noindent numdiags (and diagSt\_size): \\  \noindent numDiags (and diagSt\_size): \\
412  \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG  \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG
413  which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\  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  \begin{verbatim}  \begin{verbatim}
417        common /diagnostics/        _RL  qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy)
418       &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)        _RL  qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy)
419          COMMON / DIAG_STORE_R / qdiag, qSdiag
420  \end{verbatim}  \end{verbatim}
421  \noindent  \noindent
422  The first two-dimensions of qdiag correspond to the horizontal  The first two-dimensions of qdiag correspond to the horizontal
# Line 315  dimension of a given diagnostic, and the Line 424  dimension of a given diagnostic, and the
424  used to identify diagnostic fields and levels combined. In order to  used to identify diagnostic fields and levels combined. In order to
425  minimize the memory requirement of the model for diagnostics, the  minimize the memory requirement of the model for diagnostics, the
426  default GCM executable is compiled with room for only one horizontal  default GCM executable is compiled with room for only one horizontal
427  diagnostic array, or with numdiags set to Nr. In order for the User to  diagnostic array, or with numDiags set to Nr. In order for the User to
428  enable more than 1 three-dimensional diagnostic, the size of the  enable more than 1 three-dimensional diagnostic, the size of the
429  diagnostics common must be expanded to accomodate the desired  diagnostics common must be expanded to accommodate the desired
430  diagnostics.  This can be accomplished by manually changing the  diagnostics.  This can be accomplished by manually changing the
431  parameter numdiags in the file  parameter numDiags in the file
432  \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.  \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
433  numdiags should be set greater than or equal to the sum of all the  numDiags should be set greater than or equal to the sum of all the
434  diagnostics activated for output each multiplied by the number of  diagnostics activated for output each multiplied by the number of
435  levels defined for that diagnostic quantity.  For the above example,  levels defined for that diagnostic quantity.  For the above example,
436  there are 4 multiple level fields, which the diagnostics menu (see  there are 4 multiple level fields, which the diagnostics menu (see
437  below) indicates are defined at the GCM vertical resolution, Nr. The  below) indicates are defined at the GCM vertical resolution, Nr. The
438  value of numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to  value of numDiags in DIAGNOSTICS\_SIZE.h would therefore be equal to
439  4*Nr, or, say 40 if $Nr=10$.  4*Nr, or, say 40 if $Nr=10$.
440    
441  \noindent numlists and numperlist: \\  \noindent numLists and numperList: \\
442  \noindent The parameter numlists must be set greater than or equal to  \noindent The parameter numLists must be set greater than or equal to
443  the number of separate output streams that the user specifies in the  the number of separate output streams that the user specifies in the
444  namelist file data.diagnostics.  The parameter numperlist corresponds  namelist file data.diagnostics.  The parameter numperList corresponds
445  to the number of diagnostics requested in each output stream.  to the maximum number of diagnostics requested per output streams.
446    
447    \subsubsection{Adding new diagnostics to the code}
448    
449  \noindent  \noindent
450  In order to define and include as part of the diagnostic output any  In order to define and include as part of the diagnostic output any
451  field that is desired for a particular experiment, two steps must be  field that is desired for a particular experiment, two steps must be
452  taken. The first is to enable the ``User Diagnostic'' in  taken. The first is to enable the ``User Diagnostic'' in
453  data.diagnostics. This is accomplished by adding one of the ``User  {\tt data.diagnostics}. This is accomplished by adding one of the ``User
454  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
455  fields, or SDIAG1 through SDIAG10 for single level fields) to the  fields, or SDIAG1 through SDIAG10 for single level fields) to the
456  data.diagnostics namelist in one of the output streams. These fields  data.diagnostics namelist in one of the output streams. These fields
457  are listed in the diagnostics menu. The second step is to add a call  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  to DIAGNOSTICS\_FILL from the subroutine in which the quantity desired
459  for diagnostic output is computed.  for diagnostic output is computed.
460    
461  \noindent  \noindent
462  In order to add a new diagnostic to the permanent set of diagnostics  In order to add a new diagnostic to the permanent set of diagnostics
463  that the main model or any package contains as part of its diagnostics  that the main model or any package contains as part of its diagnostics
464  menu, the subroutine diagnostics\_add2list should be called during the  menu, the subroutine DIAGNOSTICS\_ADDTOLIST should be called during the
465  initialization phase of the main model or package. For the main model,  initialization phase of the main model or package. For the main model,
466  the call should be made from subroutine diagnostics\_main\_init, and  the call should be made from subroutine DIAGNOSTICS\_MAIN\_INIT, and
467  for a package, the call should probably be made from somewhere in the  for a package, the call should probably be made from
468  packages\_init\_fixed sequence (probaby from inside the particular  %somewhere in the PACKAGES\_INIT\_FIXED sequence (probably
469  package's init\_fixed routine). A typical code sequence to set the  from inside the particular package's init\_fixed routine.
470  input arguments to diagnostics\_add2list would look like:  A typical code sequence to set the
471    input arguments to DIAGNOSTICS\_ADDTOLIST would look like:
472    
473  \begin{verbatim}  \begin{verbatim}
474        diagName  = 'THETA   '        diagName  = 'RHOAnoma'
475        diagTitle = 'Potential Temperature (degC,K)'        diagTitle = 'Density Anomaly (=Rho-rhoConst)'
476        diagUnits = 'Degrees K       '        diagUnits = 'kg/m^3          '
477        diagCode  = 'SM      MR      '        diagCode  = 'SMR     MR      '
478        CALL DIAGNOSTICS\_ADD2LIST( diagNum,        CALL DIAGNOSTICS\_ADDTOLIST( diagNum,
479       I          diagName, diagCode, diagUnits, diagTitle, myThid )       I          diagName, diagCode, diagUnits, diagTitle, 0, myThid )
480  \end{verbatim}  \end{verbatim}
481    
482  \noindent If the new diagnostic quantity is associated with either a  \noindent If the new diagnostic quantity is associated with either a
483  vector pair or a diagnostic counter, the diagCode argument must be  vector pair or a diagnostic counter, the diagMate argument must be
484  filled with the proper index for the ``mate''. The output argument  provided with the proper index corresponding to the ``mate''.
485  from diagnostics\_add2list that is called diagNum here contains a  The output argument from DIAGNOSTICS\_ADDTOLIST that is called diagNum here
486  running total of the number of diagnostics defined in the code up to  contains a running total of the number of diagnostics defined in the code up to
487  any point during the run. The sequence number for the next two  any point during the run. The sequence number for the next two
488  diagnostics defined (the two components of the vector pair, for  diagnostics defined (the two components of the vector pair, for
489  instance) will be diagNum+1 and diagNum+2. The definition of the first  instance) will be diagNum+1 and diagNum+2. The definition of the first
# Line 382  vector fills the ``mate'' part of diagCo Line 494  vector fills the ``mate'' part of diagCo
494  sequence for this case would look like:  sequence for this case would look like:
495    
496  \begin{verbatim}  \begin{verbatim}
497        diagName  = 'UVEL    '        diagName  = 'UVEL    '
498        diagTitle = 'Zonal Velocity                '        diagTitle = 'Zonal Component of Velocity (m/s)'
499        diagUnits = 'm / sec         '        diagUnits = 'm/s             '
500        diagCode  = 'SM      MR      '        diagCode  = 'UUR     MR      '
501        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      '        diagMate  = diagNum + 2
502        call diagnostics\_add2list( diagNum,        CALL DIAGNOSTICS_ADDTOLIST( diagNum,
503       I          diagName, diagCode, diagUnits, diagTitle, myThid )       I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
504        diagName  = 'VVEL    '  
505        diagTitle = 'Meridional Velocity           '        diagName  = 'VVEL    '
506        diagUnits = 'm / sec         '        diagTitle = 'Meridional Component of Velocity (m/s)'
507        diagCode  = 'SM      MR      '        diagUnits = 'm/s             '
508        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      '        diagCode  = 'VVR     MR      '
509        call diagnostics\_add2list( diagNum,        diagMate  = diagNum
510       I          diagName, diagCode, diagUnits, diagTitle, myThid )        CALL DIAGNOSTICS_ADDTOLIST( diagNum,
511         I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
512  \end{verbatim}  \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
# Line 419  in the manual section describing the pac Line 532  in the manual section describing the pac
532  \item obcs: \ref{sec:pkg:obcs:diagnostics}  \item obcs: \ref{sec:pkg:obcs:diagnostics}
533  \item thsice: \ref{sec:pkg:thsice:diagnostics}  \item thsice: \ref{sec:pkg:thsice:diagnostics}
534  \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}  \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}
535    \item ptracers: \ref{sec:pkg:ptracers:diagnostics}
536  \end{itemize}  \end{itemize}
537    
538  \subsection{Dos and Donts}  \subsection{Dos and Donts}
Legend:
Removed from v.1.6  
changed lines
  Added in v.1.12
  ViewVC Help
Powered by ViewVC 1.1.22