/[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.2 by edhill, Tue Oct 12 18:16:03 2004 UTC revision 1.7 by molod, Mon Oct 18 19:43:56 2004 UTC
# Line 6  Line 6 
6    
7  \subsection{Introduction}  \subsection{Introduction}
8    
9  This section of the documentation describes the Diagnostics Utilities available within the GCM.    \noindent
10  In addition to  This section of the documentation describes the Diagnostics package available within
11  a description on how to set and extract diagnostic quantities, this document also provides a  the GCM.  A large selection of model diagnostics is available for output.  
12  comprehensive list of all available diagnostic quantities and a short description of how they are  In addition to the diagnostic quantities pre-defined in the GCM, there exists
13  computed.  It should be noted that this document is not intended to be a complete documentation  the option, in any experiment, to define a new diagnostic quantity and include it
14  of the various packages used in the GCM, and the reader should  as part of the diagnostic output with the addition of a single subroutine call in the
15  refer to original publications for further insight.  routine where the field is computed. As a matter of philosophy, no diagnostic is enabled
16    as default, thus each user must specify the exact diagnostic information required for an
17    experiment.  This is accomplished by enabling the specific diagnostic of interest cataloged
18    in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). Instructions for enabling
19    diagnostic output and defining new diagnostic quantities are found in Section
20    \ref{sec:diagnostics:usersguide} of this document.
21    
22    \noindent
23    The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within
24    the GCM. Once a diagnostic is enabled, the GCM will continually increment an array
25    specifically allocated for that diagnostic whenever the appropriate quantity is computed.  
26    A counter is defined which records how many times each diagnostic quantity has been
27    incremented.  Several special diagnostics are included in the menu. Quantities refered to
28    as ``Counter Diagnostics'', are defined for selected diagnostics which record the
29    frequency at which a diagnostic is incremented separately for each model grid location.
30    Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate
31    defining new diagnostics for a particular experiment.
32    
33  \subsection{Equations}  \subsection{Equations}
34  Not relevant.  Not relevant.
# Line 21  Not relevant. Line 36  Not relevant.
36  \subsection{Key Subroutines and Parameters}  \subsection{Key Subroutines and Parameters}
37  \label{sec:diagnostics:diagover}  \label{sec:diagnostics:diagover}
38    
39  A large selection of model diagnostics is available in the GCM.  At the time of  \noindent
40  this writing there are 92 different diagnostic quantities which can be enabled for an  The diagnostics are computed at various times and places within the GCM. Because the
41  experiment.  As a matter of philosophy, no diagnostic is enabled as default, thus each user must  MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers,
42  specify the exact diagnostic information required for an experiment.  This is accomplished by  corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars,
43  enabling the specific diagnostic of interest cataloged in the  while others are components of vectors. An internal array is defined which contains
44  Diagnostic Menu (see Section \ref{sec:diagnostics:menu}).  information concerning various grid attributes of each diagnostic. The GDIAG
45  The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within the  array (in common block \\diagnostics in file diagnostics.h) is internally defined as a
46  GCM.  Diagnostics are internally referred to by their associated number in the Diagnostic  character*8 variable, and is equivalenced to a character*1 "parse" array in output in
47  Menu.  Once a diagnostic is enabled, the GCM will continually increment an array  order to extract the grid-attribute information.  The GDIAG array is described in
48  specifically allocated for that diagnostic whenever the associated process for the diagnostic is  Table \ref{tab:diagnostics:gdiag.tabl}.
 computed.  Separate arrays are used both for the diagnostic quantity and its diagnostic counter  
 which records how many times each diagnostic quantity has been computed.  In addition  
 special diagnostics, called  
 ``Counter Diagnostics'', records the frequency of diagnostic updates separately for each  
 model grid location.  
   
 The diagnostics are computed at various times and places within the GCM.    
 Some diagnostics are computed on the geophysical A-grid (such as  
 those within the Physics routines), while others are computed on the C-grid  
 (those computed during the dynamics time-stepping).  Some diagnostics are  
 scalars, while others are vectors.  Each of these possibilities requires  
 separate tasks for A-grid to C-grid transformations and coordinate transformations.  Due  
 to this complexity, and since the specific diagnostics enabled are User determined at the  
 time of the run,  
 a diagnostic parameter has been developed and implemented into the GCM, defined as GDIAG,  
 which contains information concerning various grid attributes of each diagnostic.  The GDIAG  
 array 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}.  
