/[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.3 by molod, Thu Oct 14 15:28:53 2004 UTC revision 1.5 by molod, Fri Oct 15 18:40:33 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  This section of the documentation describes the Diagnostics package available within
10  the GCM.  In addition to a description on how to set and extract diagnostic quantities,  the GCM.  In addition to a description of how to set and extract diagnostic quantities,
11  this document also provides a comprehensive list of all available diagnostic quantities  this document also provides a comprehensive list of all available diagnostic quantities
12  and a short description of how they are computed.  It should be noted that this document  and a short description of how they are computed.  It should be noted that this document
13  is not intended to be a complete documentation of the various packages used in the GCM,  is not intended to be a complete documentation of the various packages used in the GCM,
# Line 22  Not relevant. Line 22  Not relevant.
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 280 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 93  In this way the User now has more flexib Line 91  In this way the User now has more flexib
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:
 diagnostic array QDIAG which is located in diagnostics.h, and has the form:  
154    
155  common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)  common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)
156    
157  where numdiags is an Integer variable which should be  where numdiags is an Integer variable which should be
158  set equal to the number of enabled diagnostics, and QDIAG is a three-dimensional  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  array.  The first two-dimensions of qdiag correspond to the horizontal dimension
160  of a given diagnostic, while the third dimension of QDIAG is used to identify  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 memory requirement of the model for diagnostics,  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
# Line 186  will activate a user-defined list of dia Line 178  will activate a user-defined list of dia
178  specify the frequency of output, the number of levels, and the name of  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:  up to 10 separate output files. A sample data.diagnostics namelist file:
180    
181    <<<<<<< diagnostics.tex
182    $\#$ Diagnostic Package Choices
183     $\&$diagnostics\_list
184    =======
185    \begin{verbatim}
186  \# Diagnostic Package Choices  \# Diagnostic Package Choices
187   \&diagnostics_list   \&diagnostics_list
188    >>>>>>> 1.4
189    frequency(1) = 10, \    frequency(1) = 10, \
190     levels(1,1) = 1.,2.,3.,4.,5., \     levels(1,1) = 1.,2.,3.,4.,5., \
191     fields(1,1) = 'UVEL    ','VVEL    ', \     fields(1,1) = 'UVEL    ','VVEL    ', \
# Line 196  up to 10 separate output files. A sample Line 194  up to 10 separate output files. A sample
194     levels(1,2) = 1.,2.,3.,4.,5., \     levels(1,2) = 1.,2.,3.,4.,5., \
195     fields(1,2) = 'THETA   ','SALT    ', \     fields(1,2) = 'THETA   ','SALT    ', \
196     filename(2) = 'diagout2', \     filename(2) = 'diagout2', \
197    <<<<<<< diagnostics.tex
198     $\&$end \
199    =======
200   \&end \   \&end \
201    \end{verbatim}
202    >>>>>>> 1.4
203    
204  In this example, there are two output files that will be generated  In this example, there are two output files that will be generated
205  for each tile and for each output time. The first set of output files  for each tile and for each output time. The first set of output files
# Line 649  is time-averaged over its diagnostic out Line 652  is time-averaged over its diagnostic out
652  {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t)  {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t)
653  \]  \]
654  where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the  where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the
655  output frequency of the diagnositc, and $\Delta t$ is  output frequency of the diagnostic, and $\Delta t$ is
656  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.  
657    
658  {\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$) }
659    
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.5
  ViewVC Help
Powered by ViewVC 1.1.22