/[MITgcm]/manual/s_phys_pkgs/diagnostics.tex
ViewVC logotype

Diff of /manual/s_phys_pkgs/diagnostics.tex

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

revision 1.10 by molod, Thu Jul 14 20:58:20 2005 UTC revision 1.11 by molod, Fri Jul 15 18:58:21 2005 UTC
# Line 20  diagnostic output and defining new diagn Line 20  diagnostic output and defining new diagn
20  \ref{sec:diagnostics:usersguide} of this document.  \ref{sec:diagnostics:usersguide} of this document.
21    
22  \noindent  \noindent
23  The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within  The Diagnostic Menu in this section of the manual is a listing of diagnostic quantities available
24  the GCM. Once a diagnostic is enabled, the GCM will continually increment an array  within the main (dynamics) part of the GCM. Additional diagnostic quantities, defined within the
25  specifically allocated for that diagnostic whenever the appropriate quantity is computed.    different GCM packages, are available and are listed in the diagnostic menu subsection of
26  A counter is defined which records how many times each diagnostic quantity has been  the manual section associated with each relevant package. Once a diagnostic is enabled, the
27  incremented.  Several special diagnostics are included in the menu. Quantities refered to  GCM will continually increment an array specifically allocated for that diagnostic whenever the
28  as ``Counter Diagnostics'', are defined for selected diagnostics which record the  appropriate quantity is computed.  A counter is defined which records how many times each diagnostic
29    quantity has been incremented.  Several special diagnostics are included in the menu. Quantities
30    refered to as ``Counter Diagnostics'', are defined for selected diagnostics which record the
31  frequency at which a diagnostic is incremented separately for each model grid location.  frequency at which a diagnostic is incremented separately for each model grid location.
32  Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate  Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate
33  defining new diagnostics for a particular experiment.  defining new diagnostics for a particular experiment.
# Line 37  Not relevant. Line 39  Not relevant.
39  \label{sec:diagnostics:diagover}  \label{sec:diagnostics:diagover}
40    
41  \noindent  \noindent
 The diagnostics are computed at various times and places within the GCM. Because the  
 MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,  
 corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars,  
 while others are components of vectors. An internal array is defined which contains  
 information concerning various grid attributes of each diagnostic. The GDIAG  
 array (in common block \\diagnostics in file diagnostics.h) is internally defined as a  
 character*8 variable, and is equivalenced to a character*1 "parse" array in output in  
 order to extract the grid-attribute information.  The GDIAG array is described in  
 Table \ref{tab:diagnostics:gdiag.tabl}.  
   
 \begin{table}  
 \caption{Diagnostic Parsing Array}  
 \label{tab:diagnostics:gdiag.tabl}  
 \begin{center}  
 \begin{tabular}{ |c|c|l| }  
 \hline  
 \multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\  
 \hline  
 \hline  
 Array & Value & Description \\  
 \hline  
   parse(1)   & $\rightarrow$ S &  Scalar Diagnostic                 \\  
              & $\rightarrow$ U &  U-vector component Diagnostic     \\  
              & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline  
   parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\  
              & $\rightarrow$ V &  C-Grid V-Point                    \\  
              & $\rightarrow$ M &  C-Grid Mass Point                 \\  
              & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline  
   parse(3)   & $\rightarrow$ R &  Not Currently in Use              \\ \hline  
   parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline  
   parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\  
              & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline  
   parse(6-8) & $\rightarrow$ C &  3-digit integer corresponding to  \\  
              &                 &  vector or counter component mate  \\ \hline  
 \end{tabular}  
 \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}  
 \end{center}  
 \end{table}  
   
   
 \noindent  
 As an example, consider a diagnostic whose associated GDIAG parameter is equal  
 to ``UU  002''.  From GDIAG we can determine that this diagnostic is a  
 U-vector component located at the C-grid U-point.  
 Its corresponding V-component diagnostic is located in Diagnostic \# 002.  
   
   
 \noindent  
 In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,  
 C-grid location, etc.) defined internally.  The Output routines use this information  
 in order to determine what type of transformations need to be performed.  Any  
 interpolations are done at the time of output rather than during each model step.  
 In this way the User has flexibility in determining the type of gridded data which  
 is output.  
   
   
 \noindent  