49    
50  \begin{table}  \begin{table}
51  \caption{Diagnostic Parsing Array}  \caption{Diagnostic Parsing Array}
# Line 68  Array & Value & Description \\ Line 64  Array & Value & Description \\
64    parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\    parse(2)   & $\rightarrow$ U &  C-Grid U-Point                    \\
65               & $\rightarrow$ V &  C-Grid V-Point                    \\               & $\rightarrow$ V &  C-Grid V-Point                    \\
66               & $\rightarrow$ M &  C-Grid Mass Point                 \\               & $\rightarrow$ M &  C-Grid Mass Point                 \\
67               & $\rightarrow$ Z &  C-Grid Vorticity Point            \\ \hline               & $\rightarrow$ Z &  C-Grid Vorticity (Corner) Point   \\ \hline
68    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  
69    parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline    parse(4)   & $\rightarrow$ P &  Positive Definite Diagnostic      \\ \hline
70    parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\    parse(5)   & $\rightarrow$ C &  Counter Diagnostic                \\
71               & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline               & $\rightarrow$ D &  Disabled Diagnostic for output    \\ \hline
# Line 81  Array & Value & Description \\ Line 76  Array & Value & Description \\
76  \end{center}  \end{center}
77  \end{table}  \end{table}
78    
79    
80    \noindent
81  As an example, consider a diagnostic whose associated GDIAG parameter is equal  As an example, consider a diagnostic whose associated GDIAG parameter is equal
82  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
83  U-vector component located at the C-grid U-point within the Rotated framework.  U-vector component located at the C-grid U-point.
84  Its corresponding V-component diagnostic is located in Diagnostic \# 002.  Its corresponding V-component diagnostic is located in Diagnostic \# 002.
85    
86    
87    \noindent
88  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,
89  rotated or geophysical, A-Grid or C-grid, etc.) defined internally.  The Output routines  C-grid location, etc.) defined internally.  The Output routines use this information
90  use this information in order to determine  in order to determine what type of transformations need to be performed.  Any
91  what type of rotations and/or transformations need to be performed.  Thus, all Diagnostic  interpolations are done at the time of output rather than during each model step.
92  interpolations are done at the time of output rather than during each model dynamic step.  In this way the User has flexibility in determining the type of gridded data which
93  In this way the User now has more flexibility  is output.
94  in determining the type of gridded data which is output.  
95    
96    \noindent
97  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,
98  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.  
99  and/or output routine.  The available utilities and the CALL sequences are listed below.  The available utilities and the CALL sequences are listed below.
100    
101    
102  {\bf SETDIAG}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning that  \noindent
103  space is allocated for the diagnostic and the  {\bf fill\_diagnostics}:  This routine will increment the specified diagnostic
104  model routines will increment the diagnostic value during execution.  This routine is useful when  quantity with a field sent through the argument list.
 called from either user application routines or user output routines, and is the underlying interface  
 between the user and the desired diagnostic.  The diagnostic is referenced by its diagnostic  
 number from the menu, and its calling sequence is given by:  
105    
106    
107    \noindent
108  \begin{tabbing}  \begin{tabbing}
109  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
110  \>        CALL SETDIAG (NUM) \\  \>        call fill\_diagnostics (myThid, chardiag, levflg, nlevs, \\
111                    bibjflg, bi, bj, arrayin) \\
112  \\  \\
113  where \>  NUM   \>= Diagnostic number from menu \\  where \>  myThid   \>= Current Process(or) \\
114          \>  chardiag \>= Character *8 expression for diag to fill \\
115          \>  levflg   \>= Integer flag for vertical levels: \\
116          \>           \> 0 indicates multiple levels incremented in qdiag \\
117          \>           \> non-0 (any integer) - WHICH single level to increment. \\
118          \>           \> negative integer - the input data array is single-leveled \\
119          \>           \> positive integer - the input data array is multi-leveled \\
120          \>  nlevs    \>= indicates Number of levels to be filled (1 if levflg <> 0) \\
121          \>           \> positive: fill in "nlevs" levels in the same order as \\
122          \>           \> the input array \\
123          \>           \> negative: fill in -nlevs levels in reverse order. \\
124          \>  bibjflg  \>= Integer flag to indicate instructions for bi bj loop \\
125          \>           \> 0 indicates that the bi-bj loop must be done here \\
126          \>           \> 1 indicates that the bi-bj loop is done OUTSIDE \\
127          \>           \> 2 indicates that the bi-bj loop is done OUTSIDE \\
128          \>           \>    AND that we have been sent a local array \\
129          \>           \> 3 indicates that the bi-bj loop is done OUTSIDE \\
130          \>           \>    AND that we have been sent a local array \\
131          \>           \>    AND that the array has the shadow regions \\
132          \>  bi       \>= X-direction process(or) number - used for bibjflg=1-3 \\
133          \>  bj       \>= Y-direction process(or) number - used for bibjflg=1-3 \\
134          \>  arrayin  \>= Field to increment diagnostics array \\
135  \end{tabbing}  \end{tabbing}
136    
137    
138  {\bf GETDIAG}:  This subroutine retrieves the value of a model diagnostic.  This routine is  \noindent
139  particulary useful when called from a user output routine, although it can be called from an  {\bf setdiag}:  This subroutine enables a diagnostic from the Diagnostic Menu, meaning
140  application routine as well.  This routine returns the time-averaged value of the diagnostic by  that space is allocated for the diagnostic and the model routines will increment the
141  dividing the current accumulated diagnostic value by its corresponding counter.  This routine does  diagnostic value during execution.  This routine is the underlying interface
142  not change the value of the diagnostic itself, that is, it does not replace the diagnostic with its  between the user and the desired diagnostic.  The diagnostic is referenced by its diagnostic
143  time-average.  The calling sequence for this routine is givin by:  number from the menu, and its calling sequence is given by:
144    
145    \noindent
146  \begin{tabbing}  \begin{tabbing}
147  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
148  \>        CALL GETDIAG (LEV,NUM,QTMP,UNDEF) \\  \>        call setdiag (num) \\
149  \\  \\
150  where \>  LEV   \>= Model Level at which the diagnostic is desired \\  where \>  num   \>= Diagnostic number from menu \\
       \>  NUM   \>= Diagnostic number from menu \\  
       \>  QTMP  \>= Time-Averaged Diagnostic Output \\  
       \>  UNDEF \>= Fill value to be used when diagnostic is undefined \\  
