/[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.5 by edhill, Thu Apr 6 17:36:07 2006 UTC revision 1.9 by jmc, Fri Jun 10 13:13:11 2011 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 51  enable, disable, clear, write and retrie Line 51  enable, disable, clear, write and retrie
51  be called from any routine.  The available utilities and the CALL  be called from any routine.  The available utilities and the CALL
52  sequences are listed below.  sequences are listed below.
53    
54    \noindent
55    {\bf DIAGNOSTICS\_ADDTOLIST}
56    (\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  \noindent
83  {\bf diagnostics\_fill}: This is the main user interface routine to  {\bf DIAGNOSTICS\_FILL}
84  the diagnostics package. This routine will increment the specified  (\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, chardiag,
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, chardiag,
129         &         levflg, nlevs, bibjflg, bi, bj, myThid )         I             kLev, nLevs, bibjFlg, bi, bj, myThid )
130    
131       where all the arguments are the same as for diagnostics_fill with  
132         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 (before scaling)
136  \end{verbatim}  \end{verbatim}
137    
138  \noindent  \noindent
139  {\bf diagnostics\_is\_on}: Function call to inquire whether a  {\bf DIAGNOSTICS\_IS\_ON}: Function call to inquire whether a
140  diagnostic is active and can be incremented. Useful when there is a  diagnostic is active and can be incremented. Useful when there is a
141  computation that must be done locally before a call to  computation that must be done locally before a call to
142  diagnostics\_fill. The call sequence:  DIAGNOSTICS\_FILL. The call sequence:
143    
144  \begin{verbatim}  \begin{verbatim}
145          flag = diagnostics_is_on( diagName, myThid )          flag = DIAGNOSTICS_IS_ON( diagName, myThid )
146    
147       where:       where:
148          diagName = Character *8 expression for diagnostic          diagName = diagnostic identificator name (8 characters long)
149          myThid   = Current Thread number          myThid   = my thread Id number
150  \end{verbatim}  \end{verbatim}
151    
152  \noindent  \noindent
153  {\bf diagnostics\_get\_pointers}: This subroutine retrieves the value  {\bf DIAGNOSTICS\_GET\_POINTERS}
154  of a the diagnostics pointers that other routines require as input -  (\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
155  can be useful if the diagnostics common blocks are not local to a  This subroutine retrieves the value of a the diagnostics pointers
156  routine.  that other routines require as input - can be useful if the diagnostics common
157    blocks are not local to a routine.
158    
159  \begin{verbatim}  \begin{verbatim}
160          call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid )          CALL DIAGNOSTICS_GET_POINTERS(
161         I                       diagName, listId,
162         O                       ndId, ip,
163         I                       myThid )
164    
165       where:       where:
166          diagName = Character *8 expression of diagnostic          diagName = diagnostic identificator name (8 characters long)
167          ipoint   = Pointer into qdiag array - from idiag array in common          listId   = list number that specifies the output frequency
168          jpoint   = Pointer into diagnostics menu - from jdiag array in common          ndId     = diagnostics  Id number (in available diagnostics list)
169          myThid   = Current Thread number          ip       = diagnostics  pointer to storage array
170            myThid   = my Thread Id number
171  \end{verbatim}  \end{verbatim}
172    
173  \noindent  \noindent
174  {\bf getdiag}: This subroutine retrieves the value of a model  {\bf GETDIAG}
175  diagnostic.  This routine is particulary useful when called from a  (\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}):
176    This subroutine retrieves the value of a model diagnostic.  
177    This routine is particularly useful when called from a
178  user output routine, although it can be called from any routine.  This  user output routine, although it can be called from any routine.  This
179  routine returns the time-averaged value of the diagnostic by dividing  routine returns the time-averaged value of the diagnostic by dividing
180  the current accumulated diagnostic value by its corresponding counter.  the current accumulated diagnostic value by its corresponding counter.
# Line 141  is, it does not replace the diagnostic w Line 183  is, it does not replace the diagnostic w
183  calling sequence for this routine is givin by:  calling sequence for this routine is givin by:
184    
185  \begin{verbatim}  \begin{verbatim}
186          call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid)          CALL GETDIAG(
187           I             levreal, undef,
188           O             qtmp,
189           I             ndId, mate, ip, im, bi, bj, myThid )
190    
191       where:       where:
192          lev     = Model Level at which the diagnostic is desired          lev     = Model Level at which the diagnostic is desired
193          undef   = Fill value to be used when diagnostic is undefined          undef   = Fill value to be used when diagnostic is undefined
194          qtmp    = Time-Averaged Diagnostic Output          qtmp    = Time-Averaged Diagnostic Output
195          ipoint  = Pointer into qdiag array - from idiag array in common          ndId    = diagnostics  Id number (in available diagnostics list)
196          mate    = Diagnostic mate pointer number          mate    = counter diagnostic number if any ; 0 otherwise
197          bi      = X-direction process(or) number          ip      = pointer to storage array location for diag.
198          bj      = Y-direction process(or) number          im      = pointer to storage array location for mate
199          myThid  = Current Thread number          bi      = X-direction tile number
200  \end{verbatim}          bj      = Y-direction tile number
201            myThid  = my thread Id number
 \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:  
   
 \begin{verbatim}  
        call diagnostics_add2list( diagNum,diagName, diagCode,  
                                   diagUnits, diagTitle, myThid )  
   
      where:  
        diagNum   = Diagnostic number - Output from routine  
        diagName  = character*8 diagnostic name  
        diagCode  = character*16 parsing code (see description of gdiag below)  
        diagUnits = Diagnostic units (character*16)  
        diagTitle = Diagnostic title or long name (up to character*80)  
        myThid    = Current Thread number  