42  There are several utilities within the GCM available to users to enable, disable,  There are several utilities within the GCM available to users to enable, disable,
43  clear, write and retrieve model diagnostics, and may be called from any routine.    clear, write and retrieve model diagnostics, and may be called from any routine.  
44  The available utilities and the CALL sequences are listed below.  The available utilities and the CALL sequences are listed below.
45    
   
46  \noindent  \noindent
47  {\bf fill\_diagnostics}:  This routine will increment the specified diagnostic  {\bf diagnostics\_fill}:  This is the main user interface routine to the diagnostics
48  quantity with a field sent through the argument list.  package. This routine will increment the specified diagnostic quantity with a field
49    sent through the argument list.
50    
51  \noindent  \noindent
52  \begin{tabbing}  \begin{tabbing}
53  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
54  \>        call fill\_diagnostics (myThid, chardiag, levflg, nlevs, \\  \>        call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\
55                  bibjflg, bi, bj, arrayin) \\  \>              bibjflg, bi, bj, myThid) \\
56  \\  \\
57  where \>  myThid   \>= Current Process(or) \\  where \>  arrayin  \>= Field to increment diagnostics array \\
58        \>  chardiag \>= Character *8 expression for diag to fill \\        \>  chardiag \>= Character *8 expression for diag to fill \\
59        \>  levflg   \>= Integer flag for vertical levels: \\        \>  levflg   \>= Integer flag for vertical levels: \\
60        \>           \> 0 indicates multiple levels incremented in qdiag \\        \>           \>= 0 indicates multiple (nlevs) levels incremented \\
61        \>           \> non-0 (any integer) - WHICH single level to increment. \\        \>           \>= -1 indicates multiple (nlevs) levels incremented, \\
62        \>           \> negative integer - the input data array is single-leveled \\        \>           \> but in reverse vertical order \\
63        \>           \> positive integer - the input data array is multi-leveled \\        \>           \> positive integer - WHICH single level to increment. \\
64        \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg <> 0) \\        \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg gt 0) \\
       \>           \> positive: fill in "nlevs" levels in the same order as \\  
       \>           \> the input array \\  
       \>           \> negative: fill in -nlevs levels in reverse order. \\  
65        \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\        \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\
66        \>           \> 0 indicates that the bi-bj loop must be done here \\        \>           \>= 0 indicates that the bi-bj loop must be done here \\
67        \>           \> 1 indicates that the bi-bj loop is done OUTSIDE \\        \>           \>= 1 indicates that the bi-bj loop is done OUTSIDE \\
68        \>           \> 2 indicates that the bi-bj loop is done OUTSIDE \\        \>           \>= 2 indicates that the bi-bj loop is done OUTSIDE \\
       \>           \>    AND that we have been sent a local array \\  
       \>           \> 3 indicates that the bi-bj loop is done OUTSIDE \\  