151  \end{tabbing}  \end{tabbing}
152    
153  {\bf CLRDIAG}:  This subroutine initializes the values of model diagnostics to zero, and is  \noindent
154  particularly useful when called from user output routines to re-initialize diagnostics during the  {\bf getdiag}:  This subroutine retrieves the value of a model diagnostic.  This routine
155  run.  The calling sequence is:  is particulary useful when called from a user output routine, although it can be called
156    from any routine.  This routine returns the time-averaged value of the diagnostic by
157    dividing the current accumulated diagnostic value by its corresponding counter.  This
158    routine does not change the value of the diagnostic itself, that is, it does not replace
159    the diagnostic with its time-average.  The calling sequence for this routine is givin by:
160    
161    \noindent
162  \begin{tabbing}  \begin{tabbing}
163  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
164  \>        CALL CLRDIAG (NUM) \\  \>        call getdiag (lev,num,qtmp,undef) \\
165  \\  \\
166  where \>  NUM   \>= Diagnostic number from menu \\  where \>  lev   \>= Model Level at which the diagnostic is desired \\
167          \>  num   \>= Diagnostic number from menu \\
168          \>  qtmp  \>= Time-Averaged Diagnostic Output \\
169          \>  undef \>= Fill value to be used when diagnostic is undefined \\
170  \end{tabbing}  \end{tabbing}
171    
172    \noindent
173    {\bf clrdiag}:  This subroutine initializes the values of model diagnostics to zero, and is
174    particularly useful when called from user output routines to re-initialize diagnostics
175    during the run.  The calling sequence is:
176    
177    \noindent
 {\bf ZAPDIAG}:  This entry into subroutine SETDIAG disables model diagnostics, meaning that the  
 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:  
   
   
