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{s_outp_pkgs/text/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:gad: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 |
\item ptracers: \ref{sec:pkg:ptracers:diagnostics} |
423 |
\end{itemize} |
424 |
|
425 |
\subsection{Dos and Donts} |
426 |
|
427 |
\subsection{Diagnostics Reference} |
428 |
|