69        \>           \>    AND that we have been sent a local array \\        \>           \>    AND that we have been sent a local array \\
70        \>           \>    AND that the array has the shadow regions \\        \>           \>    AND that the array has the shadow regions \\
71          \>           \>= 3 indicates that the bi-bj loop is done OUTSIDE \\
72          \>           \>    AND that we have been sent a local array \\
73          \>           \>    AND that the array has no shadow regions \\
74        \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\        \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\
75        \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\        \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\
76        \>  arrayin  \>= Field to increment diagnostics array \\        \>  myThid   \>= Current Thread number \\
77  \end{tabbing}  \end{tabbing}
78    
79    \noindent
80    {\bf diagnostics\_scale\_fill}:  This is a possible alternative routine to
81    diagnostics\_fill which performs the same functions and has an additional option
82    to scale the field before filling or raise the field to a power before filling.
83    
84  \noindent  \noindent
85  {\bf setdiag}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning  \begin{tabbing}
86  that space is allocated for the diagnostic and the model routines will increment the  XXXXXXXXX\=XXXXXX\= \kill
87  diagnostic value during execution.  This routine is the underlying interface  \>        call diagnostics\_scale\_fill (arrayin, scalefactor, power, chardiag, \\
88  between the user and the desired diagnostic.  The diagnostic is referenced by its diagnostic  \>        levflg, nlevs, bibjflg, bi, bj, myThid) \\
89  number from the menu, and its calling sequence is given by:  \\
90    where \>  All the arguments are the same as for diagnostics\_fill with the addition of: \\
91          \>  scalefactor \>= Factor to scale field \\
92          \>  power       \>= Integer power to which to raise the input field \\
93    \end{tabbing}
94    
95    \noindent
96    {\bf diagnostics\_is\_on}: Function call to inquire whether a diagnostic is active
97    and can be incremented. Useful when there is a computation that must be done locally
98    before a call to diagnostics\_fill. The call sequence:
99    
100    \noindent
101    \begin{tabbing}
102    XXXXXXXXX\=XXXXXX\= \kill
103    \> flag = diagnostics\_is\_on( diagName, myThid )
104    \\
105    where \>  diagName \>= Character *8 expression for diagnostic \\
106          \>  myThid   \>= Current Thread number \\
107    \end{tabbing}
108    
109    \noindent
110    {\bf diagnostics\_get\_pointers}:  This subroutine retrieves the value of a the diagnostics
111    pointers that other routines require as input - can be useful if the diagnostics common
112    blocks are not local to a routine.
113    
114  \noindent  \noindent
115  \begin{tabbing}  \begin{tabbing}
116  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
117  \>        call setdiag (num) \\  \> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid )
118  \\  \\
119  where \>  num   \>= Diagnostic number from menu \\  where \>  diagName \>= Character *8 expression of diagnostic \\
120          \>  ipoint   \>= Pointer into qdiag array - from idiag array in common \\
121          \>  jpoint   \>= Pointer into diagnostics menu - from jdiag array in common \\
122          \>  myThid   \>= Current Thread number \\
123  \end{tabbing}  \end{tabbing}
124    
125  \noindent  \noindent
# Line 161  the diagnostic with its time-average.  T Line 133  the diagnostic with its time-average.  T
133  \noindent  \noindent
134  \begin{tabbing}  \begin{tabbing}
135  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
136  \>        call getdiag (lev,num,qtmp,undef) \\  \>        call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\
137  \\  \\
138  where \>  lev   \>= Model Level at which the diagnostic is desired \\  where \>  lev     \>= Model Level at which the diagnostic is desired \\
139        \>  num   \>= Diagnostic number from menu \\        \>  undef   \>= Fill value to be used when diagnostic is undefined \\
140        \>  qtmp  \>= Time-Averaged Diagnostic Output \\        \>  qtmp    \>= Time-Averaged Diagnostic Output \\
141        \>  undef \>= Fill value to be used when diagnostic is undefined \\        \>  ipoint  \>= Pointer into qdiag array - from idiag array in common \\
142          \>  mate    \>= Diagnostic mate pointer number \\
143          \>  bi      \>= X-direction process(or) number \\
144          \>  bj      \>= Y-direction process(or) number \\
145          \>  myThid  \>= Current Thread number \\
146  \end{tabbing}  \end{tabbing}
147    
148  \noindent  \noindent
149  {\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is  {\bf diagnostics\_add2list}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning
150  particularly useful when called from user output routines to re-initialize diagnostics  that space is allocated for the diagnostic and the model routines will increment the
151  during the run.  The calling sequence is:  diagnostic value during execution.  This routine is the underlying interface routine
152    for defining a new permanent diagnostic in the main model or in a package.  The calling sequence is:
153    
154  \noindent  \noindent
155  \begin{tabbing}  \begin{tabbing}
156  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
157  \>        call clrdiag (num) \\  \>        call diagnostics\_add2list( diagNum,diagName, diagCode, \\
158    \>        diagUnits, diagTitle, myThid ) \\
159  \\  \\
160  where \>  num   \>= Diagnostic number from menu \\  where \> diagNum   \>=Diagnostic number - Output from routine \\
161          \> diagName  \>=character*8 diagnostic name \\
162          \> diagCode  \>=character*16 parsing code (see description of gdiag below) \\
163          \> diagUnits \>=Diagnostic units (character*16) \\
164          \> diagTitle \>=Diagnostic title or long name (up to character*80) \\
165          \> myThid    \>=Current Thread number \\
166  \end{tabbing}  \end{tabbing}
167    
168  \noindent  \noindent
169  {\bf zapdiag}:  This entry into subroutine SETDIAG disables model diagnostics, meaning  {\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is
170  that the diagnostic is no longer available to the user.  The memory previously allocated  particularly useful when called from user output routines to re-initialize diagnostics
171  to the diagnostic is released when ZAPDIAG is invoked.  The calling sequence is given by:  during the run.  The calling sequence is:
172    
173  \noindent  \noindent
174  \begin{tabbing}  \begin{tabbing}
175  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
176  \>        call zapdiag (NUM) \\  \>        call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\
177  \\  \\
178  where \>  num   \>= Diagnostic number from menu \\  where \>  jpoint \>= Diagnostic number from menu - from jdiag array \\
179              ipoint \>= Pointer number into qdiag array - from idiag array \\
180          \>  myThid \>=Current Thread number \\
181  \end{tabbing}  \end{tabbing}
182    
183    \noindent
184    The diagnostics are computed at various times and places within the GCM. Because the
185    MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,
186    corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars,
187    while others are components of vectors. An internal array is defined which contains
188    information concerning various grid attributes of each diagnostic. The GDIAG
189    array (in common block \\diagnostics in file diagnostics.h) is internally defined as a
190    character*8 variable, and is equivalenced to a character*1 "parse" array in output in
191    order to extract the grid-attribute information.  The GDIAG array is described in
192    Table \ref{tab:diagnostics:gdiag.tabl}.
193    
194    \begin{table}
195    \caption{Diagnostic Parsing Array}
196    \label{tab:diagnostics:gdiag.tabl}
197    \begin{center}
198    \begin{tabular}{ |c|c|l| }
199    \hline
200    \multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\
201    \hline
202    \hline
203    Array & Value & Description \\
204    \hline
205      parse(1)   & $\rightarrow$ S &  Scalar Diagnostic                 \\
206                 & $\rightarrow$ U &  U-vector component Diagnostic     \\
207                 & $\rightarrow$ V &  V-vector component Diagnostic     \\ \hline
208      parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\
209                 & $\rightarrow$ V &  C-Grid V-Point                    \\
210                 & $\rightarrow$ M &  C-Grid Mass Point                 \\
211                 & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
212      parse(3)   & $\rightarrow$ R &  Not Currently in Use              \\ \hline
213      parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
214      parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\
215                 & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
216      parse(6-8) & $\rightarrow$ C &  3-digit integer corresponding to  \\
217                 &                 &  vector or counter component mate  \\ \hline
218    \end{tabular}
219    \addcontentsline{lot}{section}{Table 3:  Diagnostic Parsing Array}
220    \end{center}
221    \end{table}
222    
 \subsection{Usage Notes}  
 \label{sec:diagnostics:usersguide}  
223    
224  \noindent  \noindent
225  We begin this section with a discussion on the manner in which computer  As an example, consider a diagnostic whose associated GDIAG parameter is equal
226  memory is allocated for diagnostics. All GCM diagnostic quantities are stored in the  to ``UU  002''.  From GDIAG we can determine that this diagnostic is a
227  single diagnostic array QDIAG which is located in the file \\  U-vector component located at the C-grid U-point.
228  \filelink{pkg/diagnostics/diagnostics.h}{pkg-diagnostics-diagnostics.h}.  Its corresponding V-component diagnostic is located in Diagnostic \# 002.
 and has the form:  
   
 common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)  
229    
230  \noindent  \noindent
231  where numdiags is an Integer variable which should be set equal to the number of  In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,
232  enabled diagnostics, and qdiag is a three-dimensional array.  The first two-dimensions  C-grid location, etc.) defined internally.  The Output routines use this information
233  of qdiag correspond to the horizontal dimension of a given diagnostic, while the third  in order to determine what type of transformations need to be performed.  Any
234  dimension of qdiag is used to identify diagnostic fields and levels combined. In order  interpolations are done at the time of output rather than during each model step.
235  to minimize the memory requirement of the model for diagnostics, the default GCM  In this way the User has flexibility in determining the type of gridded data which
236  executable is compiled with room for only one horizontal diagnostic array, or with  is output.
237  numdiags set to 1. In order for the User to enable more than 1 two-dimensional diagnostic,  
238  the size of the diagnostics common must be expanded to accomodate the desired diagnostics.  \subsection{Usage Notes}
239  This can be accomplished by manually changing the parameter numdiags in the  \label{sec:diagnostics:usersguide}
 file \filelink{pkg/diagnostics/diagnostics\_SIZE.h}{pkg-diagnostics-diagnostics\_SIZE.h}.  
 numdiags should be set greater than or equal to the sum of all the diagnostics activated  
 for output each multiplied by the number of levels defined for that diagnostic quantity.  
 This is illustrated in the example below:  