178  \begin{tabbing}  \begin{tabbing}
179  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
180  \>        CALL ZAPDIAG (NUM) \\  \>        call clrdiag (num) \\
181  \\  \\
182  where \>  NUM   \>= Diagnostic number from menu \\  where \>  num   \>= Diagnostic number from menu \\
183  \end{tabbing}  \end{tabbing}
184    
185  {\bf DIAGSIZE}:  We end this section with a discussion on the manner in which computer memory    \noindent
186  is allocated for diagnostics.    {\bf zapdiag}:  This entry into subroutine SETDIAG disables model diagnostics, meaning
187  All GCM diagnostic quantities are stored in the single  that the diagnostic is no longer available to the user.  The memory previously allocated
188  diagnostic array QDIAG which is located in the DIAG COMMON, having the form:  to the diagnostic is released when ZAPDIAG is invoked.  The calling sequence is given by:
189    
190    \noindent
191  \begin{tabbing}  \begin{tabbing}
192  XXXXXXXXX\=XXXXXX\= \kill  XXXXXXXXX\=XXXXXX\= \kill
193  \>        COMMON /DIAG/ NDIAG\_MAX,QDIAG(IM,JM,1) \\  \>        call zapdiag (NUM) \\
194  \\  \\
195    where \>  num   \>= Diagnostic number from menu \\
196  \end{tabbing}  \end{tabbing}
197    
198  where NDIAG\_MAX is an Integer variable which should be  
199  set equal to the number of enabled diagnostics, and QDIAG is a three-dimensional  \subsection{Usage Notes}
200  array.  The first two-dimensions of QDIAG correspond to the horizontal dimension  \label{sec:diagnostics:usersguide}
201  of a given diagnostic, while the third dimension of QDIAG is used to identify  
202  specific diagnostic types.  \noindent
203  In order to minimize the maximum memory requirement used by the model,  We begin this section with a discussion on the manner in which computer
204  the default GCM executable is compiled with room for only one horizontal  memory is allocated for diagnostics. All GCM diagnostic quantities are stored in the
205  diagnostic array, as shown in the above example.    single diagnostic array QDIAG which is located in the file \\
206  In order for the User to enable more than 1 two-dimensional diagnostic,  \filelink{pkg/diagnostics/diagnostics.h}{pkg-diagnostics-diagnostics.h}.
207  the size of the DIAG COMMON must be expanded to accomodate the desired diagnostics.  and has the form:
208    
209    common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
210    
211    \noindent
212    where numdiags is an Integer variable which should be set equal to the number of
213    enabled diagnostics, and qdiag is a three-dimensional array.  The first two-dimensions
214    of qdiag correspond to the horizontal dimension of a given diagnostic, while the third
215    dimension of qdiag is used to identify diagnostic fields and levels combined. In order
216    to minimize the memory requirement of the model for diagnostics, the default GCM
217    executable is compiled with room for only one horizontal diagnostic array, or with
218    numdiags set to 1. In order for the User to enable more than 1 two-dimensional diagnostic,
219    the size of the diagnostics common must be expanded to accomodate the desired diagnostics.
220  This can be accomplished by manually changing the parameter numdiags in the  This can be accomplished by manually changing the parameter numdiags in the
221  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}.
222  shell script (???????) to make this  numdiags should be set greater than or equal to the sum of all the diagnostics activated
223  change based on the choice of diagnostic output made in the namelist.  for output each multiplied by the number of levels defined for that diagnostic quantity.
224    This is illustrated in the example below:
225    
226    \noindent
227    To use the diagnostics package, other than enabling it in packages.conf
228    and turning the usediagnostics flag in data.pkg to .TRUE., a namelist
229    must be supplied in the run directory called data.diagnostics. The namelist
230    will activate a user-defined list of diagnostics quantities to be computed,
231    specify the frequency of output, the number of levels, and the name of
232    up to 10 separate output files. A sample data.diagnostics namelist file:
233    
234    \noindent
235    $\#$ Diagnostic Package Choices \\
236     $\&$diagnostics\_list \\
237      frequency(1) = 10, \ \\
238       levels(1,1) = 1.,2.,3.,4.,5., \ \\
239       fields(1,1) = 'UVEL    ','VVEL    ', \ \\
240       filename(1) = 'diagout1', \ \\
241      frequency(2) = 100, \ \\
242       levels(1,2) = 1.,2.,3.,4.,5., \ \\
243       fields(1,2) = 'THETA   ','SALT    ', \ \\
244       filename(2) = 'diagout2', \ \\
245     $\&$end \ \\
246    
247    \noindent
248    In this example, there are two output files that will be generated
249    for each tile and for each output time. The first set of output files
250    has the prefix diagout1, does time averaging every 10 time steps
251    (frequency is 10), they will write fields which are multiple-level
252    fields and output levels 1-5. The names of diagnostics quantities are
253    UVEL and VVEL.  The second set of output files
254    has the prefix diagout2, does time averaging every 100 time steps,
255    they include fields which are multiple-level fields, levels output are 1-5,
256    and the names of diagnostics quantities are THETA and SALT.
257    
258    \noindent
259    In order to define and include as part of the diagnostic output any field
260    that is desired for a particular experiment, two steps must be taken. The
261    first is to enable the ``User Diagnostic'' in data.diagnostics. This is
262    accomplished by setting one of the fields slots to either UDIAG1 through
263    UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level
264    fields. These are listed in the diagnostics menu. The second step is to
265    add a call to fill\_diagnostics from the subroutine in which the quantity
266    desired for diagnostic output is computed.
267    
268  \newpage  \newpage
269    
# Line 624  is time-averaged over its diagnostic out Line 706  is time-averaged over its diagnostic out
706  {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t)  {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t)
707  \]  \]
708  where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the  where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the
709  output frequency of the diagnositc, and $\Delta t$ is  output frequency of the diagnostic, and $\Delta t$ is
710  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.  
711    
712  {\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$) }
713    
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.7
  ViewVC Help
Powered by ViewVC 1.1.22