6 |
|
|
7 |
\subsection{Introduction} |
\subsection{Introduction} |
8 |
|
|
9 |
This section of the documentation describes the Diagnostics Utilities available within the GCM. |
This section of the documentation describes the Diagnostics package available within |
10 |
In addition to |
the GCM. In addition to a description of how to set and extract diagnostic quantities, |
11 |
a description on how to set and extract diagnostic quantities, this document also provides a |
this document also provides a comprehensive list of all available diagnostic quantities |
12 |
comprehensive list of all available diagnostic quantities and a short description of how they are |
and a short description of how they are computed. It should be noted that this document |
13 |
computed. It should be noted that this document is not intended to be a complete documentation |
is not intended to be a complete documentation of the various packages used in the GCM, |
14 |
of the various packages used in the GCM, and the reader should |
and the reader should refer to original publications and the appropriate sections of this |
15 |
refer to original publications for further insight. |
documentation for further insight. |
|
|
|
16 |
|
|
17 |
\subsection{Equations} |
\subsection{Equations} |
18 |
Not relevant. |
Not relevant. |
21 |
\label{sec:diagnostics:diagover} |
\label{sec:diagnostics:diagover} |
22 |
|
|
23 |
A large selection of model diagnostics is available in the GCM. At the time of |
A large selection of model diagnostics is available in the GCM. At the time of |
24 |
this writing there are 92 different diagnostic quantities which can be enabled for an |
this writing there are 280 different diagnostic quantities which can be enabled for an |
25 |
experiment. As a matter of philosophy, no diagnostic is enabled as default, thus each user must |
experiment. As a matter of philosophy, no diagnostic is enabled as default, thus each |
26 |
specify the exact diagnostic information required for an experiment. This is accomplished by |
user must specify the exact diagnostic information required for an experiment. This |
27 |
enabling the specific diagnostic of interest cataloged in the |
is accomplished by enabling the specific diagnostic of interest cataloged in the |
28 |
Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). |
Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). |
29 |
The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within the |
The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within |
30 |
GCM. Diagnostics are internally referred to by their associated number in the Diagnostic |
the GCM. Diagnostics are internally referred to by their associated number in the Diagnostic |
31 |
Menu. Once a diagnostic is enabled, the GCM will continually increment an array |
Menu. Once a diagnostic is enabled, the GCM will continually increment an array |
32 |
specifically allocated for that diagnostic whenever the associated process for the diagnostic is |
specifically allocated for that diagnostic whenever the associated process for the |
33 |
computed. Separate arrays are used both for the diagnostic quantity and its diagnostic counter |
diagnostic is computed. Separate arrays are used both for the diagnostic quantity and |
34 |
which records how many times each diagnostic quantity has been computed. In addition |
its diagnostic counter which records how many times each diagnostic quantity has been |
35 |
special diagnostics, called |
computed. In addition special diagnostics, called ``Counter Diagnostics'', records the |
36 |
``Counter Diagnostics'', records the frequency of diagnostic updates separately for each |
frequency of diagnostic updates separately for each model grid location. |
|
model grid location. |
|
37 |
|
|
38 |
The diagnostics are computed at various times and places within the GCM. |
The diagnostics are computed at various times and places within the GCM. |
39 |
Some diagnostics are computed on the geophysical A-grid (such as |
Some diagnostics are computed on the A-grid (such as those within the fizhi routines), |
40 |
those within the Physics routines), while others are computed on the C-grid |
while others are computed on the C-grid (those computed during the dynamics time-stepping). |
41 |
(those computed during the dynamics time-stepping). Some diagnostics are |
Some diagnostics are scalars, while others are vectors. Each of these possibilities requires |
|
scalars, while others are vectors. Each of these possibilities requires |
|
42 |
separate tasks for A-grid to C-grid transformations and coordinate transformations. Due |
separate tasks for A-grid to C-grid transformations and coordinate transformations. Due |
43 |
to this complexity, and since the specific diagnostics enabled are User determined at the |
to this complexity, and since the specific diagnostics enabled are User determined at the |
44 |
time of the run, |
time of the run, |
65 |
parse(2) & $\rightarrow$ U & C-Grid U-Point \\ |
parse(2) & $\rightarrow$ U & C-Grid U-Point \\ |
66 |
& $\rightarrow$ V & C-Grid V-Point \\ |
& $\rightarrow$ V & C-Grid V-Point \\ |
67 |
& $\rightarrow$ M & C-Grid Mass Point \\ |
& $\rightarrow$ M & C-Grid Mass Point \\ |
68 |
& $\rightarrow$ Z & C-Grid Vorticity Point \\ \hline |
& $\rightarrow$ Z & C-Grid Vorticity (Corner) Point \\ \hline |
69 |
parse(3) & $\rightarrow$ R & Computed on the Rotated Grid \\ |
parse(3) & $\rightarrow$ R & Not Currently in Use \\ \hline |
|
& $\rightarrow$ G & Computed on the Geophysical Grid \\ \hline |
|
70 |
parse(4) & $\rightarrow$ P & Positive Definite Diagnostic \\ \hline |
parse(4) & $\rightarrow$ P & Positive Definite Diagnostic \\ \hline |
71 |
parse(5) & $\rightarrow$ C & Counter Diagnostic \\ |
parse(5) & $\rightarrow$ C & Counter Diagnostic \\ |
72 |
& $\rightarrow$ D & Disabled Diagnostic for output \\ \hline |
& $\rightarrow$ D & Disabled Diagnostic for output \\ \hline |
78 |
\end{table} |
\end{table} |
79 |
|
|
80 |
As an example, consider a diagnostic whose associated GDIAG parameter is equal |
As an example, consider a diagnostic whose associated GDIAG parameter is equal |
81 |
to ``UUR 002''. From GDIAG we can determine that this diagnostic is a |
to ``UU 002''. From GDIAG we can determine that this diagnostic is a |
82 |
U-vector component located at the C-grid U-point within the Rotated framework. |
U-vector component located at the C-grid U-point. |
83 |
Its corresponding V-component diagnostic is located in Diagnostic \# 002. |
Its corresponding V-component diagnostic is located in Diagnostic \# 002. |
84 |
|
|
85 |
In this way, each Diagnostic in the model has its attributes (ie. vector or scalar, |
In this way, each Diagnostic in the model has its attributes (ie. vector or scalar, |
86 |
rotated or geophysical, A-Grid or C-grid, etc.) defined internally. The Output routines |
A-Grid or C-grid, etc.) defined internally. The Output routines |
87 |
use this information in order to determine |
use this information in order to determine |
88 |
what type of rotations and/or transformations need to be performed. Thus, all Diagnostic |
what type of transformations need to be performed. Thus, all Diagnostic |
89 |
interpolations are done at the time of output rather than during each model dynamic step. |
interpolations are done at the time of output rather than during each model dynamic step. |
90 |
In this way the User now has more flexibility |
In this way the User now has more flexibility |
91 |
in determining the type of gridded data which is output. |
in determining the type of gridded data which is output. |
92 |
|
|
93 |
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, |
94 |
clear, and retrieve model diagnostics, and may be called from any user-supplied application |
clear, write and retrieve model diagnostics, and may be called from any routine. |
95 |
and/or output routine. The available utilities and the CALL sequences are listed below. |
The available utilities and the CALL sequences are listed below. |
96 |
|
|
97 |
|
{\bf fill\_diag}: This routine will increment |
98 |
|
|
99 |
{\bf SETDIAG}: This subroutine enables a diagnostic from the Diagnostic Menu, meaning that |
{\bf setdiag}: This subroutine enables a diagnostic from the Diagnostic Menu, meaning |
100 |
space is allocated for the diagnostic and the |
that space is allocated for the diagnostic and the model routines will increment the |
101 |
model routines will increment the diagnostic value during execution. This routine is useful when |
diagnostic value during execution. This routine is the underlying interface |
|
called from either user application routines or user output routines, and is the underlying interface |
|
102 |
between the user and the desired diagnostic. The diagnostic is referenced by its diagnostic |
between the user and the desired diagnostic. The diagnostic is referenced by its diagnostic |
103 |
number from the menu, and its calling sequence is given by: |
number from the menu, and its calling sequence is given by: |
104 |
|
|
105 |
\begin{tabbing} |
\begin{tabbing} |
106 |
XXXXXXXXX\=XXXXXX\= \kill |
XXXXXXXXX\=XXXXXX\= \kill |
107 |
\> CALL SETDIAG (NUM) \\ |
\> call setdiag (num) \\ |
108 |
\\ |
\\ |
109 |
where \> NUM \>= Diagnostic number from menu \\ |
where \> num \>= Diagnostic number from menu \\ |
110 |
\end{tabbing} |
\end{tabbing} |
111 |
|
|
112 |
|
{\bf getdiag}: This subroutine retrieves the value of a model diagnostic. This routine |
113 |
{\bf GETDIAG}: This subroutine retrieves the value of a model diagnostic. This routine is |
is particulary useful when called from a user output routine, although it can be called |
114 |
particulary useful when called from a user output routine, although it can be called from an |
from any routine. This routine returns the time-averaged value of the diagnostic by |
115 |
application routine as well. This routine returns the time-averaged value of the diagnostic by |
dividing the current accumulated diagnostic value by its corresponding counter. This |
116 |
dividing the current accumulated diagnostic value by its corresponding counter. This routine does |
routine does not change the value of the diagnostic itself, that is, it does not replace |
117 |
not change the value of the diagnostic itself, that is, it does not replace the diagnostic with its |
the diagnostic with its time-average. The calling sequence for this routine is givin by: |
|
time-average. The calling sequence for this routine is givin by: |
|
118 |
|
|
119 |
\begin{tabbing} |
\begin{tabbing} |
120 |
XXXXXXXXX\=XXXXXX\= \kill |
XXXXXXXXX\=XXXXXX\= \kill |
121 |
\> CALL GETDIAG (LEV,NUM,QTMP,UNDEF) \\ |
\> call getdiag (lev,num,qtmp,undef) \\ |
122 |
\\ |
\\ |
123 |
where \> LEV \>= Model Level at which the diagnostic is desired \\ |
where \> lev \>= Model Level at which the diagnostic is desired \\ |
124 |
\> NUM \>= Diagnostic number from menu \\ |
\> num \>= Diagnostic number from menu \\ |
125 |
\> QTMP \>= Time-Averaged Diagnostic Output \\ |
\> qtmp \>= Time-Averaged Diagnostic Output \\ |
126 |
\> UNDEF \>= Fill value to be used when diagnostic is undefined \\ |
\> undef \>= Fill value to be used when diagnostic is undefined \\ |
127 |
\end{tabbing} |
\end{tabbing} |
128 |
|
|
129 |
{\bf CLRDIAG}: This subroutine initializes the values of model diagnostics to zero, and is |
{\bf clrdiag}: This subroutine initializes the values of model diagnostics to zero, and is |
130 |
particularly useful when called from user output routines to re-initialize diagnostics during the |
particularly useful when called from user output routines to re-initialize diagnostics |
131 |
run. The calling sequence is: |
during the run. The calling sequence is: |
|
|
|
132 |
|
|
133 |
\begin{tabbing} |
\begin{tabbing} |
134 |
XXXXXXXXX\=XXXXXX\= \kill |
XXXXXXXXX\=XXXXXX\= \kill |
135 |
\> CALL CLRDIAG (NUM) \\ |
\> call clrdiag (num) \\ |
136 |
\\ |
\\ |
137 |
where \> NUM \>= Diagnostic number from menu \\ |
where \> num \>= Diagnostic number from menu \\ |
138 |
\end{tabbing} |
\end{tabbing} |
139 |
|
|
140 |
|
{\bf zapdiag}: This entry into subroutine SETDIAG disables model diagnostics, meaning |
141 |
|
that the diagnostic is no longer available to the user. The memory previously allocated |
142 |
{\bf ZAPDIAG}: This entry into subroutine SETDIAG disables model diagnostics, meaning that the |
to the diagnostic is released when ZAPDIAG is invoked. The calling sequence is given by: |
|
diagnostic is no longer available to the user. The memory previously allocated to the diagnostic |
|
|
is released when ZAPDIAG is invoked. The calling sequence is given by: |
|
|
|
|
143 |
|
|
144 |
\begin{tabbing} |
\begin{tabbing} |
145 |
XXXXXXXXX\=XXXXXX\= \kill |
XXXXXXXXX\=XXXXXX\= \kill |
146 |
\> CALL ZAPDIAG (NUM) \\ |
\> call zapdiag (NUM) \\ |
147 |
\\ |
\\ |
148 |
where \> NUM \>= Diagnostic number from menu \\ |
where \> num \>= Diagnostic number from menu \\ |
149 |
\end{tabbing} |
\end{tabbing} |
150 |
|
|
151 |
{\bf DIAGSIZE}: We end this section with a discussion on the manner in which computer memory |
{\bf diagsize}: We end this section with a discussion on the manner in which computer |
152 |
is allocated for diagnostics. |
memory is allocated for diagnostics. All GCM diagnostic quantities are stored in the |
153 |
All GCM diagnostic quantities are stored in the single |
single diagnostic array QDIAG which is located in diagnostics.h, and has the form: |
154 |
diagnostic array QDIAG which is located in the DIAG COMMON, having the form: |
|
155 |
|
common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) |
156 |
\begin{tabbing} |
|
157 |
XXXXXXXXX\=XXXXXX\= \kill |
where numdiags is an Integer variable which should be |
158 |
\> COMMON /DIAG/ NDIAG\_MAX,QDIAG(IM,JM,1) \\ |
set equal to the number of enabled diagnostics, and qdiag is a three-dimensional |
159 |
\\ |
array. The first two-dimensions of qdiag correspond to the horizontal dimension |
160 |
\end{tabbing} |
of a given diagnostic, while the third dimension of qdiag is used to identify |
|
|
|
|
where NDIAG\_MAX is an Integer variable which should be |
|
|
set equal to the number of enabled diagnostics, and QDIAG is a three-dimensional |
|
|
array. The first two-dimensions of QDIAG correspond to the horizontal dimension |
|
|
of a given diagnostic, while the third dimension of QDIAG is used to identify |
|
161 |
specific diagnostic types. |
specific diagnostic types. |
162 |
In order to minimize the maximum memory requirement used by the model, |
In order to minimize the memory requirement of the model for diagnostics, |
163 |
the default GCM executable is compiled with room for only one horizontal |
the default GCM executable is compiled with room for only one horizontal |
164 |
diagnostic array, as shown in the above example. |
diagnostic array, as shown in the above example. |
165 |
In order for the User to enable more than 1 two-dimensional diagnostic, |
In order for the User to enable more than 1 two-dimensional diagnostic, |
166 |
the size of the DIAG COMMON must be expanded to accomodate the desired diagnostics. |
the size of the diagnostics common must be expanded to accomodate the desired diagnostics. |
167 |
This can be accomplished by manually changing the parameter numdiags in the |
This can be accomplished by manually changing the parameter numdiags in the |
168 |
file \filelink{FORWARD\_STEP}{pkg-diagnostics-diagnostics_SIZE.h}, or by allowing the |
file \filelink{pkg/diagnostics/diagnostics\_SIZE.h}{pkg-diagnostics-diagnostics_SIZE.h}, or by allowing the |
169 |
shell script (???????) to make this |
shell script (???????) to make this |
170 |
change based on the choice of diagnostic output made in the namelist. |
change based on the choice of diagnostic output made in the namelist. |
171 |
|
|
172 |
|
\subsection{Usage Notes} |
173 |
|
\label{sec:diagnostics:usersguide} |
174 |
|
To use the diagnostics package, other than enabling it in packages.conf |
175 |
|
and turning the usediagnostics flag in data.pkg to .TRUE., a namelist |
176 |
|
must be supplied in the run directory called data.diagnostics. The namelist |
177 |
|
will activate a user-defined list of diagnostics quantities to be computed, |
178 |
|
specify the frequency of output, the number of levels, and the name of |
179 |
|
up to 10 separate output files. A sample data.diagnostics namelist file: |
180 |
|
|
181 |
|
$\#$ Diagnostic Package Choices |
182 |
|
$\&$diagnostics\_list |
183 |
|
frequency(1) = 10, \ |
184 |
|
levels(1,1) = 1.,2.,3.,4.,5., \ |
185 |
|
fields(1,1) = 'UVEL ','VVEL ', \ |
186 |
|
filename(1) = 'diagout1', \ |
187 |
|
frequency(2) = 100, \ |
188 |
|
levels(1,2) = 1.,2.,3.,4.,5., \ |
189 |
|
fields(1,2) = 'THETA ','SALT ', \ |
190 |
|
filename(2) = 'diagout2', \ |
191 |
|
$\&$end \ |
192 |
|
|
193 |
|
In this example, there are two output files that will be generated |
194 |
|
for each tile and for each output time. The first set of output files |
195 |
|
has the prefix diagout1, does time averaging every 10 time steps, |
196 |
|
for fields which are multiple-level fields the levels output are 1-5, |
197 |
|
and the names of diagnostics quantities are UVEL and VVEL. |
198 |
|
The second set of output files |
199 |
|
has the prefix diagout2, does time averaging every 100 time steps, |
200 |
|
for fields which are multiple-level fields the levels output are 1-5, |
201 |
|
and the names of diagnostics quantities are THETA and SALT. |
202 |
|
|
203 |
\newpage |
\newpage |
204 |
|
|
205 |
\subsubsection{GCM Diagnostic Menu} |
\subsubsection{GCM Diagnostic Menu} |
641 |
{\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t) |
{\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t) |
642 |
\] |
\] |
643 |
where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the |
where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the |
644 |
output frequency of the diagnositc, and $\Delta t$ is |
output frequency of the diagnostic, and $\Delta t$ is |
645 |
the timestep over which the diagnostic is updated. For further information on how |
the timestep over which the diagnostic is updated. |
|
to set the diagnostic output frequency {\bf NQDIAG}, please see Part III, A User's Guide. |
|
646 |
|
|
647 |
{\bf 1) \underline {UFLUX} Surface Zonal Wind Stress on the Atmosphere ($Newton/m^2$) } |
{\bf 1) \underline {UFLUX} Surface Zonal Wind Stress on the Atmosphere ($Newton/m^2$) } |
648 |
|
|