/[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.1 by molod, Wed Jan 28 21:00:10 2004 UTC revision 1.6 by edhill, Sat Oct 16 03:40:17 2004 UTC
# Line 1  Line 1 
1  \section{Diagnostics-Flexible model infrastructure for diagnostic (instananeous or time averaged) output}  \section{Diagnostics--A Flexible Infrastructure}
2    \label{sec:pkg:diagnostics}
3    \begin{rawhtml}
4    <!-- CMIREDIR:package_diagnostics: -->
5    \end{rawhtml}
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.
# Line 18  Not relevant. Line 21  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,
# Line 64  Array & Value & Description \\ Line 65  Array & Value & Description \\
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
# Line 78  Array & Value & Description \\ Line 78  Array & Value & Description \\
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}
# Line 620  is time-averaged over its diagnostic out Line 641  is time-averaged over its diagnostic out
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    
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.6
  ViewVC Help
Powered by ViewVC 1.1.22