--- manual/s_phys_pkgs/diagnostics.tex 2004/01/28 21:00:10 1.1 +++ manual/s_phys_pkgs/diagnostics.tex 2004/10/16 03:40:17 1.6 @@ -1,15 +1,18 @@ -\section{Diagnostics-Flexible model infrastructure for diagnostic (instananeous or time averaged) output} +\section{Diagnostics--A Flexible Infrastructure} +\label{sec:pkg:diagnostics} +\begin{rawhtml} + +\end{rawhtml} \subsection{Introduction} -This section of the documentation describes the Diagnostics Utilities available within the GCM. -In addition to -a description on how to set and extract diagnostic quantities, this document also provides a -comprehensive list of all available diagnostic quantities and a short description of how they are -computed. It should be noted that this document is not intended to be a complete documentation -of the various packages used in the GCM, and the reader should -refer to original publications for further insight. - +This section of the documentation describes the Diagnostics package available within +the GCM. In addition to a description of how to set and extract diagnostic quantities, +this document also provides a comprehensive list of all available diagnostic quantities +and a short description of how they are computed. It should be noted that this document +is not intended to be a complete documentation of the various packages used in the GCM, +and the reader should refer to original publications and the appropriate sections of this +documentation for further insight. \subsection{Equations} Not relevant. @@ -18,26 +21,24 @@ \label{sec:diagnostics:diagover} A large selection of model diagnostics is available in the GCM. At the time of -this writing there are 92 different diagnostic quantities which can be enabled for an -experiment. As a matter of philosophy, no diagnostic is enabled as default, thus each user must -specify the exact diagnostic information required for an experiment. This is accomplished by -enabling the specific diagnostic of interest cataloged in the +this writing there are 280 different diagnostic quantities which can be enabled for an +experiment. As a matter of philosophy, no diagnostic is enabled as default, thus each +user must specify the exact diagnostic information required for an experiment. This +is accomplished by enabling the specific diagnostic of interest cataloged in the Diagnostic Menu (see Section \ref{sec:diagnostics:menu}). -The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within the -GCM. Diagnostics are internally referred to by their associated number in the Diagnostic +The Diagnostic Menu is a hard-wired enumeration of diagnostic quantities available within +the GCM. Diagnostics are internally referred to by their associated number in the Diagnostic Menu. Once a diagnostic is enabled, the GCM will continually increment an array -specifically allocated for that diagnostic whenever the associated process for the diagnostic is -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. +specifically allocated for that diagnostic whenever the associated process for the +diagnostic is 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 +Some diagnostics are computed on the A-grid (such as those within the fizhi 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, @@ -64,9 +65,8 @@ parse(2) & $\rightarrow$ U & C-Grid U-Point \\ & $\rightarrow$ V & C-Grid V-Point \\ & $\rightarrow$ M & C-Grid Mass Point \\ - & $\rightarrow$ Z & C-Grid Vorticity Point \\ \hline - parse(3) & $\rightarrow$ R & Computed on the Rotated Grid \\ - & $\rightarrow$ G & Computed on the Geophysical Grid \\ \hline + & $\rightarrow$ Z & C-Grid Vorticity (Corner) Point \\ \hline + parse(3) & $\rightarrow$ R & Not Currently in Use \\ \hline parse(4) & $\rightarrow$ P & Positive Definite Diagnostic \\ \hline parse(5) & $\rightarrow$ C & Counter Diagnostic \\ & $\rightarrow$ D & Disabled Diagnostic for output \\ \hline @@ -78,107 +78,128 @@ \end{table} As an example, consider a diagnostic whose associated GDIAG parameter is equal -to ``UUR 002''. From GDIAG we can determine that this diagnostic is a -U-vector component located at the C-grid U-point within the Rotated framework. +to ``UU 002''. From GDIAG we can determine that this diagnostic is a +U-vector component located at the C-grid U-point. Its corresponding V-component diagnostic is located in Diagnostic \# 002. In this way, each Diagnostic in the model has its attributes (ie. vector or scalar, -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 use this information in order to determine -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 interpolations are done at the time of output rather than during each model dynamic step. In this way the User now has more flexibility in determining the type of gridded data which is output. There are several utilities within the GCM available to users to enable, disable, -clear, and retrieve model diagnostics, and may be called from any user-supplied application -and/or output routine. The available utilities and the CALL sequences are listed below. +clear, write and retrieve model diagnostics, and may be called from any routine. +The available utilities and the CALL sequences are listed below. +{\bf fill\_diag}: This routine will increment -{\bf SETDIAG}: This subroutine enables a diagnostic from the Diagnostic Menu, meaning that -space is allocated for the diagnostic and the -model routines will increment the diagnostic value during execution. This routine is useful when -called from either user application routines or user output routines, and is the underlying interface +{\bf setdiag}: This subroutine enables a diagnostic from the Diagnostic Menu, meaning +that space is allocated for the diagnostic and the model routines will increment the +diagnostic value during execution. This routine 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: \begin{tabbing} XXXXXXXXX\=XXXXXX\= \kill -\> CALL SETDIAG (NUM) \\ +\> call setdiag (num) \\ \\ -where \> NUM \>= Diagnostic number from menu \\ +where \> num \>= Diagnostic number from menu \\ \end{tabbing} - -{\bf GETDIAG}: This subroutine retrieves the value of a model diagnostic. This routine is -particulary useful when called from a user output routine, although it can be called from an -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 routine does -not change the value of the diagnostic itself, that is, it does not replace the diagnostic with its -time-average. The calling sequence for this routine is givin by: +{\bf getdiag}: This subroutine retrieves the value of a model diagnostic. This routine +is particulary useful when called from a user output routine, although it can be called +from any routine. This routine returns the time-averaged value of the diagnostic by +dividing the current accumulated diagnostic value by its corresponding counter. This +routine does not change the value of the diagnostic itself, that is, it does not replace +the diagnostic with its time-average. The calling sequence for this routine is givin by: \begin{tabbing} XXXXXXXXX\=XXXXXX\= \kill -\> CALL GETDIAG (LEV,NUM,QTMP,UNDEF) \\ +\> call getdiag (lev,num,qtmp,undef) \\ \\ -where \> LEV \>= Model Level at which the diagnostic is desired \\ - \> NUM \>= Diagnostic number from menu \\ - \> QTMP \>= Time-Averaged Diagnostic Output \\ - \> UNDEF \>= Fill value to be used when diagnostic is undefined \\ +where \> lev \>= Model Level at which the diagnostic is desired \\ + \> num \>= Diagnostic number from menu \\ + \> qtmp \>= Time-Averaged Diagnostic Output \\ + \> undef \>= Fill value to be used when diagnostic is undefined \\ \end{tabbing} -{\bf CLRDIAG}: This subroutine initializes the values of model diagnostics to zero, and is -particularly useful when called from user output routines to re-initialize diagnostics during the -run. The calling sequence is: - +{\bf clrdiag}: This subroutine initializes the values of model diagnostics to zero, and is +particularly useful when called from user output routines to re-initialize diagnostics +during the run. The calling sequence is: \begin{tabbing} XXXXXXXXX\=XXXXXX\= \kill -\> CALL CLRDIAG (NUM) \\ +\> call clrdiag (num) \\ \\ -where \> NUM \>= Diagnostic number from menu \\ +where \> num \>= Diagnostic number from menu \\ \end{tabbing} - - -{\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: - +{\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: \begin{tabbing} XXXXXXXXX\=XXXXXX\= \kill -\> CALL ZAPDIAG (NUM) \\ +\> call zapdiag (NUM) \\ \\ -where \> NUM \>= Diagnostic number from menu \\ +where \> num \>= Diagnostic number from menu \\ \end{tabbing} -{\bf DIAGSIZE}: We end this section with a discussion on the manner in which computer memory -is allocated for diagnostics. -All GCM diagnostic quantities are stored in the single -diagnostic array QDIAG which is located in the DIAG COMMON, having the form: - -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> COMMON /DIAG/ NDIAG\_MAX,QDIAG(IM,JM,1) \\ -\\ -\end{tabbing} - -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 +{\bf diagsize}: We end this section with a discussion on the manner in which computer +memory is allocated for diagnostics. All GCM diagnostic quantities are stored in the +single diagnostic array QDIAG which is located in diagnostics.h, and has the form: + +common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) + +where numdiags 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 specific diagnostic types. -In order to minimize the maximum memory requirement used by the model, +In order to minimize the memory requirement of the model for diagnostics, the default GCM executable is compiled with room for only one horizontal diagnostic array, as shown in the above example. In order for the User to enable more than 1 two-dimensional diagnostic, -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. This can be accomplished by manually changing the parameter numdiags in the -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 shell script (???????) to make this change based on the choice of diagnostic output made in the namelist. +\subsection{Usage Notes} +\label{sec:diagnostics:usersguide} +To use the diagnostics package, other than enabling it in packages.conf +and turning the usediagnostics flag in data.pkg to .TRUE., a namelist +must be supplied in the run directory called data.diagnostics. The namelist +will activate a user-defined list of diagnostics quantities to be computed, +specify the frequency of output, the number of levels, and the name of +up to 10 separate output files. A sample data.diagnostics namelist file: + +$\#$ Diagnostic Package Choices + $\&$diagnostics\_list + frequency(1) = 10, \ + levels(1,1) = 1.,2.,3.,4.,5., \ + fields(1,1) = 'UVEL ','VVEL ', \ + filename(1) = 'diagout1', \ + frequency(2) = 100, \ + levels(1,2) = 1.,2.,3.,4.,5., \ + fields(1,2) = 'THETA ','SALT ', \ + filename(2) = 'diagout2', \ + $\&$end \ + +In this example, there are two output files that will be generated +for each tile and for each output time. The first set of output files +has the prefix diagout1, does time averaging every 10 time steps, +for fields which are multiple-level fields the levels output are 1-5, +and the names of diagnostics quantities are UVEL and VVEL. +The second set of output files +has the prefix diagout2, does time averaging every 100 time steps, +for fields which are multiple-level fields the levels output are 1-5, +and the names of diagnostics quantities are THETA and SALT. + \newpage \subsubsection{GCM Diagnostic Menu} @@ -620,9 +641,8 @@ {\bf DIAGNOSTIC} = {1 \over TTOT} \sum_{t=1}^{t=TTOT} diag(t) \] where $TTOT = {{\bf NQDIAG} \over \Delta t}$, {\bf NQDIAG} is the -output frequency of the diagnositc, and $\Delta t$ is -the timestep over which the diagnostic is updated. For further information on how -to set the diagnostic output frequency {\bf NQDIAG}, please see Part III, A User's Guide. +output frequency of the diagnostic, and $\Delta t$ is +the timestep over which the diagnostic is updated. {\bf 1) \underline {UFLUX} Surface Zonal Wind Stress on the Atmosphere ($Newton/m^2$) }