/[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.2 by edhill, Sat Aug 6 16:28:14 2005 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.  refered 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.  Quantitied
39    refered 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\_fill}: This is the main user interface routine to
56  sent through the argument list.  the diagnostics package. This routine will increment the specified
57    diagnostic quantity with a field sent through the argument list.
58  \noindent  
59  \begin{tabbing}  \begin{verbatim}
60  XXXXXXXXX\=XXXXXX\= \kill          call diagnostics_fill(
61  \>        call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\         &      arrayin, chardiag, levflg, nlevs,
62  \>              bibjflg, bi, bj, myThid) \\         &      bibjflg, bi, bj, myThid )
63  \\  
64  where \>  arrayin  \>= Field to increment diagnostics array \\       where:
65        \>  chardiag \>= Character *8 expression for diag to fill \\          arrayin  = Field to increment diagnostics array
66        \>  levflg   \>= Integer flag for vertical levels: \\          chardiag = Character *8 expression for diag to fill
67        \>           \>= 0 indicates multiple (nlevs) levels incremented \\          levflg   = Integer flag for vertical levels:
68        \>           \>= -1 indicates multiple (nlevs) levels incremented, \\                   = 0 indicates multiple (nlevs) levels incremented
69        \>           \> but in reverse vertical order \\                   = -1 indicates multiple (nlevs) levels incremented,
70        \>           \> positive integer - WHICH single level to increment. \\                       but in reverse vertical order
71        \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg gt 0) \\                       positive integer - WHICH single level to increment.
72        \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\          nlevs    = indicates Number of levels to be filled (1 if levflg gt 0)
73        \>           \>= 0 indicates that the bi-bj loop must be done here \\          bibjflg  = Integer flag to indicate instructions for bi bj loop
74        \>           \>= 1 indicates that the bi-bj loop is done OUTSIDE \\                   = 0 indicates that the bi-bj loop must be done here
75        \>           \>= 2 indicates that the bi-bj loop is done OUTSIDE \\                   = 1 indicates that the bi-bj loop is done OUTSIDE
76        \>           \>    AND that we have been sent a local array \\                   = 2 indicates that the bi-bj loop is done OUTSIDE
77        \>           \>    AND that the array has the shadow regions \\                       AND that we have been sent a local array
78        \>           \>= 3 indicates that the bi-bj loop is done OUTSIDE \\                       AND that the array has the shadow regions
79        \>           \>    AND that we have been sent a local array \\                   = 3 indicates that the bi-bj loop is done OUTSIDE
80        \>           \>    AND that the array has no shadow regions \\                       AND that we have been sent a local array
81        \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\                       AND that the array has no shadow regions
82        \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\          bi       = X-direction process(or) number - used for bibjflg=1-3
83        \>  myThid   \>= Current Thread number \\          bj       = Y-direction process(or) number - used for bibjflg=1-3
84  \end{tabbing}          myThid   = Current Thread number
85    \end{verbatim}
86    
87  \noindent  \noindent
88  {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to  {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to
89  diagnostics\_fill which performs the same functions and has an additional option  diagnostics\_fill which performs the same functions and has an additional option
90  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.
91    
92  \noindent  \begin{verbatim}
93  \begin{tabbing}          call diagnostics_scale_fill(
94  XXXXXXXXX\=XXXXXX\= \kill         &         arrayin, scalefactor, power, chardiag,
95  \>        call diagnostics\_scale\_fill (arrayin, scalefactor, power, chardiag, \\         &         levflg, nlevs, bibjflg, bi, bj, myThid )
96  \>        levflg, nlevs, bibjflg, bi, bj, myThid) \\  
97  \\       where all the arguments are the same as for diagnostics_fill with
98  where \>  All the arguments are the same as for diagnostics\_fill with the addition of: \\       the addition of:
99        \>  scalefactor \>= Factor to scale field \\          scalefactor = Factor to scale field
100        \>  power       \>= Integer power to which to raise the input field \\          power       = Integer power to which to raise the input field
101  \end{tabbing}  \end{verbatim}
102    
103  \noindent  \noindent
104  {\bf diagnostics\_is\_on}: Function call to inquire whether a diagnostic is active  {\bf diagnostics\_is\_on}: Function call to inquire whether a
105  and can be incremented. Useful when there is a computation that must be done locally  diagnostic is active and can be incremented. Useful when there is a
106  before a call to diagnostics\_fill. The call sequence:  computation that must be done locally before a call to
107    diagnostics\_fill. The call sequence:
108  \noindent  
109  \begin{tabbing}  \begin{verbatim}
110  XXXXXXXXX\=XXXXXX\= \kill          flag = diagnostics_is_on( diagName, myThid )
111  \> flag = diagnostics\_is\_on( diagName, myThid )  
112  \\       where:
113  where \>  diagName \>= Character *8 expression for diagnostic \\          diagName = Character *8 expression for diagnostic
114        \>  myThid   \>= Current Thread number \\          myThid   = Current Thread number
115  \end{tabbing}  \end{verbatim}
116    
117  \noindent  \noindent
118  {\bf diagnostics\_get\_pointers}:  This subroutine retrieves the value of a the diagnostics  {\bf diagnostics\_get\_pointers}: This subroutine retrieves the value
119  pointers that other routines require as input - can be useful if the diagnostics common  of a the diagnostics pointers that other routines require as input -
120  blocks are not local to a routine.  can be useful if the diagnostics common blocks are not local to a
121    routine.
122  \noindent  
123  \begin{tabbing}  \begin{verbatim}
124  XXXXXXXXX\=XXXXXX\= \kill          call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid )
125  \> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid )  
126  \\       where:
127  where \>  diagName \>= Character *8 expression of diagnostic \\          diagName = Character *8 expression of diagnostic
128        \>  ipoint   \>= Pointer into qdiag array - from idiag array in common \\          ipoint   = Pointer into qdiag array - from idiag array in common
129        \>  jpoint   \>= Pointer into diagnostics menu - from jdiag array in common \\          jpoint   = Pointer into diagnostics menu - from jdiag array in common
130        \>  myThid   \>= Current Thread number \\          myThid   = Current Thread number
131  \end{tabbing}  \end{verbatim}
132    
133  \noindent  \noindent
134  {\bf getdiag}:  This subroutine retrieves the value of a model diagnostic.  This routine  {\bf getdiag}: This subroutine retrieves the value of a model
135  is particulary useful when called from a user output routine, although it can be called  diagnostic.  This routine is particulary useful when called from a
136  from any routine.  This routine returns the time-averaged value of the diagnostic by  user output routine, although it can be called from any routine.  This
137  dividing the current accumulated diagnostic value by its corresponding counter.  This  routine returns the time-averaged value of the diagnostic by dividing
138  routine does not change the value of the diagnostic itself, that is, it does not replace  the current accumulated diagnostic value by its corresponding counter.
139  the diagnostic with its time-average.  The calling sequence for this routine is givin by:  This routine does not change the value of the diagnostic itself, that
140    is, it does not replace the diagnostic with its time-average.  The
141  \noindent  calling sequence for this routine is givin by:
142  \begin{tabbing}  
143  XXXXXXXXX\=XXXXXX\= \kill  \begin{verbatim}
144  \>        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\          call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid)
145  \\  
146  where \>  lev     \>= Model Level at which the diagnostic is desired \\       where:
147        \>  undef   \>= Fill value to be used when diagnostic is undefined \\          lev     = Model Level at which the diagnostic is desired
148        \>  qtmp    \>= Time-Averaged Diagnostic Output \\          undef   = Fill value to be used when diagnostic is undefined
149        \>  ipoint  \>= Pointer into qdiag array - from idiag array in common \\          qtmp    = Time-Averaged Diagnostic Output
150        \>  mate    \>= Diagnostic mate pointer number \\          ipoint  = Pointer into qdiag array - from idiag array in common
151        \>  bi      \>= X-direction process(or) number \\          mate    = Diagnostic mate pointer number
152        \>  bj      \>= Y-direction process(or) number \\          bi      = X-direction process(or) number
153        \>  myThid  \>= Current Thread number \\          bj      = Y-direction process(or) number
154  \end{tabbing}          myThid  = Current Thread number
155    \end{verbatim}
156  \noindent  
157  {\bf diagnostics\_add2list}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning  \noindent
158  that space is allocated for the diagnostic and the model routines will increment the  {\bf diagnostics\_add2list}: This subroutine enables a diagnostic from
159  diagnostic value during execution.  This routine is the underlying interface routine  the Diagnostic Menu, meaning that space is allocated for the
160  for defining a new permanent diagnostic in the main model or in a package.  The calling sequence is:  diagnostic and the model routines will increment the diagnostic value
161    during execution.  This routine is the underlying interface routine
162  \noindent  for defining a new permanent diagnostic in the main model or in a
163  \begin{tabbing}  package.  The calling sequence is:
164  XXXXXXXXX\=XXXXXX\= \kill  
165  \>        call diagnostics\_add2list( diagNum,diagName, diagCode, \\  \begin{verbatim}
166  \>        diagUnits, diagTitle, myThid ) \\         call diagnostics_add2list( diagNum,diagName, diagCode,
167  \\                                    diagUnits, diagTitle, myThid )
168  where \> diagNum   \>=Diagnostic number - Output from routine \\  
169        \> diagName  \>=character*8 diagnostic name \\       where:
170        \> diagCode  \>=character*16 parsing code (see description of gdiag below) \\         diagNum   = Diagnostic number - Output from routine
171        \> diagUnits \>=Diagnostic units (character*16) \\         diagName  = character*8 diagnostic name
172        \> diagTitle \>=Diagnostic title or long name (up to character*80) \\         diagCode  = character*16 parsing code (see description of gdiag below)
173        \> myThid    \>=Current Thread number \\         diagUnits = Diagnostic units (character*16)
174  \end{tabbing}         diagTitle = Diagnostic title or long name (up to character*80)
175           myThid    = Current Thread number
176  \noindent  \end{verbatim}
177  {\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is  
178  particularly useful when called from user output routines to re-initialize diagnostics  \noindent
179  during the run.  The calling sequence is:  {\bf clrdiag}: This subroutine initializes the values of model
180    diagnostics to zero, and is particularly useful when called from user
181  \noindent  output routines to re-initialize diagnostics during the run.  The
182  \begin{tabbing}  calling sequence is:
183  XXXXXXXXX\=XXXXXX\= \kill  
184  \>        call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\  \begin{verbatim}
185  \\          call diagnostics_clrdiag (jpoint, ipoint, myThid)
186  where \>  jpoint \>= Diagnostic number from menu - from jdiag array \\  
187            ipoint \>= Pointer number into qdiag array - from idiag array \\       where:
188        \>  myThid \>=Current Thread number \\          jpoint = Diagnostic number from menu - from jdiag array
189  \end{tabbing}          ipoint = Pointer number into qdiag array - from idiag array
190            myThid = Current Thread number
191  \noindent  \end{verbatim}
192  The diagnostics are computed at various times and places within the GCM. Because the  
193  MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,  \noindent
194  corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars,  The diagnostics are computed at various times and places within the
195  while others are components of vectors. An internal array is defined which contains  GCM. Because MITgcm may employ a staggered grid, diagnostics may be
196  information concerning various grid attributes of each diagnostic. The GDIAG  computed at grid box centers, corners, or edges, and at the middle or
197  array (in common block \\diagnostics in file DIAGNOSTICS.h) is internally defined as a  edge in the vertical. Some diagnostics are scalars, while others are
198  character*8 variable, and is equivalenced to a character*1 "parse" array in output in  components of vectors. An internal array is defined which contains
199  order to extract the grid-attribute information.  The GDIAG array is described in  information concerning various grid attributes of each diagnostic. The
200  Table \ref{tab:diagnostics:gdiag.tabl}.  GDIAG array (in common block {\tt diagnostics} in file {\tt
201      DIAGNOSTICS.h}) is internally defined as a character*8 variable, and
202    is equivalenced to a character*1 "parse" array in output in order to
203    extract the grid-attribute information.  The GDIAG array is described
204    in Table \ref{tab:diagnostics:gdiag.tabl}.
205    
206  \begin{table}  \begin{table}
207  \caption{Diagnostic Parsing Array}  \caption{Diagnostic Parsing Array}
# Line 235  interpolations are done at the time of o Line 247  interpolations are done at the time of o
247  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
248  is output.  is output.
249    
250  \subsubsection{Usage Notes}  \subsection{Usage Notes}
251  \label{sec:diagnostics:usersguide}  \label{sec:diagnostics:usersguide}
252    
253  \noindent  \noindent
# Line 252  temporary) diagnostic quantity will be o Line 264  temporary) diagnostic quantity will be o
264  to be computed, specify the frequency and type of output, the number of levels, and  to be computed, specify the frequency and type of output, the number of levels, and
265  the name of all the separate output files. A sample data.diagnostics namelist file:  the name of all the separate output files. A sample data.diagnostics namelist file:
266    
267  \noindent  \begin{verbatim}
268  $\#$ Diagnostic Package Choices \\  # Diagnostic Package Choices
269   $\&$diagnostics\_list \\   &diagnostics\_list
270    frequency(1) = 86400., \ \\    frequency(1) = 86400.,
271     levels(1,1) = 1., \ \\     levels(1,1) = 1.,
272     fields(1,1) = 'RSURF   ', \ \\     fields(1,1) = 'RSURF   ',
273     filename(1) = 'surface', \ \\     filename(1) = 'surface',
274    frequency(2) = 86400., \ \\    frequency(2) = 86400.,
275     levels(1,2) = 1.,2.,3.,4.,5., \ \\     levels(1,2) = 1.,2.,3.,4.,5.,
276     fields(1,2) = 'UVEL    ','VVEL    ', \ \\     fields(1,2) = 'UVEL    ','VVEL    ',
277     filename(2) = 'diagout1', \ \\     filename(2) = 'diagout1',
278    frequency(3) = 3600., \ \\    frequency(3) = 3600.,
279     fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', \ \\     fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE',
280     filename(3) = 'diagout2', \ \\     filename(3) = 'diagout2',
281    fileflags(3) = ' P1     ', \ \\    fileflags(3) = ' P1     ',
282   $\&$end \ \\   &end
283    \end{verbatim}
284  \noindent  
285  In this example, there are two output files that will be generated  \noindent
286  for each tile and for each output time. The first set of output files  In this example, there are two output files that will be generated for
287  has the prefix diagout1, does time averaging every 86400. seconds,  each tile and for each output time. The first set of output files has
288  (frequency is 86400.), and will write fields which are multiple-level  the prefix diagout1, does time averaging every 86400. seconds,
289  fields at output levels 1-5. The names of diagnostics quantities are  (frequency is 86400.), and will write fields which are multiple-level
290  UVEL and VVEL.  The second set of output files  fields at output levels 1-5. The names of diagnostics quantities are
291  has the prefix diagout2, does time averaging every 3600. seconds,  UVEL and VVEL.  The second set of output files has the prefix
292  includes fields which are multiple-level fields, levels output are 1-5,  diagout2, does time averaging every 3600. seconds, includes fields
293  and the names of diagnostics quantities are THETA and SALT.  which are multiple-level fields, levels output are 1-5, and the names
294    of diagnostics quantities are THETA and SALT.
295  \noindent  
296  The user must assure that enough computer memory is allocated for the diagnostics  \noindent
297  and the output streams selected for a particular experiment.  This is acomplished by  The user must assure that enough computer memory is allocated for the
298  modifying the file DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.  diagnostics and the output streams selected for a particular
299  The parameters that should be checked are called numdiags, numlists, numperlist, and  experiment.  This is acomplished by modifying the file
300  diagSt\_size.  DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
301    The parameters that should be checked are called numdiags, numlists,
302    numperlist, and diagSt\_size.
303    
304  \noindent numdiags (and diagSt\_size): \\  \noindent numdiags (and diagSt\_size): \\
305  \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
306  which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\  which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\
307  and has the form:\\  and has the form:\\
308  common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) \\  \begin{verbatim}
309  \noindent        common /diagnostics/
310  The first two-dimensions of qdiag correspond to the horizontal dimension of a given diagnostic,       &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
311  and the third dimension of qdiag is used to identify diagnostic fields and levels combined. In  \end{verbatim}
312  order to minimize the memory requirement of the model for diagnostics, the default GCM  \noindent
313  executable is compiled with room for only one horizontal diagnostic array, or with  The first two-dimensions of qdiag correspond to the horizontal
314  numdiags set to Nr. In order for the User to enable more than 1 three-dimensional diagnostic,  dimension of a given diagnostic, and the third dimension of qdiag is
315  the size of the diagnostics common must be expanded to accomodate the desired diagnostics.  used to identify diagnostic fields and levels combined. In order to
316  This can be accomplished by manually changing the parameter numdiags in the  minimize the memory requirement of the model for diagnostics, the
317  file \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.  default GCM executable is compiled with room for only one horizontal
318  numdiags should be set greater than or equal to the sum of all the diagnostics activated  diagnostic array, or with numdiags set to Nr. In order for the User to
319  for output each multiplied by the number of levels defined for that diagnostic quantity.  enable more than 1 three-dimensional diagnostic, the size of the
320  For the above example, there are 4 multiple level fields, which the diagnostics menu  diagnostics common must be expanded to accomodate the desired
321  (see below) indicates are defined at the GCM vertical resolution, Nr. The value of  diagnostics.  This can be accomplished by manually changing the
322  numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to 4*Nr, or, say 40 if $Nr=10$.  parameter numdiags in the file
323    \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
324    numdiags should be set greater than or equal to the sum of all the
325    diagnostics activated for output each multiplied by the number of
326    levels defined for that diagnostic quantity.  For the above example,
327    there are 4 multiple level fields, which the diagnostics menu (see
328    below) indicates are defined at the GCM vertical resolution, Nr. The
329    value of numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to
330    4*Nr, or, say 40 if $Nr=10$.
331    
332  \noindent numlists and numperlist: \\  \noindent numlists and numperlist: \\
333  \noindent The parameter numlists must be set greater than or equal to the number of  \noindent The parameter numlists must be set greater than or equal to
334  separate output streams that the user specifies in the namelist file data.diagnostics.  the number of separate output streams that the user specifies in the
335  The parameter numperlist corresponds to the number of diagnostics requested in each  namelist file data.diagnostics.  The parameter numperlist corresponds
336  output stream.  to the number of diagnostics requested in each output stream.
337    
338  \noindent  \noindent
339  In order to define and include as part of the diagnostic output any field  In order to define and include as part of the diagnostic output any
340  that is desired for a particular experiment, two steps must be taken. The  field that is desired for a particular experiment, two steps must be
341  first is to enable the ``User Diagnostic'' in data.diagnostics. This is  taken. The first is to enable the ``User Diagnostic'' in
342  accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through  data.diagnostics. This is accomplished by adding one of the ``User
343  UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level  Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
344  fields) to the data.diagnostics namelist in one of the output streams. These  fields, or SDIAG1 through SDIAG10 for single level fields) to the
345  fields are listed in the diagnostics menu. The second step is to  data.diagnostics namelist in one of the output streams. These fields
346  add a call to diagnostics\_fill from the subroutine in which the quantity  are listed in the diagnostics menu. The second step is to add a call
347  desired for diagnostic output is computed.  to diagnostics\_fill from the subroutine in which the quantity desired
348    for diagnostic output is computed.
349  \noindent  
350  In order to add a new diagnostic to the permanent set of diagnostics that the  \noindent
351  main model or any package contains as part of its diagnostics menu, the subroutine  In order to add a new diagnostic to the permanent set of diagnostics
352  diagnostics\_add2list should be called during the initialization phase of the  that the main model or any package contains as part of its diagnostics
353  main model or package. For the main model, the call should be made from  menu, the subroutine diagnostics\_add2list should be called during the
354  subroutine diagnostics\_main\_init, and for a package, the call should probably  initialization phase of the main model or package. For the main model,
355  be made from somewhere in the packages\_init\_fixed sequence (probaby from inside  the call should be made from subroutine diagnostics\_main\_init, and
356  the particular package's init\_fixed routine). A typical code sequence to set the  for a package, the call should probably be made from somewhere in the
357    packages\_init\_fixed sequence (probaby from inside the particular
358    package's init\_fixed routine). A typical code sequence to set the
359  input arguments to diagnostics\_add2list would look like:  input arguments to diagnostics\_add2list would look like:
360    
361  \noindent  \begin{verbatim}
362  \begin{tabbing}        diagName  = 'THETA   '
363  XXXXXXXXX\=XXXXXX\= \kill        diagTitle = 'Potential Temperature (degC,K)'
364  \>      diagName  = 'THETA   ' \\        diagUnits = 'Degrees K       '
365  \>      diagTitle = 'Potential Temperature (degC,K)' \\        diagCode  = 'SM      MR      '
366  \>      diagUnits = 'Degrees K       ' \\        CALL DIAGNOSTICS\_ADD2LIST( diagNum,
367  \>      diagCode  = 'SM      MR      ' \\       I          diagName, diagCode, diagUnits, diagTitle, myThid )
368  \>      CALL DIAGNOSTICS\_ADD2LIST( diagNum, \\  \end{verbatim}
369  \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\  
370  \\  \noindent If the new diagnostic quantity is associated with either a
371  \end{tabbing}  vector pair or a diagnostic counter, the diagCode argument must be
372    filled with the proper index for the ``mate''. The output argument
373  \noindent If the new diagnostic quantity is associated with either a vector  from diagnostics\_add2list that is called diagNum here contains a
374  pair or a diagnostic counter, the diagCode argument must be filled with the  running total of the number of diagnostics defined in the code up to
375  proper index for the ``mate''. The output argument from diagnostics\_add2list  any point during the run. The sequence number for the next two
376  that is called diagNum here contains a running total of the number of diagnostics  diagnostics defined (the two components of the vector pair, for
377  defined in the code up to any point during the run. The sequence number for the  instance) will be diagNum+1 and diagNum+2. The definition of the first
378  next two diagnostics defined (the two components of the vector pair, for instance)  component of the vector pair must fill the ``mate'' segment of the
379  will be diagNum+1 and diagNum+2. The definition of the first component of the vector  diagCode as diagnostic number diagNum+2.  Since the subroutine
380  pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2.  increments diagNum, the definition of the second component of the
381  Since the subroutine increments diagNum, the definition of the second component of  vector fills the ``mate'' part of diagCode with diagNum. A code
382  the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for  sequence for this case would look like:
383  this case would look like:  
384    \begin{verbatim}
385  \noindent        diagName  = 'UVEL    '
386  \begin{tabbing}        diagTitle = 'Zonal Velocity                '
387  XXXXXXXXX\=XXXXXX\= \kill        diagUnits = 'm / sec         '
388  \>      diagName  = 'UVEL    ' \\        diagCode  = 'SM      MR      '
389  \>      diagTitle = 'Zonal Velocity                ' \\        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      '
390  \>      diagUnits = 'm / sec         ' \\        call diagnostics\_add2list( diagNum,
391  \>      diagCode  = 'SM      MR      ' \\       I          diagName, diagCode, diagUnits, diagTitle, myThid )
392  \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' \\        diagName  = 'VVEL    '
393  \>      call diagnostics\_add2list( diagNum, \\        diagTitle = 'Meridional Velocity           '
394  \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\        diagUnits = 'm / sec         '
395  \>      diagName  = 'VVEL    ' \\        diagCode  = 'SM      MR      '
396  \>      diagTitle = 'Meridional Velocity           ' \\        write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      '
397  \>      diagUnits = 'm / sec         ' \\        call diagnostics\_add2list( diagNum,
398  \>      diagCode  = 'SM      MR      ' \\       I          diagName, diagCode, diagUnits, diagTitle, myThid )
399  \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' \\  \end{verbatim}
 \>      call diagnostics\_add2list( diagNum, \\  
 \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\  
 \\  
 \end{tabbing}  
400    
401  \input{part7/diagnostics-menu.tex}  \input{part7/diagnostics-menu.tex}
402    
# Line 387  in the manual section describing the pac Line 407  in the manual section describing the pac
407    
408  \filelink{part6/fizhi-diagnostics-menu.tex}{pkg-fizhi-fizhi-diagnostics-menu.tex}  \filelink{part6/fizhi-diagnostics-menu.tex}{pkg-fizhi-fizhi-diagnostics-menu.tex}
409    
410  \subsubsection{Dos and Donts}  \subsection{Dos and Donts}
411    
412  \subsubsection{Diagnostics Reference}  \subsection{Diagnostics Reference}
413    
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2
  ViewVC Help
Powered by ViewVC 1.1.22