202  \end{verbatim}  \end{verbatim}
203    
204  \noindent  \noindent
205  {\bf clrdiag}: This subroutine initializes the values of model  {\bf DIAGNOSTICS\_CLRDIAG}
206    (\filelink{pkg/diagnostics/diagnostics\_clear.F}{pkg-diagnostics-diagnostics\_clear.F}):
207    This subroutine initializes the values of model
208  diagnostics to zero, and is particularly useful when called from user  diagnostics to zero, and is particularly useful when called from user
209  output routines to re-initialize diagnostics during the run.  The  output routines to re-initialize diagnostics during the run.  
210  calling sequence is:  The calling sequence is:
211    
212  \begin{verbatim}  \begin{verbatim}
213          call diagnostics_clrdiag (jpoint, ipoint, myThid)          CALL DIAGNOSTICS_CLRDIAG ( ipt, nLev, myThid )
214    
215       where:       where:
216          jpoint = Diagnostic number from menu - from jdiag array          ipt    :: diagnostic pointer to storage array
217          ipoint = Pointer number into qdiag array - from idiag array          nLev   :: number of levels (in storage array) to reset
218          myThid = Current Thread number          myThid :: my Thread Id number
219  \end{verbatim}  \end{verbatim}
220    
221  \noindent  \noindent
# Line 198  edge in the vertical. Some diagnostics a Line 226  edge in the vertical. Some diagnostics a
226  components of vectors. An internal array is defined which contains  components of vectors. An internal array is defined which contains
227  information concerning various grid attributes of each diagnostic. The  information concerning various grid attributes of each diagnostic. The
228  GDIAG array (in common block {\tt diagnostics} in file {\tt  GDIAG array (in common block {\tt diagnostics} in file {\tt
229    DIAGNOSTICS.h}) is internally defined as a character*8 variable, and    DIAGNOSTICS.h}) is internally defined as a character*10 variable, and
230  is equivalenced to a character*1 "parse" array in output in order to  is equivalenced to a character*1 "parse" array in output in order to
231  extract the grid-attribute information.  The GDIAG array is described  extract the grid-attribute information.  The GDIAG array is described
232  in Table \ref{tab:diagnostics:gdiag.tabl}.  in Table \ref{tab:diagnostics:gdiag.tabl}.
# Line 214  in Table \ref{tab:diagnostics:gdiag.tabl Line 242  in Table \ref{tab:diagnostics:gdiag.tabl
242  \hline  \hline
243  Array & Value & Description \\  Array & Value & Description \\
244  \hline  \hline
245    parse(1)   & $\rightarrow$ S &  Scalar Diagnostic                 \\   parse(1)  & $\rightarrow$ S &  Scalar Diagnostic                 \\
246               & $\rightarrow$ U &  U-vector component Diagnostic     \\             & $\rightarrow$ U &  U-vector component Diagnostic     \\
247               & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline             & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline
248    parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\   parse(2)  & $\rightarrow$ U &  C-Grid U-Point                    \\
249               & $\rightarrow$ V &  C-Grid V-Point                    \\             & $\rightarrow$ V &  C-Grid V-Point                    \\
250               & $\rightarrow$ M &  C-Grid Mass Point                 \\             & $\rightarrow$ M &  C-Grid Mass Point                 \\
251               & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline             & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
252    parse(3)   & $\rightarrow$ R &  Not Currently in Use              \\ \hline   parse(3)  & $\rightarrow$   &  Used for Level Integrated output: cumulate levels \\
253    parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline             & $\rightarrow$ r &  same but cumulate product by model level thickness \\
254    parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\             & $\rightarrow$ R &  same but cumulate product by hFac \& level thickness \\ \hline
255               & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline   parse(4)  & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
256    parse(6-8) & $\rightarrow$ C &  3-digit integer corresponding to  \\   parse(5)  & $\rightarrow$ C &  with Counter array                \\
257               &                 &  vector or counter component mate  \\ \hline             & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
258     parse(6-8)&                 &  retired, formerly: 3-digit mate number \\ \hline
259     parse(9)  & $\rightarrow$ U &  model-level plus 1/2  \\
260               & $\rightarrow$ M &  model-level middle  \\
261               & $\rightarrow$ L &  model-level minus 1/2  \\ \hline
262     parse(10) & $\rightarrow$ 0 &  levels = 0  \\
263               & $\rightarrow$ 1 &  levels = 1  \\
264               & $\rightarrow$ R &  levels = Nr  \\
265               & $\rightarrow$ L &  levels = MAX(Nr,NrPhys)  \\
266               & $\rightarrow$ M &  levels = MAX(Nr,NrPhys) - 1  \\
267               & $\rightarrow$ G &  levels = Ground\_level Number \\
268               & $\rightarrow$ I &  levels = sea-Ice\_level Number \\
269               & $\rightarrow$ X &  free levels option (need to be set explicitly)\\ \hline
270  \end{tabular}  \end{tabular}
271  \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}  \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
272  \end{center}  \end{center}
# Line 235  Array & Value & Description \\ Line 275  Array & Value & Description \\
275    
276  \noindent  \noindent
277  As an example, consider a diagnostic whose associated GDIAG parameter is equal  As an example, consider a diagnostic whose associated GDIAG parameter is equal
278  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
279  U-vector component located at the C-grid U-point.  U-vector component located at the C-grid U-point, model mid-level (M)
280  Its corresponding V-component diagnostic is located in Diagnostic \# 002.  with Nr levels (last R).
281    
282  \noindent  \noindent
283  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,
# Line 251  is output. Line 291  is output.
291  \label{sec:diagnostics:usersguide}  \label{sec:diagnostics:usersguide}
292    
293  \noindent  \noindent
294  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}
295  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
296  further steps the user must take to enable the diagnostics package for  further steps the user must take to enable the diagnostics package for
297  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
298  configuration of packages.  A namelist must be supplied in the run directory  configuration of packages.  
299  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,
300    and the file DIAGNOSTICS\_SIZE.h must be included in the
301  code directory.  The steps for defining a new (permanent or experiment-specific  code directory.  The steps for defining a new (permanent or experiment-specific
302  temporary) diagnostic quantity will be outlined later.  temporary) diagnostic quantity will be outlined later.
303    
304  \noindent The namelist will activate a user-defined list of diagnostics quantities  \noindent The namelist in parameter file {\tt data.diagnostics} will activate
305  to be computed, specify the frequency and type of output, the number of levels, and  a user-defined list of diagnostics quantities to be computed,
306  the name of all the separate output files. A sample data.diagnostics namelist file:  specify the frequency and type of output, the number of levels, and
307    the name of all the separate output files.
308    A sample {\tt data.diagnostics} namelist file:
309    
310  \begin{verbatim}  \begin{verbatim}
311  # Diagnostic Package Choices  # Diagnostic Package Choices
312   &diagnostics\_list  #--------------------
313    #  dumpAtLast (logical): always write output at the end of simulation (default=F)
314    #  diag_mnc   (logical): write to NetCDF files (default=useMNC)
315    #--for each output-stream:
316    #  fileName(n) : prefix of the output file name (max 80c long) for outp.stream n
317    #  frequency(n):< 0 : write snap-shot output every |frequency| seconds
318    #               > 0 : write time-average output every frequency seconds
319    #  timePhase(n)     : write at time = timePhase + multiple of |frequency|
320    #    averagingFreq  : frequency (in s) for periodic averaging interval
321    #    averagingPhase : phase     (in s) for periodic averaging interval
322    #    repeatCycle    : number of averaging intervals in 1 cycle
323    #  levels(:,n) : list of levels to write to file (Notes: declared as REAL)
324    #                when this entry is missing, select all common levels of this list
325    #  fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n
326    #                (see "available_diagnostics.log" file for the full list of diags)
327    #  missing_value(n) : missing value for real-type fields in output file "n"
328    #  fileFlags(n)     : specific code (8c string) for output file "n"
329    #--------------------
330     &DIAGNOSTICS_LIST
331      fields(1:2,1) = 'UVEL    ','VVEL    ',
332       levels(1:5,1) = 1.,2.,3.,4.,5.,
333       filename(1) = 'diagout1',
334    frequency(1) = 86400.,    frequency(1) = 86400.,
335     levels(1,1) = 1.,    fields(1:3,2) = 'THETA   ','SALT    ',
336     fields(1,1) = 'RSURF   ',     filename(2) = 'diagout2',
337     filename(1) = 'surface',    fileflags(2) = ' P1     ',
338    frequency(2) = 86400.,    frequency(2) = 3600.,
339     levels(1,2) = 1.,2.,3.,4.,5.,   &
340     fields(1,2) = 'UVEL    ','VVEL    ',  
341     filename(2) = 'diagout1',  #--------------------
342    frequency(3) = 3600.,  # Parameter for Diagnostics of per level statistics:
343     fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE',  #--------------------
344     filename(3) = 'diagout2',  #  diagSt_mnc (logical): write stat-diags to NetCDF files (default=diag_mnc)
345    fileflags(3) = ' P1     ',  #  diagSt_regMaskFile : file containing the region-mask to read-in
346   &end  #  nSetRegMskFile   : number of region-mask sets within the region-mask file
347    #  set_regMask(i)   : region-mask set-index that identifies the region "i"
348    #  val_regMask(i)   : region "i" identifier value in the region mask
349    #--for each output-stream:
350    #  stat_fName(n) : prefix of the output file name (max 80c long) for outp.stream n
351    #  stat_freq(n):< 0 : write snap-shot output every |stat_freq| seconds
352    #               > 0 : write time-average output every stat_freq seconds
353    #  stat_phase(n)    : write at time = stat_phase + multiple of |stat_freq|
354    #  stat_region(:,n) : list of "regions" (default: 1 region only=global)
355    #  stat_fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n
356    #                (see "available_diagnostics.log" file for the full list of diags)
357    #--------------------
358     &DIAG_STATIS_PARMS
359     &
360  \end{verbatim}  \end{verbatim}
361    
362  \noindent  \noindent
# Line 290  the prefix diagout1, does time averaging Line 367  the prefix diagout1, does time averaging
367  fields at output levels 1-5. The names of diagnostics quantities are  fields at output levels 1-5. The names of diagnostics quantities are
368  UVEL and VVEL.  The second set of output files has the prefix  UVEL and VVEL.  The second set of output files has the prefix
369  diagout2, does time averaging every 3600. seconds, includes fields  diagout2, does time averaging every 3600. seconds, includes fields
370  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.  
371    
372  \noindent  \noindent
373  The user must assure that enough computer memory is allocated for the  The user must assure that enough computer memory is allocated for the
374  diagnostics and the output streams selected for a particular  diagnostics and the output streams selected for a particular
375  experiment.  This is acomplished by modifying the file  experiment.  This is accomplished by modifying the file
376  DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.  DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
377  The parameters that should be checked are called numdiags, numlists,  The parameters that should be checked are called numDiags, numLists,
378  numperlist, and diagSt\_size.  numperList, and diagSt\_size.
379    
380  \noindent numdiags (and diagSt\_size): \\  \noindent numDiags (and diagSt\_size): \\
381  \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
382  which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\  which is located in the file
383    \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}
384  and has the form:\\  and has the form:\\
385  \begin{verbatim}  \begin{verbatim}
386        common /diagnostics/        _RL  qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy)
387       &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)        _RL  qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy)
388          COMMON / DIAG_STORE_R / qdiag, qSdiag
389  \end{verbatim}  \end{verbatim}
390  \noindent  \noindent
391  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 393  dimension of a given diagnostic, and the
393  used to identify diagnostic fields and levels combined. In order to  used to identify diagnostic fields and levels combined. In order to
394  minimize the memory requirement of the model for diagnostics, the  minimize the memory requirement of the model for diagnostics, the
395  default GCM executable is compiled with room for only one horizontal  default GCM executable is compiled with room for only one horizontal
396  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
397  enable more than 1 three-dimensional diagnostic, the size of the  enable more than 1 three-dimensional diagnostic, the size of the
398  diagnostics common must be expanded to accomodate the desired  diagnostics common must be expanded to accommodate the desired
399  diagnostics.  This can be accomplished by manually changing the  diagnostics.  This can be accomplished by manually changing the
400  parameter numdiags in the file  parameter numDiags in the file
401  \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.  \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
402  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
403  diagnostics activated for output each multiplied by the number of  diagnostics activated for output each multiplied by the number of
404  levels defined for that diagnostic quantity.  For the above example,  levels defined for that diagnostic quantity.  For the above example,
405  there are 4 multiple level fields, which the diagnostics menu (see  there are 4 multiple level fields, which the diagnostics menu (see
406  below) indicates are defined at the GCM vertical resolution, Nr. The  below) indicates are defined at the GCM vertical resolution, Nr. The
407  value of numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to  value of numDiags in DIAGNOSTICS\_SIZE.h would therefore be equal to
408  4*Nr, or, say 40 if $Nr=10$.  4*Nr, or, say 40 if $Nr=10$.
409    
410  \noindent numlists and numperlist: \\  \noindent numLists and numperList: \\
411  \noindent The parameter numlists must be set greater than or equal to  \noindent The parameter numLists must be set greater than or equal to
412  the number of separate output streams that the user specifies in the  the number of separate output streams that the user specifies in the
413  namelist file data.diagnostics.  The parameter numperlist corresponds  namelist file data.diagnostics.  The parameter numperList corresponds
414  to the number of diagnostics requested in each output stream.  to the maximum number of diagnostics requested per output streams.
415    
416  \noindent  \noindent
417  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
418  field that is desired for a particular experiment, two steps must be  field that is desired for a particular experiment, two steps must be
419  taken. The first is to enable the ``User Diagnostic'' in  taken. The first is to enable the ``User Diagnostic'' in
420  data.diagnostics. This is accomplished by adding one of the ``User  {\tt data.diagnostics}. This is accomplished by adding one of the ``User
421  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
422  fields, or SDIAG1 through SDIAG10 for single level fields) to the  fields, or SDIAG1 through SDIAG10 for single level fields) to the
423  data.diagnostics namelist in one of the output streams. These fields  data.diagnostics namelist in one of the output streams. These fields
424  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
425  to diagnostics\_fill from the subroutine in which the quantity desired  to DIAGNOSTICS\_FILL from the subroutine in which the quantity desired
426  for diagnostic output is computed.  for diagnostic output is computed.
427    
428  \noindent  \noindent
429  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
430  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
431  menu, the subroutine diagnostics\_add2list should be called during the  menu, the subroutine DIAGNOSTICS\_ADDTOLIST should be called during the
432  initialization phase of the main model or package. For the main model,  initialization phase of the main model or package. For the main model,
433  the call should be made from subroutine diagnostics\_main\_init, and  the call should be made from subroutine DIAGNOSTICS\_MAIN\_INIT, and
434  for a package, the call should probably be made from somewhere in the  for a package, the call should probably be made from
435  packages\_init\_fixed sequence (probaby from inside the particular  %somewhere in the PACKAGES\_INIT\_FIXED sequence (probably
436  package's init\_fixed routine). A typical code sequence to set the  from inside the particular package's init\_fixed routine.
437  input arguments to diagnostics\_add2list would look like:  A typical code sequence to set the
438    input arguments to DIAGNOSTICS\_ADDTOLIST would look like:
439    
440  \begin{verbatim}  \begin{verbatim}
441        diagName  = 'THETA   '        diagName  = 'RHOAnoma'
442        diagTitle = 'Potential Temperature (degC,K)'        diagTitle = 'Density Anomaly (=Rho-rhoConst)'
443        diagUnits = 'Degrees K       '        diagUnits = 'kg/m^3          '
444        diagCode  = 'SM      MR      '        diagCode  = 'SMR     MR      '
445        CALL DIAGNOSTICS\_ADD2LIST( diagNum,        CALL DIAGNOSTICS\_ADDTOLIST( diagNum,
446       I          diagName, diagCode, diagUnits, diagTitle, myThid )       I          diagName, diagCode, diagUnits, diagTitle, 0, myThid )
447  \end{verbatim}  \end{verbatim}
448    
449  \noindent If the new diagnostic quantity is associated with either a  \noindent If the new diagnostic quantity is associated with either a
450  vector pair or a diagnostic counter, the diagCode argument must be  vector pair or a diagnostic counter, the diagMate argument must be
451  filled with the proper index for the ``mate''. The output argument  provided with the proper index corresponding to the ``mate''.
452  from diagnostics\_add2list that is called diagNum here contains a  The output argument from DIAGNOSTICS\_ADDTOLIST that is called diagNum here
453  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
454  any point during the run. The sequence number for the next two  any point during the run. The sequence number for the next two
455  diagnostics defined (the two components of the vector pair, for  diagnostics defined (the two components of the vector pair, for
456  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 461  vector fills the ``mate'' part of diagCo
461  sequence for this case would look like:  sequence for this case would look like:
462    
463  \begin{verbatim}  \begin{verbatim}
464        diagName  = 'UVEL    '        diagName  = 'UVEL    '
465        diagTitle = 'Zonal Velocity                '        diagTitle = 'Zonal Component of Velocity (m/s)'
466        diagUnits = 'm / sec         '        diagUnits = 'm/s             '
467        diagCode  = 'SM      MR      '        diagCode  = 'UUR     MR      '
468        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      '        diagMate  = diagNum + 2
469        call diagnostics\_add2list( diagNum,        CALL DIAGNOSTICS_ADDTOLIST( diagNum,
470       I          diagName, diagCode, diagUnits, diagTitle, myThid )       I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
471        diagName  = 'VVEL    '  
472        diagTitle = 'Meridional Velocity           '        diagName  = 'VVEL    '
473        diagUnits = 'm / sec         '        diagTitle = 'Meridional Component of Velocity (m/s)'
474        diagCode  = 'SM      MR      '        diagUnits = 'm/s             '
475        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      '        diagCode  = 'VVR     MR      '
476        call diagnostics\_add2list( diagNum,        diagMate  = diagNum
477       I          diagName, diagCode, diagUnits, diagTitle, myThid )        CALL DIAGNOSTICS_ADDTOLIST( diagNum,
478         I   diagName, diagCode, diagUnits, diagTitle, diagMate, myThid )
479  \end{verbatim}  \end{verbatim}
480    
481  \input{part7/diagnostics-menu.tex}  \input{s_outp_pkgs/text/diagnostics-menu.tex}
482    
483  \newpage  \newpage
484  \noindent For a list of the diagnostic fields available in the  \noindent For a list of the diagnostic fields available in the
# Line 409  in the manual section describing the pac Line 489  in the manual section describing the pac
489  \item aim: \ref{sec:pkg:aim:diagnostics}  \item aim: \ref{sec:pkg:aim:diagnostics}
490  \item exf: \ref{sec:pkg:exf:diagnostics}  \item exf: \ref{sec:pkg:exf:diagnostics}
491  \item gchem: \ref{sec:pkg:gchem:diagnostics}  \item gchem: \ref{sec:pkg:gchem:diagnostics}
492  \item generic\_advdiff: \ref{sec:pkg:generic_advdiff:diagnostics}  \item generic\_advdiff: \ref{sec:pkg:gad:diagnostics}
493  \item gridalt: \ref{sec:pkg:gridalt:diagnostics}  \item gridalt: \ref{sec:pkg:gridalt:diagnostics}
494  \item gmredi: \ref{sec:pkg:gmredi:diagnostics}  \item gmredi: \ref{sec:pkg:gmredi:diagnostics}
495  \item fizhi: \ref{sec:pkg:fizhi:diagnostics}  \item fizhi: \ref{sec:pkg:fizhi:diagnostics}
# Line 419  in the manual section describing the pac Line 499  in the manual section describing the pac
499  \item obcs: \ref{sec:pkg:obcs:diagnostics}  \item obcs: \ref{sec:pkg:obcs:diagnostics}
500  \item thsice: \ref{sec:pkg:thsice:diagnostics}  \item thsice: \ref{sec:pkg:thsice:diagnostics}
501  \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}  \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}
502    \item ptracers: \ref{sec:pkg:ptracers:diagnostics}
503  \end{itemize}  \end{itemize}
504    
505  \subsection{Dos and Donts}  \subsection{Dos and Donts}
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.9
  ViewVC Help
Powered by ViewVC 1.1.22