240    
241  \noindent  \noindent
242  To use the diagnostics package, other than enabling it in packages.conf  To use the diagnostics package, other than enabling it in packages.conf
243  and turning the usediagnostics flag in data.pkg to .TRUE., a namelist  and turning the usediagnostics flag in data.pkg to .TRUE., there are two
244  must be supplied in the run directory called data.diagnostics. The namelist  further steps the user must take to enable the diagnostics package for
245  will activate a user-defined list of diagnostics quantities to be computed,  output of quantities that are already defined in the GCM under an experiment's
246  specify the frequency of output, the number of levels, and the name of  configuration of packages.  A namelist must be supplied in the run directory
247  up to 10 separate output files. A sample data.diagnostics namelist file:  called data.diagnostics, and the file DIAGNOSTICS\_SIZE.h must be included in the
248    code directory.  The steps for defining a new (permanent or experiment-specific
249    temporary) diagnostic quantity will be outlined later.
250    
251    \noindent The namelist will activate a user-defined list of diagnostics quantities
252    to be computed, specify the frequency and type of output, the number of levels, and
253    the name of all the separate output files. A sample data.diagnostics namelist file:
254    
255  \noindent  \noindent
256  $\#$ Diagnostic Package Choices \\  $\#$ Diagnostic Package Choices \\
257   $\&$diagnostics\_list \\   $\&$diagnostics\_list \\
258    frequency(1) = 10, \ \\    frequency(1) = 86400., \ \\
259     levels(1,1) = 1.,2.,3.,4.,5., \ \\     levels(1,1) = 1., \ \\
260     fields(1,1) = 'UVEL    ','VVEL    ', \ \\     fields(1,1) = 'RSURF   ', \ \\
261     filename(1) = 'diagout1', \ \\     filename(1) = 'surface', \ \\
262    frequency(2) = 100, \ \\    frequency(2) = 86400., \ \\
263     levels(1,2) = 1.,2.,3.,4.,5., \ \\     levels(1,2) = 1.,2.,3.,4.,5., \ \\
264     fields(1,2) = 'THETA   ','SALT    ', \ \\     fields(1,2) = 'UVEL    ','VVEL    ', \ \\
265     filename(2) = 'diagout2', \ \\     filename(2) = 'diagout1', \ \\
266      frequency(3) = 3600., \ \\
267       fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', \ \\
268       filename(3) = 'diagout2', \ \\
269      fileflags(3) = ' P1     ', \ \\
270   $\&$end \ \\   $\&$end \ \\
271    
272  \noindent  \noindent
273  In this example, there are two output files that will be generated  In this example, there are two output files that will be generated
274  for each tile and for each output time. The first set of output files  for each tile and for each output time. The first set of output files
275  has the prefix diagout1, does time averaging every 10 time steps  has the prefix diagout1, does time averaging every 86400. seconds,
276  (frequency is 10), they will write fields which are multiple-level  (frequency is 86400.), and will write fields which are multiple-level
277  fields and output levels 1-5. The names of diagnostics quantities are  fields at output levels 1-5. The names of diagnostics quantities are
278  UVEL and VVEL.  The second set of output files  UVEL and VVEL.  The second set of output files
279  has the prefix diagout2, does time averaging every 100 time steps,  has the prefix diagout2, does time averaging every 3600. seconds,
280  they include fields which are multiple-level fields, levels output are 1-5,  includes fields which are multiple-level fields, levels output are 1-5,
281  and the names of diagnostics quantities are THETA and SALT.  and the names of diagnostics quantities are THETA and SALT.
282    
283  \noindent  \noindent
284    The user must assure that enough computer memory is allocated for the diagnostics
285    and the output streams selected for a particular experiment.  This is acomplished by
286    modifying the file DIAGNOSTICS\_SIZE.h and including it in the experiment code directory.
287    The parameters that should be checked are called numdiags, numlists, numperlist, and
288    diagSt\_size.
289    
290    \noindent numdiags (and diagSt\_size): \\
291    \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG
292    which is located in the file \\ \filelink{pkg/diagnostics/diagnostics.h}{pkg-diagnostics-diagnostics.h}.\\
293    and has the form:\\
294    common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) \\
295    \noindent
296    The first two-dimensions of qdiag correspond to the horizontal dimension of a given diagnostic,
297    and the third dimension of qdiag is used to identify diagnostic fields and levels combined. In
298    order to minimize the memory requirement of the model for diagnostics, the default GCM
299    executable is compiled with room for only one horizontal diagnostic array, or with
300    numdiags set to Nr. In order for the User to enable more than 1 three-dimensional diagnostic,
301    the size of the diagnostics common must be expanded to accomodate the desired diagnostics.
302    This can be accomplished by manually changing the parameter numdiags in the
303    file \filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}.
304    numdiags should be set greater than or equal to the sum of all the diagnostics activated
305    for output each multiplied by the number of levels defined for that diagnostic quantity.
306    For the above example, there are 4 multiple level fields, which the diagnostics menu
307    (see below) indicates are defined at the GCM vertical resolution, Nr. The value of
308    numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to 4*Nr, or, say 40 if $Nr=10$.
309    
310    \noindent numlists and numperlist: \\
311    \noindent The parameter numlists must be set greater than or equal to the number of
312    separate output streams that the user specifies in the namelist file data.diagnostics.
313    The parameter numperlist corresponds to the number of diagnostics requested in each
314    output stream.
315    
316    \noindent
317  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 field
318  that is desired for a particular experiment, two steps must be taken. The  that is desired for a particular experiment, two steps must be taken. The
319  first is to enable the ``User Diagnostic'' in data.diagnostics. This is  first is to enable the ``User Diagnostic'' in data.diagnostics. This is
320  accomplished by setting one of the fields slots to either UDIAG1 through  accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through
321  UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level  UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level
322  fields. These are listed in the diagnostics menu. The second step is to  fields) to the data.diagnostics namelist in one of the output streams. These
323  add a call to fill\_diagnostics from the subroutine in which the quantity  fields are listed in the diagnostics menu. The second step is to
324    add a call to diagnostics\_fill from the subroutine in which the quantity
325  desired for diagnostic output is computed.  desired for diagnostic output is computed.
326    
327    \noindent
328    In order to add a new diagnostic to the permanent set of diagnostics that the
329    main model or any package contains as part of its diagnostics menu, the subroutine
330    diagnostics\_add2list should be called during the initialization phase of the
331    main model or package. For the main model, the call should be made from
332    subroutine diagnostics\_main\_init, and for a package, the call should probably
333    be made from somewhere in the packages\_init\_fixed sequence (probaby from inside
334    the particular package's init\_fixed routine). A typical code sequence to set the
335    input arguments to diagnostics\_add2list would look like:
336    
337    \noindent
338    \begin{tabbing}
339    XXXXXXXXX\=XXXXXX\= \kill
340    \>      diagName  = 'THETA   ' \\
341    \>      diagTitle = 'Potential Temperature (degC,K)' \\
342    \>      diagUnits = 'Degrees K       ' \\
343    \>      diagCode  = 'SM      MR      ' \\
344    \>      CALL DIAGNOSTICS\_ADD2LIST( diagNum, \\
345    \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
346    \\
347    \end{tabbing}
348    
349    \noindent If the new diagnostic quantity is associated with either a vector
350    pair or a diagnostic counter, the diagCode argument must be filled with the
351    proper index for the ``mate''. The output argument from diagnostics\_add2list
352    that is called diagNum here contains a running total of the number of diagnostics
353    defined in the code up to any point during the run. The sequence number for the
354    next two diagnostics defined (the two components of the vector pair, for instance)
355    will be diagNum+1 and diagNum+2. The definition of the first component of the vector
356    pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2.
357    Since the subroutine increments diagNum, the definition of the second component of
358    the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for
359    this case would look like:
360    
361    \noindent
362    \begin{tabbing}
363    XXXXXXXXX\=XXXXXX\= \kill
364    \>      diagName  = 'UVEL    ' \\
365    \>      diagTitle = 'Zonal Velocity                ' \\
366    \>      diagUnits = 'm / sec         ' \\
367    \>      diagCode  = 'SM      MR      ' \\
368    \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' \\
369    \>      call diagnostics\_add2list( diagNum, \\
370    \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
371    \>      diagName  = 'VVEL    ' \\
372    \>      diagTitle = 'Meridional Velocity           ' \\
373    \>      diagUnits = 'm / sec         ' \\
374    \>      diagCode  = 'SM      MR      ' \\
375    \>      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' \\
376    \>      call diagnostics\_add2list( diagNum, \\
377    \>     I          diagName, diagCode, diagUnits, diagTitle, myThid ) \\
378    \\
379    \end{tabbing}
380    
381    
382  \newpage  \newpage
383    
384  \subsubsection{GCM Diagnostic Menu}  \subsubsection{GCM Diagnostic Menu}
Legend:
Removed from v.1.10  
changed lines
  Added in v.1.11
  ViewVC Help
Powered by ViewVC 1.1.22