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

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

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


Revision 1.5 - (show annotations) (download) (as text)
Thu Apr 6 17:36:07 2006 UTC (19 years, 3 months ago) by edhill
Branch: MAIN
Changes since 1.4: +15 -13 lines
File MIME type: application/x-tex
fix broken LaTeX syntax

1 \section{Diagnostics--A Flexible Infrastructure}
2 \label{sec:pkg:diagnostics}
3 \begin{rawhtml}
4 <!-- CMIREDIR:package_diagnostics: -->
5 \end{rawhtml}
6
7 \subsection{Introduction}
8
9 \noindent
10 This section of the documentation describes the Diagnostics package
11 available within the GCM. A large selection of model diagnostics is
12 available for output. In addition to the diagnostic quantities
13 pre-defined in the GCM, there exists the option, in any experiment, to
14 define a new diagnostic quantity and include it as part of the
15 diagnostic output with the addition of a single subroutine call in the
16 routine where the field is computed. As a matter of philosophy, no
17 diagnostic is enabled as default, thus each user must specify the
18 exact diagnostic information required for an experiment. This is
19 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.
24
25 \noindent
26 The Diagnostic Menu in this section of the manual is a listing of
27 diagnostic quantities available within the main (dynamics) part of the
28 GCM. Additional diagnostic quantities, defined within the different
29 GCM packages, are available and are listed in the diagnostic menu
30 subsection of the manual section associated with each relevant
31 package. Once a diagnostic is enabled, the GCM will continually
32 increment an array specifically allocated for that diagnostic whenever
33 the appropriate quantity is computed. A counter is defined which
34 records how many times each diagnostic quantity has been incremented.
35 Several special diagnostics are included in the menu. Quantities
36 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 \subsection{Equations}
43 Not relevant.
44
45 \subsection{Key Subroutines and Parameters}
46 \label{sec:diagnostics:diagover}
47
48 \noindent
49 There are several utilities within the GCM available to users to
50 enable, disable, clear, write and retrieve model diagnostics, and may
51 be called from any routine. The available utilities and the CALL
52 sequences are listed below.
53
54 \noindent
55 {\bf diagnostics\_fill}: This is the main user interface routine to
56 the diagnostics package. This routine will increment the specified
57 diagnostic quantity with a field sent through the argument list.
58
59 \begin{verbatim}
60 call diagnostics_fill(
61 & arrayin, chardiag, levflg, nlevs,
62 & bibjflg, bi, bj, myThid )
63
64 where:
65 arrayin = Field to increment diagnostics array
66 chardiag = Character *8 expression for diag to fill
67 levflg = Integer flag for vertical levels:
68 = 0 indicates multiple (nlevs) levels incremented
69 = -1 indicates multiple (nlevs) levels incremented,
70 but in reverse vertical order
71 positive integer - WHICH single level to increment.
72 nlevs = indicates Number of levels to be filled (1 if levflg gt 0)
73 bibjflg = Integer flag to indicate instructions for bi bj loop
74 = 0 indicates that the bi-bj loop must be done here
75 = 1 indicates that the bi-bj loop is done OUTSIDE
76 = 2 indicates that the bi-bj loop is done OUTSIDE
77 AND that we have been sent a local array
78 AND that the array has the shadow regions
79 = 3 indicates that the bi-bj loop is done OUTSIDE
80 AND that we have been sent a local array
81 AND that the array has no shadow regions
82 bi = X-direction process(or) number - used for bibjflg=1-3
83 bj = Y-direction process(or) number - used for bibjflg=1-3
84 myThid = Current Thread number
85 \end{verbatim}
86
87 \noindent
88 {\bf diagnostics\_scale\_fill}: This is a possible alternative routine to
89 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.
91
92 \begin{verbatim}
93 call diagnostics_scale_fill(
94 & arrayin, scalefactor, power, chardiag,
95 & levflg, nlevs, bibjflg, bi, bj, myThid )
96
97 where all the arguments are the same as for diagnostics_fill with
98 the addition of:
99 scalefactor = Factor to scale field
100 power = Integer power to which to raise the input field
101 \end{verbatim}
102
103 \noindent
104 {\bf diagnostics\_is\_on}: Function call to inquire whether a
105 diagnostic is active and can be incremented. Useful when there is a
106 computation that must be done locally before a call to
107 diagnostics\_fill. The call sequence:
108
109 \begin{verbatim}
110 flag = diagnostics_is_on( diagName, myThid )
111
112 where:
113 diagName = Character *8 expression for diagnostic
114 myThid = Current Thread number
115 \end{verbatim}
116
117 \noindent
118 {\bf diagnostics\_get\_pointers}: This subroutine retrieves the value
119 of a the diagnostics pointers that other routines require as input -
120 can be useful if the diagnostics common blocks are not local to a
121 routine.
122
123 \begin{verbatim}
124 call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid )
125
126 where:
127 diagName = Character *8 expression of diagnostic
128 ipoint = Pointer into qdiag array - from idiag array in common
129 jpoint = Pointer into diagnostics menu - from jdiag array in common
130 myThid = Current Thread number
131 \end{verbatim}
132
133 \noindent
134 {\bf getdiag}: This subroutine retrieves the value of a model
135 diagnostic. This routine is particulary useful when called from a
136 user output routine, although it can be called from any routine. This
137 routine returns the time-averaged value of the diagnostic by dividing
138 the current accumulated diagnostic value by its corresponding counter.
139 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 calling sequence for this routine is givin by:
142
143 \begin{verbatim}
144 call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid)
145
146 where:
147 lev = Model Level at which the diagnostic is desired
148 undef = Fill value to be used when diagnostic is undefined
149 qtmp = Time-Averaged Diagnostic Output
150 ipoint = Pointer into qdiag array - from idiag array in common
151 mate = Diagnostic mate pointer number
152 bi = X-direction process(or) number
153 bj = Y-direction process(or) number
154 myThid = Current Thread number
155 \end{verbatim}
156
157 \noindent
158 {\bf diagnostics\_add2list}: This subroutine enables a diagnostic from
159 the Diagnostic Menu, meaning that space is allocated for the
160 diagnostic and the model routines will increment the diagnostic value
161 during execution. This routine is the underlying interface routine
162 for defining a new permanent diagnostic in the main model or in a
163 package. The calling sequence is:
164
165 \begin{verbatim}
166 call diagnostics_add2list( diagNum,diagName, diagCode,
167 diagUnits, diagTitle, myThid )
168
169 where:
170 diagNum = Diagnostic number - Output from routine
171 diagName = character*8 diagnostic name
172 diagCode = character*16 parsing code (see description of gdiag below)
173 diagUnits = Diagnostic units (character*16)
174 diagTitle = Diagnostic title or long name (up to character*80)
175 myThid = Current Thread number
176 \end{verbatim}
177
178 \noindent
179 {\bf clrdiag}: This subroutine initializes the values of model
180 diagnostics to zero, and is particularly useful when called from user
181 output routines to re-initialize diagnostics during the run. The
182 calling sequence is:
183
184 \begin{verbatim}
185 call diagnostics_clrdiag (jpoint, ipoint, myThid)
186
187 where:
188 jpoint = Diagnostic number from menu - from jdiag array
189 ipoint = Pointer number into qdiag array - from idiag array
190 myThid = Current Thread number
191 \end{verbatim}
192
193 \noindent
194 The diagnostics are computed at various times and places within the
195 GCM. Because MITgcm may employ a staggered grid, diagnostics may be
196 computed at grid box centers, corners, or edges, and at the middle or
197 edge in the vertical. Some diagnostics are scalars, while others are
198 components of vectors. An internal array is defined which contains
199 information concerning various grid attributes of each diagnostic. The
200 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}
207 \caption{Diagnostic Parsing Array}
208 \label{tab:diagnostics:gdiag.tabl}
209 \begin{center}
210 \begin{tabular}{ |c|c|l| }
211 \hline
212 \multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\
213 \hline
214 \hline
215 Array & Value & Description \\
216 \hline
217 parse(1) & $\rightarrow$ S & Scalar Diagnostic \\
218 & $\rightarrow$ U & U-vector component Diagnostic \\
219 & $\rightarrow$ V & V-vector component Diagnostic \\ \hline
220 parse(2) & $\rightarrow$ U & C-Grid U-Point \\
221 & $\rightarrow$ V & C-Grid V-Point \\
222 & $\rightarrow$ M & C-Grid Mass Point \\
223 & $\rightarrow$ Z & C-Grid Vorticity (Corner) Point \\ \hline
224 parse(3) & $\rightarrow$ R & Not Currently in Use \\ \hline
225 parse(4) & $\rightarrow$ P & Positive Definite Diagnostic \\ \hline
226 parse(5) & $\rightarrow$ C & Counter Diagnostic \\
227 & $\rightarrow$ D & Disabled Diagnostic for output \\ \hline
228 parse(6-8) & $\rightarrow$ C & 3-digit integer corresponding to \\
229 & & vector or counter component mate \\ \hline
230 \end{tabular}
231 \addcontentsline{lot}{section}{Table 3: Diagnostic Parsing Array}
232 \end{center}
233 \end{table}
234
235
236 \noindent
237 As an example, consider a diagnostic whose associated GDIAG parameter is equal
238 to ``UU 002''. From GDIAG we can determine that this diagnostic is a
239 U-vector component located at the C-grid U-point.
240 Its corresponding V-component diagnostic is located in Diagnostic \# 002.
241
242 \noindent
243 In this way, each Diagnostic in the model has its attributes (ie. vector or scalar,
244 C-grid location, etc.) defined internally. The Output routines use this information
245 in order to determine what type of transformations need to be performed. Any
246 interpolations are done at the time of output rather than during each model step.
247 In this way the User has flexibility in determining the type of gridded data which
248 is output.
249
250 \subsection{Usage Notes}
251 \label{sec:diagnostics:usersguide}
252
253 \noindent
254 To use the diagnostics package, other than enabling it in packages.conf
255 and turning the usediagnostics flag in data.pkg to .TRUE., there are two
256 further steps the user must take to enable the diagnostics package for
257 output of quantities that are already defined in the GCM under an experiment's
258 configuration of packages. A namelist must be supplied in the run directory
259 called data.diagnostics, and the file DIAGNOSTICS\_SIZE.h must be included in the
260 code directory. The steps for defining a new (permanent or experiment-specific
261 temporary) diagnostic quantity will be outlined later.
262
263 \noindent The namelist will activate a user-defined list of diagnostics quantities
264 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:
266
267 \begin{verbatim}
268 # Diagnostic Package Choices
269 &diagnostics\_list
270 frequency(1) = 86400.,
271 levels(1,1) = 1.,
272 fields(1,1) = 'RSURF ',
273 filename(1) = 'surface',
274 frequency(2) = 86400.,
275 levels(1,2) = 1.,2.,3.,4.,5.,
276 fields(1,2) = 'UVEL ','VVEL ',
277 filename(2) = 'diagout1',
278 frequency(3) = 3600.,
279 fields(1,3) = 'UVEL ','VVEL ','PRESSURE',
280 filename(3) = 'diagout2',
281 fileflags(3) = ' P1 ',
282 &end
283 \end{verbatim}
284
285 \noindent
286 In this example, there are two output files that will be generated for
287 each tile and for each output time. The first set of output files has
288 the prefix diagout1, does time averaging every 86400. seconds,
289 (frequency is 86400.), and will write fields which are multiple-level
290 fields at output levels 1-5. The names of diagnostics quantities are
291 UVEL and VVEL. The second set of output files has the prefix
292 diagout2, does time averaging every 3600. seconds, includes fields
293 which are multiple-level fields, levels output are 1-5, and the names
294 of diagnostics quantities are THETA and SALT.
295
296 \noindent
297 The user must assure that enough computer memory is allocated for the
298 diagnostics and the output streams selected for a particular
299 experiment. This is acomplished by modifying the file
300 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): \\
305 \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}.\\
307 and has the form:\\
308 \begin{verbatim}
309 common /diagnostics/
310 & qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
311 \end{verbatim}
312 \noindent
313 The first two-dimensions of qdiag correspond to the horizontal
314 dimension of a given diagnostic, and the third dimension of qdiag is
315 used to identify diagnostic fields and levels combined. In order to
316 minimize the memory requirement of the model for diagnostics, the
317 default GCM executable is compiled with room for only one horizontal
318 diagnostic array, or with numdiags set to Nr. In order for the User to
319 enable more than 1 three-dimensional diagnostic, the size of the
320 diagnostics common must be expanded to accomodate the desired
321 diagnostics. This can be accomplished by manually changing the
322 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: \\
333 \noindent The parameter numlists must be set greater than or equal to
334 the number of separate output streams that the user specifies in the
335 namelist file data.diagnostics. The parameter numperlist corresponds
336 to the number of diagnostics requested in each output stream.
337
338 \noindent
339 In order to define and include as part of the diagnostic output any
340 field that is desired for a particular experiment, two steps must be
341 taken. The first is to enable the ``User Diagnostic'' in
342 data.diagnostics. This is accomplished by adding one of the ``User
343 Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level
344 fields, or SDIAG1 through SDIAG10 for single level fields) to the
345 data.diagnostics namelist in one of the output streams. These fields
346 are listed in the diagnostics menu. The second step is to add a call
347 to diagnostics\_fill from the subroutine in which the quantity desired
348 for diagnostic output is computed.
349
350 \noindent
351 In order to add a new diagnostic to the permanent set of diagnostics
352 that the main model or any package contains as part of its diagnostics
353 menu, the subroutine diagnostics\_add2list should be called during the
354 initialization phase of the main model or package. For the main model,
355 the call should be made from subroutine diagnostics\_main\_init, and
356 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:
360
361 \begin{verbatim}
362 diagName = 'THETA '
363 diagTitle = 'Potential Temperature (degC,K)'
364 diagUnits = 'Degrees K '
365 diagCode = 'SM MR '
366 CALL DIAGNOSTICS\_ADD2LIST( diagNum,
367 I diagName, diagCode, diagUnits, diagTitle, myThid )
368 \end{verbatim}
369
370 \noindent If the new diagnostic quantity is associated with either a
371 vector pair or a diagnostic counter, the diagCode argument must be
372 filled with the proper index for the ``mate''. The output argument
373 from diagnostics\_add2list that is called diagNum here contains a
374 running total of the number of diagnostics defined in the code up to
375 any point during the run. The sequence number for the next two
376 diagnostics defined (the two components of the vector pair, for
377 instance) will be diagNum+1 and diagNum+2. The definition of the first
378 component of the vector pair must fill the ``mate'' segment of the
379 diagCode as diagnostic number diagNum+2. Since the subroutine
380 increments diagNum, the definition of the second component of the
381 vector fills the ``mate'' part of diagCode with diagNum. A code
382 sequence for this case would look like:
383
384 \begin{verbatim}
385 diagName = 'UVEL '
386 diagTitle = 'Zonal Velocity '
387 diagUnits = 'm / sec '
388 diagCode = 'SM MR '
389 write(diagCode,'(A,I3.3,A)') 'VV ', diagNum+2 ,'MR '
390 call diagnostics\_add2list( diagNum,
391 I diagName, diagCode, diagUnits, diagTitle, myThid )
392 diagName = 'VVEL '
393 diagTitle = 'Meridional Velocity '
394 diagUnits = 'm / sec '
395 diagCode = 'SM MR '
396 write(diagCode,'(A,I3.3,A)') 'VV ', diagNum ,'MR '
397 call diagnostics\_add2list( diagNum,
398 I diagName, diagCode, diagUnits, diagTitle, myThid )
399 \end{verbatim}
400
401 \input{part7/diagnostics-menu.tex}
402
403 \newpage
404 \noindent For a list of the diagnostic fields available in the
405 different MITgcm packages, follow the link to the diagnostics menu
406 in the manual section describing the package:
407
408 \begin{itemize}
409 \item aim: \ref{sec:pkg:aim:diagnostics}
410 \item exf: \ref{sec:pkg:exf:diagnostics}
411 \item gchem: \ref{sec:pkg:gchem:diagnostics}
412 \item generic\_advdiff: \ref{sec:pkg:generic_advdiff:diagnostics}
413 \item gridalt: \ref{sec:pkg:gridalt:diagnostics}
414 \item gmredi: \ref{sec:pkg:gmredi:diagnostics}
415 \item fizhi: \ref{sec:pkg:fizhi:diagnostics}
416 \item kpp: \ref{sec:pkg:kpp:diagnostics}
417 \item land: \ref{sec:pkg:land:diagnostics}
418 \item mom\_common: \ref{sec:pkg:mom_common:diagnostics}
419 \item obcs: \ref{sec:pkg:obcs:diagnostics}
420 \item thsice: \ref{sec:pkg:thsice:diagnostics}
421 \item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics}
422 \end{itemize}
423
424 \subsection{Dos and Donts}
425
426 \subsection{Diagnostics Reference}
427

  ViewVC Help
Powered by ViewVC 1.1.22