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 |
referred 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. Quantities |
39 |
referred 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\_ADDTOLIST} |
56 |
(\filelink{pkg/diagnostics/diagnostics\_addtolist.F}{pkg-diagnostics-diagnostics\_addtolist.F}): |
57 |
%This subroutine enables a diagnostic from the Diagnostic Menu, |
58 |
%meaning that space is allocated for the |
59 |
%diagnostic and the model routines will increment the diagnostic value |
60 |
%during execution. |
61 |
This routine is the underlying interface routine for defining a new permanent |
62 |
diagnostic in the main model or in a package. The calling sequence is: |
63 |
|
64 |
\begin{verbatim} |
65 |
CALL DIAGNOSTICS_ADDTOLIST ( |
66 |
O diagNum, |
67 |
I diagName, diagCode, diagUnits, diagTitle, diagMate, |
68 |
I myThid ) |
69 |
|
70 |
where: |
71 |
diagNum = diagnostic Id number - Output from routine |
72 |
diagName = name of diagnostic to declare |
73 |
diagCode = parser code for this diagnostic |
74 |
diagUnits = field units for this diagnostic |
75 |
diagTitle = field description for this diagnostic |
76 |
diagMate = diagnostic mate number |
77 |
myThid = my Thread Id number |
78 |
|
79 |
\end{verbatim} |
80 |
|
81 |
|
82 |
\noindent |
83 |
{\bf DIAGNOSTICS\_FILL} |
84 |
(\filelink{pkg/diagnostics/diagnostics\_fill.F}{pkg-diagnostics-diagnostics\_fill.F}): |
85 |
This is the main user interface routine to the diagnostics package. |
86 |
This routine will increment the specified |
87 |
diagnostic quantity with a field sent through the argument list. |
88 |
|
89 |
\begin{verbatim} |
90 |
CALL DIAGNOSTICS_FILL( |
91 |
I inpFld, diagName, |
92 |
I kLev, nLevs, bibjFlg, bi, bj, myThid ) |
93 |
|
94 |
where: |
95 |
inpFld = Field to increment diagnostics array |
96 |
diagName = diagnostic identificator name (8 characters long) |
97 |
kLev = Integer flag for vertical levels: |
98 |
> 0 (any integer): WHICH single level to increment in qdiag. |
99 |
0,-1 to increment "nLevs" levels in qdiag, |
100 |
0 : fill-in in the same order as the input array |
101 |
-1: fill-in in reverse order. |
102 |
nLevs = indicates Number of levels of the input field array |
103 |
(whether to fill-in all the levels (kLev<1) or just one (kLev>0)) |
104 |
bibjFlg = Integer flag to indicate instructions for bi bj loop |
105 |
= 0 indicates that the bi-bj loop must be done here |
106 |
= 1 indicates that the bi-bj loop is done OUTSIDE |
107 |
= 2 indicates that the bi-bj loop is done OUTSIDE |
108 |
AND that we have been sent a local array (with overlap regions) |
109 |
(local array here means that it has no bi-bj dimensions) |
110 |
= 3 indicates that the bi-bj loop is done OUTSIDE |
111 |
AND that we have been sent a local array |
112 |
AND that the array has no overlap region (interior only) |
113 |
NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter |
114 |
bi = X-direction tile number - used for bibjFlg=1-3 |
115 |
bj = Y-direction tile number - used for bibjFlg=1-3 |
116 |
myThid = my thread Id number |
117 |
\end{verbatim} |
118 |
|
119 |
\noindent |
120 |
{\bf DIAGNOSTICS\_SCALE\_FILL} |
121 |
(\filelink{pkg/diagnostics/diagnostics\_scale\_fill.F}{pkg-diagnostics-diagnostics\_scale\_fill.F}): |
122 |
This is a possible alternative routine to |
123 |
DIAGNOSTICS\_FILL which performs the same functions and has an additional option |
124 |
to scale the field before filling or raise the field to a power before filling. |
125 |
|
126 |
\begin{verbatim} |
127 |
CALL DIAGNOSTICS_SCALE_FILL( |
128 |
I inpFld, scaleFact, power, diagName, |
129 |
I kLev, nLevs, bibjFlg, bi, bj, myThid ) |
130 |
|
131 |
|
132 |
where all the arguments are the same as for DIAGNOSTICS_FILL with |
133 |
the addition of: |
134 |
scaleFact = Scaling factor to apply to the input field product |
135 |
power = Integer power to which to raise the input field (after scaling) |
136 |
\end{verbatim} |
137 |
|
138 |
\noindent |
139 |
{\bf DIAGNOSTICS\_FRACT\_FILL} |
140 |
(\filelink{pkg/diagnostics/diagnostics\_fract\_fill.F}{pkg-diagnostics-diagnostics\_fract\_fill.F}): |
141 |
This is a specific alternative routine to DIAGNOSTICS\_[SCALE]\_FILL |
142 |
for the case of a diagnostics which is associated to |
143 |
a fraction-weight factor (referred to as the diagnostics "counter mate"). |
144 |
This fraction-weight field is expected to vary during the simulation |
145 |
and is provided as argument to DIAGNOSTICS\_FRACT\_FILL |
146 |
in order to perform fraction-weighted time-average diagnostics. |
147 |
Note that the fraction-weight field has to correspond to the diagnostics |
148 |
counter-mate which has to be filled independently with a call to DIAGNOSTICS\_FILL. |
149 |
|
150 |
\begin{verbatim} |
151 |
CALL DIAGNOSTICS_FRACT_FILL( |
152 |
I inpFld, fractFld, scaleFact, power, diagName, |
153 |
I kLev, nLevs, bibjFlg, bi, bj, myThid ) |
154 |
|
155 |
|
156 |
where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with |
157 |
the addition of: |
158 |
fractFld = fraction used for weighted average diagnostics |
159 |
\end{verbatim} |
160 |
|
161 |
\noindent |
162 |
{\bf DIAGNOSTICS\_IS\_ON}: Function call to inquire whether a |
163 |
diagnostic is active and should be incremented. Useful when there is a |
164 |
computation that must be done locally before a call to |
165 |
DIAGNOSTICS\_FILL. The call sequence: |
166 |
|
167 |
\begin{verbatim} |
168 |
flag = DIAGNOSTICS_IS_ON( diagName, myThid ) |
169 |
|
170 |
where: |
171 |
diagName = diagnostic identificator name (8 characters long) |
172 |
myThid = my thread Id number |
173 |
\end{verbatim} |
174 |
|
175 |
\noindent |
176 |
{\bf DIAGNOSTICS\_COUNT} |
177 |
(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}): |
178 |
This subroutine increments the diagnostics counter only. |
179 |
In general, the diagnostics counter is incremented at the same time as the |
180 |
diagnostics is filled, by calling DIAGNOSTICS\_FILL. |
181 |
However, there are few cases where the counter is not incremented |
182 |
during the filling (e.g., when the filling is done level per level but |
183 |
level 1 is skipped) and needs to be done explicitly with a call to subroutine |
184 |
DIAGNOSTICS\_COUNT. The call sequence is: |
185 |
|
186 |
\begin{verbatim} |
187 |
CALL DIAGNOSTICS_COUNT( |
188 |
I diagName, bi, bj, myThid ) |
189 |
|
190 |
where: |
191 |
diagName = name of diagnostic to increment the counter |
192 |
bi = X-direction tile number, or 0 if called outside bi,bj loops |
193 |
bj = Y-direction tile number, or 0 if called outside bi,bj loops |
194 |
myThid = my thread Id number |
195 |
|
196 |
\end{verbatim} |
197 |
|
198 |
%\noindent |
199 |
%{\bf DIAGNOSTICS\_GET\_POINTERS} |
200 |
%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}): |
201 |
%This subroutine retrieves the value of a the diagnostics pointers |
202 |
%that other routines require as input - can be useful if the diagnostics common |
203 |
%blocks are not local to a routine. |
204 |
% |
205 |
%\begin{verbatim} |
206 |
% CALL DIAGNOSTICS_GET_POINTERS( |
207 |
% I diagName, listId, |
208 |
% O ndId, ip, |
209 |
% I myThid ) |
210 |
% |
211 |
% where: |
212 |
% diagName = diagnostic identificator name (8 characters long) |
213 |
% listId = list number that specifies the output frequency |
214 |
% ndId = diagnostics Id number (in available diagnostics list) |
215 |
% ip = diagnostics pointer to storage array |
216 |
% myThid = my Thread Id number |
217 |
%\end{verbatim} |
218 |
% |
219 |
%\noindent |
220 |
%{\bf GETDIAG} |
221 |
%%(\filelink{pkg/diagnostics/diagnostics\_utils.F}{pkg-diagnostics-diagnostics\_utils.F}): |
222 |
%This subroutine retrieves the value of a model diagnostic. |
223 |
%This routine is particularly useful when called from a |
224 |
%user output routine, although it can be called from any routine. This |
225 |
%routine returns the time-averaged value of the diagnostic by dividing |
226 |
%the current accumulated diagnostic value by its corresponding counter. |
227 |
%This routine does not change the value of the diagnostic itself, that |
228 |
%is, it does not replace the diagnostic with its time-average. The |
229 |
%%calling sequence for this routine is givin by: |
230 |
% |
231 |
%\begin{verbatim} |
232 |
% CALL GETDIAG( |
233 |
% I levreal, undef, |
234 |
% O qtmp, |
235 |
% I ndId, mate, ip, im, bi, bj, myThid ) |
236 |
% |
237 |
% where: |
238 |
%% lev = Model Level at which the diagnostic is desired |
239 |
% undef = Fill value to be used when diagnostic is undefined |
240 |
% qtmp = Time-Averaged Diagnostic Output |
241 |
% ndId = diagnostics Id number (in available diagnostics list) |
242 |
% mate = counter diagnostic number if any ; 0 otherwise |
243 |
% ip = pointer to storage array location for diag. |
244 |
% im = pointer to storage array location for mate |
245 |
% bi = X-direction tile number |
246 |
% bj = Y-direction tile number |
247 |
% myThid = my thread Id number |
248 |
%\end{verbatim} |
249 |
% |
250 |
%\noindent |
251 |
%{\bf DIAGNOSTICS\_CLRDIAG} |
252 |
%(\filelink{pkg/diagnostics/diagnostics\_clear.F}{pkg-diagnostics-diagnostics\_clear.F}): |
253 |
%This subroutine initializes the values of model |
254 |
%diagnostics to zero, and is particularly useful when called from user |
255 |
%output routines to re-initialize diagnostics during the run. |
256 |
%The calling sequence is: |
257 |
% |
258 |
%\begin{verbatim} |
259 |
% CALL DIAGNOSTICS_CLRDIAG ( ipt, nLev, myThid ) |
260 |
% |
261 |
% where: |
262 |
% ipt :: diagnostic pointer to storage array |
263 |
% nLev :: number of levels (in storage array) to reset |
264 |
% myThid :: my Thread Id number |
265 |
%\end{verbatim} |
266 |
|
267 |
\begin{table} |
268 |
\caption{Diagnostic Parsing Array} |
269 |
\label{tab:diagnostics:gdiag.tabl} |
270 |
\begin{center} |
271 |
\begin{tabular}{ |c|c|l| } |
272 |
\hline |
273 |
\multicolumn{3}{|c|}{\bf Diagnostic Parsing Array} \\ |
274 |
\hline |
275 |
\hline |
276 |
Array & Value & Description \\ |
277 |
\hline |
278 |
parse(1) & $\rightarrow$ S & Scalar Diagnostic \\ |
279 |
& $\rightarrow$ U & U-vector component Diagnostic \\ |
280 |
& $\rightarrow$ V & V-vector component Diagnostic \\ \hline |
281 |
parse(2) & $\rightarrow$ U & C-Grid U-Point \\ |
282 |
& $\rightarrow$ V & C-Grid V-Point \\ |
283 |
& $\rightarrow$ M & C-Grid Mass Point \\ |
284 |
& $\rightarrow$ Z & C-Grid Vorticity (Corner) Point \\ \hline |
285 |
parse(3) & $\rightarrow$ & Used for Level Integrated output: cumulate levels \\ |
286 |
& $\rightarrow$ r & same but cumulate product by model level thickness \\ |
287 |
& $\rightarrow$ R & same but cumulate product by hFac \& level thickness \\ \hline |
288 |
parse(4) & $\rightarrow$ P & Positive Definite Diagnostic \\ \hline |
289 |
parse(5) & $\rightarrow$ C & with Counter array \\ |
290 |
& $\rightarrow$ P & post-processed (not filled up) from other diags \\ |
291 |
& $\rightarrow$ D & Disabled Diagnostic for output \\ \hline |
292 |
parse(6-8)& & retired, formerly: 3-digit mate number \\ \hline |
293 |
parse(9) & $\rightarrow$ U & model-level plus 1/2 \\ |
294 |
& $\rightarrow$ M & model-level middle \\ |
295 |
& $\rightarrow$ L & model-level minus 1/2 \\ \hline |
296 |
parse(10) & $\rightarrow$ 0 & levels = 0 \\ |
297 |
& $\rightarrow$ 1 & levels = 1 \\ |
298 |
& $\rightarrow$ R & levels = Nr \\ |
299 |
& $\rightarrow$ L & levels = MAX(Nr,NrPhys) \\ |
300 |
& $\rightarrow$ M & levels = MAX(Nr,NrPhys) - 1 \\ |
301 |
& $\rightarrow$ G & levels = Ground\_level Number \\ |
302 |
& $\rightarrow$ I & levels = sea-Ice\_level Number \\ |
303 |
& $\rightarrow$ X & free levels option (need to be set explicitly)\\ \hline |
304 |
\end{tabular} |
305 |
\addcontentsline{lot}{section}{Table 3: Diagnostic Parsing Array} |
306 |
\end{center} |
307 |
\end{table} |
308 |
|
309 |
\noindent |
310 |
The diagnostics are computed at various times and places within the |
311 |
GCM. Because MITgcm may employ a staggered grid, diagnostics may be |
312 |
computed at grid box centers, corners, or edges, and at the middle or |
313 |
edge in the vertical. Some diagnostics are scalars, while others are |
314 |
components of vectors. An internal array is defined which contains |
315 |
information concerning various grid attributes of each diagnostic. The |
316 |
GDIAG array (in common block {\tt diagnostics} in file {\tt |
317 |
DIAGNOSTICS.h}) is internally defined as a character*16 variable, and |
318 |
is equivalenced to a character*1 "parse" array in output in order to |
319 |
extract the grid-attribute information. The GDIAG array is described |
320 |
in Table \ref{tab:diagnostics:gdiag.tabl}. |
321 |
|
322 |
\noindent |
323 |
As an example, consider a diagnostic whose associated GDIAG parameter is equal |
324 |
to ``UUR\hspace{5mm}MR''. From GDIAG we can determine that this diagnostic is a |
325 |
U-vector component located at the C-grid U-point, model mid-level (M) |
326 |
with Nr levels (last R). |
327 |
|
328 |
\noindent |
329 |
In this way, each Diagnostic in the model has its attributes (ie. vector or scalar, |
330 |
C-grid location, etc.) defined internally. The Output routines use this information |
331 |
in order to determine what type of transformations need to be performed. Any |
332 |
interpolations are done at the time of output rather than during each model step. |
333 |
In this way the User has flexibility in determining the type of gridded data which |
334 |
is output. |
335 |
|
336 |
%\newpage |
337 |
\subsection{Usage Notes} |
338 |
\label{sec:diagnostics:usersguide} |
339 |
|
340 |
\subsubsection{Using available diagnostics} |
341 |
\noindent |
342 |
To use the diagnostics package, other than enabling it in {\tt packages.conf} |
343 |
and turning the {\tt useDiagnostics} flag in {\tt data.pkg} to .TRUE., there are two |
344 |
further steps the user must take to enable the diagnostics package for |
345 |
output of quantities that are already defined in the GCM under an experiment's |
346 |
configuration of packages. |
347 |
A parameter file {\tt data.diagnostics} must be supplied in the run directory, |
348 |
and the file DIAGNOSTICS\_SIZE.h must be included in the |
349 |
code directory. The steps for defining a new (permanent or experiment-specific |
350 |
temporary) diagnostic quantity will be outlined later. |
351 |
|
352 |
\noindent The namelist in parameter file {\tt data.diagnostics} will activate |
353 |
a user-defined list of diagnostics quantities to be computed, |
354 |
specify the frequency and type of output, the number of levels, and |
355 |
the name of all the separate output files. |
356 |
A sample {\tt data.diagnostics} namelist file: |
357 |
|
358 |
\begin{verbatim} |
359 |
# Diagnostic Package Choices |
360 |
#-------------------- |
361 |
# dumpAtLast (logical): always write output at the end of simulation (default=F) |
362 |
# diag_mnc (logical): write to NetCDF files (default=useMNC) |
363 |
#--for each output-stream: |
364 |
# fileName(n) : prefix of the output file name (max 80c long) for outp.stream n |
365 |
# frequency(n):< 0 : write snap-shot output every |frequency| seconds |
366 |
# > 0 : write time-average output every frequency seconds |
367 |
# timePhase(n) : write at time = timePhase + multiple of |frequency| |
368 |
# averagingFreq : frequency (in s) for periodic averaging interval |
369 |
# averagingPhase : phase (in s) for periodic averaging interval |
370 |
# repeatCycle : number of averaging intervals in 1 cycle |
371 |
# levels(:,n) : list of levels to write to file (Notes: declared as REAL) |
372 |
# when this entry is missing, select all common levels of this list |
373 |
# fields(:,n) : list of selected diagnostics fields (8.c) in outp.stream n |
374 |
# (see "available_diagnostics.log" file for the full list of diags) |
375 |
# missing_value(n) : missing value for real-type fields in output file "n" |
376 |
# fileFlags(n) : specific code (8c string) for output file "n" |
377 |
#-------------------- |
378 |
&DIAGNOSTICS_LIST |
379 |
fields(1:2,1) = 'UVEL ','VVEL ', |
380 |
levels(1:5,1) = 1.,2.,3.,4.,5., |
381 |
filename(1) = 'diagout1', |
382 |
frequency(1) = 86400., |
383 |
fields(1:2,2) = 'THETA ','SALT ', |
384 |
filename(2) = 'diagout2', |
385 |
fileflags(2) = ' P1 ', |
386 |
frequency(2) = 3600., |
387 |
& |
388 |
|
389 |
&DIAG_STATIS_PARMS |
390 |
& |
391 |
\end{verbatim} |
392 |
|
393 |
\noindent |
394 |
In this example, there are two output files that will be generated for |
395 |
each tile and for each output time. The first set of output files has |
396 |
the prefix diagout1, does time averaging every 86400. seconds, |
397 |
(frequency is 86400.), and will write fields which are multiple-level |
398 |
fields at output levels 1-5. The names of diagnostics quantities are |
399 |
UVEL and VVEL. The second set of output files has the prefix |
400 |
diagout2, does time averaging every 3600. seconds, includes fields |
401 |
with all levels, and the names of diagnostics quantities are THETA and SALT. |
402 |
|
403 |
\noindent |
404 |
The user must assure that enough computer memory is allocated for the |
405 |
diagnostics and the output streams selected for a particular |
406 |
experiment. This is accomplished by modifying the file |
407 |
DIAGNOSTICS\_SIZE.h and including it in the experiment code directory. |
408 |
The parameters that should be checked are called numDiags, numLists, |
409 |
numperList, and diagSt\_size. |
410 |
|
411 |
\noindent numDiags (and diagSt\_size): \\ |
412 |
\noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG |
413 |
which is located in the file |
414 |
\filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h} |
415 |
and has the form:\\ |
416 |
\begin{verbatim} |
417 |
_RL qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numDiags,nSx,nSy) |
418 |
_RL qSdiag(0:nStats,0:nRegions,diagSt_size,nSx,nSy) |
419 |
COMMON / DIAG_STORE_R / qdiag, qSdiag |
420 |
\end{verbatim} |
421 |
\noindent |
422 |
The first two-dimensions of qdiag correspond to the horizontal |
423 |
dimension of a given diagnostic, and the third dimension of qdiag is |
424 |
used to identify diagnostic fields and levels combined. In order to |
425 |
minimize the memory requirement of the model for diagnostics, the |
426 |
default GCM executable is compiled with room for only one horizontal |
427 |
diagnostic array, or with numDiags set to Nr. In order for the User to |
428 |
enable more than 1 three-dimensional diagnostic, the size of the |
429 |
diagnostics common must be expanded to accommodate the desired |
430 |
diagnostics. This can be accomplished by manually changing the |
431 |
parameter numDiags in the file |
432 |
\filelink{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}. |
433 |
numDiags should be set greater than or equal to the sum of all the |
434 |
diagnostics activated for output each multiplied by the number of |
435 |
levels defined for that diagnostic quantity. For the above example, |
436 |
there are 4 multiple level fields, which the diagnostics menu (see |
437 |
below) indicates are defined at the GCM vertical resolution, Nr. The |
438 |
value of numDiags in DIAGNOSTICS\_SIZE.h would therefore be equal to |
439 |
4*Nr, or, say 40 if $Nr=10$. |
440 |
|
441 |
\noindent numLists and numperList: \\ |
442 |
\noindent The parameter numLists must be set greater than or equal to |
443 |
the number of separate output streams that the user specifies in the |
444 |
namelist file data.diagnostics. The parameter numperList corresponds |
445 |
to the maximum number of diagnostics requested per output streams. |
446 |
|
447 |
\subsubsection{Adding new diagnostics to the code} |
448 |
|
449 |
\noindent |
450 |
In order to define and include as part of the diagnostic output any |
451 |
field that is desired for a particular experiment, two steps must be |
452 |
taken. The first is to enable the ``User Diagnostic'' in |
453 |
{\tt data.diagnostics}. This is accomplished by adding one of the ``User |
454 |
Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level |
455 |
fields, or SDIAG1 through SDIAG10 for single level fields) to the |
456 |
data.diagnostics namelist in one of the output streams. These fields |
457 |
are listed in the diagnostics menu. The second step is to add a call |
458 |
to DIAGNOSTICS\_FILL from the subroutine in which the quantity desired |
459 |
for diagnostic output is computed. |
460 |
|
461 |
\noindent |
462 |
In order to add a new diagnostic to the permanent set of diagnostics |
463 |
that the main model or any package contains as part of its diagnostics |
464 |
menu, the subroutine DIAGNOSTICS\_ADDTOLIST should be called during the |
465 |
initialization phase of the main model or package. For the main model, |
466 |
the call should be made from subroutine DIAGNOSTICS\_MAIN\_INIT, and |
467 |
for a package, the call should probably be made from |
468 |
%somewhere in the PACKAGES\_INIT\_FIXED sequence (probably |
469 |
from inside the particular package's init\_fixed routine. |
470 |
A typical code sequence to set the |
471 |
input arguments to DIAGNOSTICS\_ADDTOLIST would look like: |
472 |
|
473 |
\begin{verbatim} |
474 |
diagName = 'RHOAnoma' |
475 |
diagTitle = 'Density Anomaly (=Rho-rhoConst)' |
476 |
diagUnits = 'kg/m^3 ' |
477 |
diagCode = 'SMR MR ' |
478 |
CALL DIAGNOSTICS\_ADDTOLIST( diagNum, |
479 |
I diagName, diagCode, diagUnits, diagTitle, 0, myThid ) |
480 |
\end{verbatim} |
481 |
|
482 |
\noindent If the new diagnostic quantity is associated with either a |
483 |
vector pair or a diagnostic counter, the diagMate argument must be |
484 |
provided with the proper index corresponding to the ``mate''. |
485 |
The output argument from DIAGNOSTICS\_ADDTOLIST that is called diagNum here |
486 |
contains a running total of the number of diagnostics defined in the code up to |
487 |
any point during the run. The sequence number for the next two |
488 |
diagnostics defined (the two components of the vector pair, for |
489 |
instance) will be diagNum+1 and diagNum+2. The definition of the first |
490 |
component of the vector pair must fill the ``mate'' segment of the |
491 |
diagCode as diagnostic number diagNum+2. Since the subroutine |
492 |
increments diagNum, the definition of the second component of the |
493 |
vector fills the ``mate'' part of diagCode with diagNum. A code |
494 |
sequence for this case would look like: |
495 |
|
496 |
\begin{verbatim} |
497 |
diagName = 'UVEL ' |
498 |
diagTitle = 'Zonal Component of Velocity (m/s)' |
499 |
diagUnits = 'm/s ' |
500 |
diagCode = 'UUR MR ' |
501 |
diagMate = diagNum + 2 |
502 |
CALL DIAGNOSTICS_ADDTOLIST( diagNum, |
503 |
I diagName, diagCode, diagUnits, diagTitle, diagMate, myThid ) |
504 |
|
505 |
diagName = 'VVEL ' |
506 |
diagTitle = 'Meridional Component of Velocity (m/s)' |
507 |
diagUnits = 'm/s ' |
508 |
diagCode = 'VVR MR ' |
509 |
diagMate = diagNum |
510 |
CALL DIAGNOSTICS_ADDTOLIST( diagNum, |
511 |
I diagName, diagCode, diagUnits, diagTitle, diagMate, myThid ) |
512 |
\end{verbatim} |
513 |
|
514 |
\input{s_outp_pkgs/text/diagnostics-menu.tex} |
515 |
|
516 |
\newpage |
517 |
\noindent For a list of the diagnostic fields available in the |
518 |
different MITgcm packages, follow the link to the diagnostics menu |
519 |
in the manual section describing the package: |
520 |
|
521 |
\begin{itemize} |
522 |
\item aim: \ref{sec:pkg:aim:diagnostics} |
523 |
\item exf: \ref{sec:pkg:exf:diagnostics} |
524 |
\item gchem: \ref{sec:pkg:gchem:diagnostics} |
525 |
\item generic\_advdiff: \ref{sec:pkg:gad:diagnostics} |
526 |
\item gridalt: \ref{sec:pkg:gridalt:diagnostics} |
527 |
\item gmredi: \ref{sec:pkg:gmredi:diagnostics} |
528 |
\item fizhi: \ref{sec:pkg:fizhi:diagnostics} |
529 |
\item kpp: \ref{sec:pkg:kpp:diagnostics} |
530 |
\item land: \ref{sec:pkg:land:diagnostics} |
531 |
\item mom\_common: \ref{sec:pkg:mom_common:diagnostics} |
532 |
\item obcs: \ref{sec:pkg:obcs:diagnostics} |
533 |
\item thsice: \ref{sec:pkg:thsice:diagnostics} |
534 |
\item shap\_filt: \ref{sec:pkg:shap_filt:diagnostics} |
535 |
\item ptracers: \ref{sec:pkg:ptracers:diagnostics} |
536 |
\end{itemize} |
537 |
|
538 |
\subsection{Dos and Donts} |
539 |
|
540 |
\subsection{Diagnostics Reference} |
541 |
|