--- manual/s_outp_pkgs/text/diagnostics.tex 2005/07/18 20:45:27 1.1 +++ manual/s_outp_pkgs/text/diagnostics.tex 2006/04/06 00:46:13 1.4 @@ -1,195 +1,207 @@ -\subsection{Diagnostics--A Flexible Infrastructure} +\section{Diagnostics--A Flexible Infrastructure} \label{sec:pkg:diagnostics} \begin{rawhtml} \end{rawhtml} -\subsubsection{Introduction} +\subsection{Introduction} \noindent -This section of the documentation describes the Diagnostics package available within -the GCM. A large selection of model diagnostics is available for output. -In addition to the diagnostic quantities pre-defined in the GCM, there exists -the option, in any experiment, to define a new diagnostic quantity and include it -as part of the diagnostic output with the addition of a single subroutine call in the -routine where the field is computed. 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}). Instructions for enabling -diagnostic output and defining new diagnostic quantities are found in Section +This section of the documentation describes the Diagnostics package +available within the GCM. A large selection of model diagnostics is +available for output. In addition to the diagnostic quantities +pre-defined in the GCM, there exists the option, in any experiment, to +define a new diagnostic quantity and include it as part of the +diagnostic output with the addition of a single subroutine call in the +routine where the field is computed. 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}). +Instructions for enabling diagnostic output and defining new +diagnostic quantities are found in Section \ref{sec:diagnostics:usersguide} of this document. \noindent -The Diagnostic Menu in this section of the manual is a listing of diagnostic quantities available -within the main (dynamics) part of the GCM. Additional diagnostic quantities, defined within the -different GCM packages, are available and are listed in the diagnostic menu subsection of -the manual section associated with each relevant package. Once a diagnostic is enabled, the -GCM will continually increment an array specifically allocated for that diagnostic whenever the -appropriate quantity is computed. A counter is defined which records how many times each diagnostic -quantity has been incremented. Several special diagnostics are included in the menu. Quantities -refered to as ``Counter Diagnostics'', are defined for selected diagnostics which record the -frequency at which a diagnostic is incremented separately for each model grid location. -Quantitied refered to as ``User Diagnostics'' are included in the menu to facilitate -defining new diagnostics for a particular experiment. +The Diagnostic Menu in this section of the manual is a listing of +diagnostic quantities available within the main (dynamics) part of the +GCM. Additional diagnostic quantities, defined within the different +GCM packages, are available and are listed in the diagnostic menu +subsection of the manual section associated with each relevant +package. Once a diagnostic is enabled, the GCM will continually +increment an array specifically allocated for that diagnostic whenever +the appropriate quantity is computed. A counter is defined which +records how many times each diagnostic quantity has been incremented. +Several special diagnostics are included in the menu. Quantities +refered to as ``Counter Diagnostics'', are defined for selected +diagnostics which record the frequency at which a diagnostic is +incremented separately for each model grid location. Quantitied +refered to as ``User Diagnostics'' are included in the menu to +facilitate defining new diagnostics for a particular experiment. -\subsubsection{Equations} +\subsection{Equations} Not relevant. -\subsubsection{Key Subroutines and Parameters} +\subsection{Key Subroutines and Parameters} \label{sec:diagnostics:diagover} \noindent -There are several utilities within the GCM available to users to enable, disable, -clear, write and retrieve model diagnostics, and may be called from any routine. -The available utilities and the CALL sequences are listed below. - -\noindent -{\bf diagnostics\_fill}: This is the main user interface routine to the diagnostics -package. This routine will increment the specified diagnostic quantity with a field -sent through the argument list. - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call diagnostics\_fill (arrayin, chardiag, levflg, nlevs, \\ -\> bibjflg, bi, bj, myThid) \\ -\\ -where \> arrayin \>= Field to increment diagnostics array \\ - \> chardiag \>= Character *8 expression for diag to fill \\ - \> levflg \>= Integer flag for vertical levels: \\ - \> \>= 0 indicates multiple (nlevs) levels incremented \\ - \> \>= -1 indicates multiple (nlevs) levels incremented, \\ - \> \> but in reverse vertical order \\ - \> \> positive integer - WHICH single level to increment. \\ - \> nlevs \>= indicates Number of levels to be filled (1 if levflg gt 0) \\ - \> bibjflg \>= Integer flag to indicate instructions for bi bj loop \\ - \> \>= 0 indicates that the bi-bj loop must be done here \\ - \> \>= 1 indicates that the bi-bj loop is done OUTSIDE \\ - \> \>= 2 indicates that the bi-bj loop is done OUTSIDE \\ - \> \> AND that we have been sent a local array \\ - \> \> AND that the array has the shadow regions \\ - \> \>= 3 indicates that the bi-bj loop is done OUTSIDE \\ - \> \> AND that we have been sent a local array \\ - \> \> AND that the array has no shadow regions \\ - \> bi \>= X-direction process(or) number - used for bibjflg=1-3 \\ - \> bj \>= Y-direction process(or) number - used for bibjflg=1-3 \\ - \> myThid \>= Current Thread number \\ -\end{tabbing} +There are several utilities within the GCM available to users to +enable, disable, clear, write and retrieve model diagnostics, and may +be called from any routine. The available utilities and the CALL +sequences are listed below. + +\noindent +{\bf diagnostics\_fill}: This is the main user interface routine to +the diagnostics package. This routine will increment the specified +diagnostic quantity with a field sent through the argument list. + +\begin{verbatim} + call diagnostics_fill( + & arrayin, chardiag, levflg, nlevs, + & bibjflg, bi, bj, myThid ) + + where: + arrayin = Field to increment diagnostics array + chardiag = Character *8 expression for diag to fill + levflg = Integer flag for vertical levels: + = 0 indicates multiple (nlevs) levels incremented + = -1 indicates multiple (nlevs) levels incremented, + but in reverse vertical order + positive integer - WHICH single level to increment. + nlevs = indicates Number of levels to be filled (1 if levflg gt 0) + bibjflg = Integer flag to indicate instructions for bi bj loop + = 0 indicates that the bi-bj loop must be done here + = 1 indicates that the bi-bj loop is done OUTSIDE + = 2 indicates that the bi-bj loop is done OUTSIDE + AND that we have been sent a local array + AND that the array has the shadow regions + = 3 indicates that the bi-bj loop is done OUTSIDE + AND that we have been sent a local array + AND that the array has no shadow regions + bi = X-direction process(or) number - used for bibjflg=1-3 + bj = Y-direction process(or) number - used for bibjflg=1-3 + myThid = Current Thread number +\end{verbatim} \noindent {\bf diagnostics\_scale\_fill}: This is a possible alternative routine to diagnostics\_fill which performs the same functions and has an additional option to scale the field before filling or raise the field to a power before filling. -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call diagnostics\_scale\_fill (arrayin, scalefactor, power, chardiag, \\ -\> levflg, nlevs, bibjflg, bi, bj, myThid) \\ -\\ -where \> All the arguments are the same as for diagnostics\_fill with the addition of: \\ - \> scalefactor \>= Factor to scale field \\ - \> power \>= Integer power to which to raise the input field \\ -\end{tabbing} - -\noindent -{\bf diagnostics\_is\_on}: Function call to inquire whether a diagnostic is active -and can be incremented. Useful when there is a computation that must be done locally -before a call to diagnostics\_fill. The call sequence: - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> flag = diagnostics\_is\_on( diagName, myThid ) -\\ -where \> diagName \>= Character *8 expression for diagnostic \\ - \> myThid \>= Current Thread number \\ -\end{tabbing} - -\noindent -{\bf diagnostics\_get\_pointers}: This subroutine retrieves the value of a the diagnostics -pointers that other routines require as input - can be useful if the diagnostics common -blocks are not local to a routine. - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call diagnostics\_get\_pointers( diagName, ipoint, jpoint, myThid ) -\\ -where \> diagName \>= Character *8 expression of diagnostic \\ - \> ipoint \>= Pointer into qdiag array - from idiag array in common \\ - \> jpoint \>= Pointer into diagnostics menu - from jdiag array in common \\ - \> myThid \>= Current Thread number \\ -\end{tabbing} - -\noindent -{\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: - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) \\ -\\ -where \> lev \>= Model Level at which the diagnostic is desired \\ - \> undef \>= Fill value to be used when diagnostic is undefined \\ - \> qtmp \>= Time-Averaged Diagnostic Output \\ - \> ipoint \>= Pointer into qdiag array - from idiag array in common \\ - \> mate \>= Diagnostic mate pointer number \\ - \> bi \>= X-direction process(or) number \\ - \> bj \>= Y-direction process(or) number \\ - \> myThid \>= Current Thread number \\ -\end{tabbing} - -\noindent -{\bf diagnostics\_add2list}: 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 routine -for defining a new permanent diagnostic in the main model or in a package. The calling sequence is: - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call diagnostics\_add2list( diagNum,diagName, diagCode, \\ -\> diagUnits, diagTitle, myThid ) \\ -\\ -where \> diagNum \>=Diagnostic number - Output from routine \\ - \> diagName \>=character*8 diagnostic name \\ - \> diagCode \>=character*16 parsing code (see description of gdiag below) \\ - \> diagUnits \>=Diagnostic units (character*16) \\ - \> diagTitle \>=Diagnostic title or long name (up to character*80) \\ - \> myThid \>=Current Thread number \\ -\end{tabbing} - -\noindent -{\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: - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> call diagnostics\_clrdiag (jpoint, ipoint, myThid) \\ -\\ -where \> jpoint \>= Diagnostic number from menu - from jdiag array \\ - ipoint \>= Pointer number into qdiag array - from idiag array \\ - \> myThid \>=Current Thread number \\ -\end{tabbing} - -\noindent -The diagnostics are computed at various times and places within the GCM. Because the -MIT GCM may employ a staggered grid, diagnostics may be computed at grid box centers, -corners, or edges, and at the middle or edge in the vertical. Some diagnostics are scalars, -while others are components of vectors. An internal array is defined which contains -information concerning various grid attributes of each diagnostic. The GDIAG -array (in common block \\diagnostics in file DIAGNOSTICS.h) 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}. +\begin{verbatim} + call diagnostics_scale_fill( + & arrayin, scalefactor, power, chardiag, + & levflg, nlevs, bibjflg, bi, bj, myThid ) + + where all the arguments are the same as for diagnostics_fill with + the addition of: + scalefactor = Factor to scale field + power = Integer power to which to raise the input field +\end{verbatim} + +\noindent +{\bf diagnostics\_is\_on}: Function call to inquire whether a +diagnostic is active and can be incremented. Useful when there is a +computation that must be done locally before a call to +diagnostics\_fill. The call sequence: + +\begin{verbatim} + flag = diagnostics_is_on( diagName, myThid ) + + where: + diagName = Character *8 expression for diagnostic + myThid = Current Thread number +\end{verbatim} + +\noindent +{\bf diagnostics\_get\_pointers}: This subroutine retrieves the value +of a the diagnostics pointers that other routines require as input - +can be useful if the diagnostics common blocks are not local to a +routine. + +\begin{verbatim} + call diagnostics_get_pointers( diagName, ipoint, jpoint, myThid ) + + where: + diagName = Character *8 expression of diagnostic + ipoint = Pointer into qdiag array - from idiag array in common + jpoint = Pointer into diagnostics menu - from jdiag array in common + myThid = Current Thread number +\end{verbatim} + +\noindent +{\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{verbatim} + call getdiag (lev, undef, qtmp, ipoint, mate, bi, bj, myThid) + + where: + lev = Model Level at which the diagnostic is desired + undef = Fill value to be used when diagnostic is undefined + qtmp = Time-Averaged Diagnostic Output + ipoint = Pointer into qdiag array - from idiag array in common + mate = Diagnostic mate pointer number + bi = X-direction process(or) number + bj = Y-direction process(or) number + myThid = Current Thread number +\end{verbatim} + +\noindent +{\bf diagnostics\_add2list}: 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 routine +for defining a new permanent diagnostic in the main model or in a +package. The calling sequence is: + +\begin{verbatim} + call diagnostics_add2list( diagNum,diagName, diagCode, + diagUnits, diagTitle, myThid ) + + where: + diagNum = Diagnostic number - Output from routine + diagName = character*8 diagnostic name + diagCode = character*16 parsing code (see description of gdiag below) + diagUnits = Diagnostic units (character*16) + diagTitle = Diagnostic title or long name (up to character*80) + myThid = Current Thread number +\end{verbatim} + +\noindent +{\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{verbatim} + call diagnostics_clrdiag (jpoint, ipoint, myThid) + + where: + jpoint = Diagnostic number from menu - from jdiag array + ipoint = Pointer number into qdiag array - from idiag array + myThid = Current Thread number +\end{verbatim} + +\noindent +The diagnostics are computed at various times and places within the +GCM. Because MITgcm may employ a staggered grid, diagnostics may be +computed at grid box centers, corners, or edges, and at the middle or +edge in the vertical. Some diagnostics are scalars, while others are +components of vectors. An internal array is defined which contains +information concerning various grid attributes of each diagnostic. The +GDIAG array (in common block {\tt diagnostics} in file {\tt + DIAGNOSTICS.h}) 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}. \begin{table} \caption{Diagnostic Parsing Array} @@ -235,7 +247,7 @@ In this way the User has flexibility in determining the type of gridded data which is output. -\subsubsection{Usage Notes} +\subsection{Usage Notes} \label{sec:diagnostics:usersguide} \noindent @@ -252,131 +264,139 @@ to be computed, specify the frequency and type of output, the number of levels, and the name of all the separate output files. A sample data.diagnostics namelist file: -\noindent -$\#$ Diagnostic Package Choices \\ - $\&$diagnostics\_list \\ - frequency(1) = 86400., \ \\ - levels(1,1) = 1., \ \\ - fields(1,1) = 'RSURF ', \ \\ - filename(1) = 'surface', \ \\ - frequency(2) = 86400., \ \\ - levels(1,2) = 1.,2.,3.,4.,5., \ \\ - fields(1,2) = 'UVEL ','VVEL ', \ \\ - filename(2) = 'diagout1', \ \\ - frequency(3) = 3600., \ \\ - fields(1,3) = 'UVEL ','VVEL ','PRESSURE', \ \\ - filename(3) = 'diagout2', \ \\ - fileflags(3) = ' P1 ', \ \\ - $\&$end \ \\ - -\noindent -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 86400. seconds, -(frequency is 86400.), and will write fields which are multiple-level -fields at output levels 1-5. The names of diagnostics quantities are -UVEL and VVEL. The second set of output files -has the prefix diagout2, does time averaging every 3600. seconds, -includes fields which are multiple-level fields, levels output are 1-5, -and the names of diagnostics quantities are THETA and SALT. - -\noindent -The user must assure that enough computer memory is allocated for the diagnostics -and the output streams selected for a particular experiment. This is acomplished by -modifying the file DIAGNOSTICS\_SIZE.h and including it in the experiment code directory. -The parameters that should be checked are called numdiags, numlists, numperlist, and -diagSt\_size. +\begin{verbatim} +# Diagnostic Package Choices + &diagnostics\_list + frequency(1) = 86400., + levels(1,1) = 1., + fields(1,1) = 'RSURF ', + filename(1) = 'surface', + frequency(2) = 86400., + levels(1,2) = 1.,2.,3.,4.,5., + fields(1,2) = 'UVEL ','VVEL ', + filename(2) = 'diagout1', + frequency(3) = 3600., + fields(1,3) = 'UVEL ','VVEL ','PRESSURE', + filename(3) = 'diagout2', + fileflags(3) = ' P1 ', + &end +\end{verbatim} + +\noindent +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 86400. seconds, +(frequency is 86400.), and will write fields which are multiple-level +fields at output levels 1-5. The names of diagnostics quantities are +UVEL and VVEL. The second set of output files has the prefix +diagout2, does time averaging every 3600. seconds, includes fields +which are multiple-level fields, levels output are 1-5, and the names +of diagnostics quantities are THETA and SALT. + +\noindent +The user must assure that enough computer memory is allocated for the +diagnostics and the output streams selected for a particular +experiment. This is acomplished by modifying the file +DIAGNOSTICS\_SIZE.h and including it in the experiment code directory. +The parameters that should be checked are called numdiags, numlists, +numperlist, and diagSt\_size. \noindent numdiags (and diagSt\_size): \\ \noindent All GCM diagnostic quantities are stored in the single diagnostic array QDIAG which is located in the file \\ \filelink{pkg/diagnostics/DIAGNOSTICS.h}{pkg-diagnostics-DIAGNOSTICS.h}.\\ and has the form:\\ -common /diagnostics/ qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) \\ -\noindent -The first two-dimensions of qdiag correspond to the horizontal dimension of a given diagnostic, -and the third dimension of qdiag is used to identify diagnostic fields and levels combined. 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, or with -numdiags set to Nr. In order for the User to enable more than 1 three-dimensional diagnostic, -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{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}. -numdiags should be set greater than or equal to the sum of all the diagnostics activated -for output each multiplied by the number of levels defined for that diagnostic quantity. -For the above example, there are 4 multiple level fields, which the diagnostics menu -(see below) indicates are defined at the GCM vertical resolution, Nr. The value of -numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to 4*Nr, or, say 40 if $Nr=10$. +\begin{verbatim} + common /diagnostics/ + & qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy) +\end{verbatim} +\noindent +The first two-dimensions of qdiag correspond to the horizontal +dimension of a given diagnostic, and the third dimension of qdiag is +used to identify diagnostic fields and levels combined. 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, or with numdiags set to Nr. In order for the User to +enable more than 1 three-dimensional diagnostic, 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{pkg/diagnostics/DIAGNOSTICS\_SIZE.h}{pkg-diagnostics-DIAGNOSTICS\_SIZE.h}. +numdiags should be set greater than or equal to the sum of all the +diagnostics activated for output each multiplied by the number of +levels defined for that diagnostic quantity. For the above example, +there are 4 multiple level fields, which the diagnostics menu (see +below) indicates are defined at the GCM vertical resolution, Nr. The +value of numdiag in DIAGNOSTICS\_SIZE.h would therefore be equal to +4*Nr, or, say 40 if $Nr=10$. \noindent numlists and numperlist: \\ -\noindent The parameter numlists must be set greater than or equal to the number of -separate output streams that the user specifies in the namelist file data.diagnostics. -The parameter numperlist corresponds to the number of diagnostics requested in each -output stream. - -\noindent -In order to define and include as part of the diagnostic output any field -that is desired for a particular experiment, two steps must be taken. The -first is to enable the ``User Diagnostic'' in data.diagnostics. This is -accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through -UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level -fields) to the data.diagnostics namelist in one of the output streams. These -fields are listed in the diagnostics menu. The second step is to -add a call to diagnostics\_fill from the subroutine in which the quantity -desired for diagnostic output is computed. - -\noindent -In order to add a new diagnostic to the permanent set of diagnostics that the -main model or any package contains as part of its diagnostics menu, the subroutine -diagnostics\_add2list should be called during the initialization phase of the -main model or package. For the main model, the call should be made from -subroutine diagnostics\_main\_init, and for a package, the call should probably -be made from somewhere in the packages\_init\_fixed sequence (probaby from inside -the particular package's init\_fixed routine). A typical code sequence to set the +\noindent The parameter numlists must be set greater than or equal to +the number of separate output streams that the user specifies in the +namelist file data.diagnostics. The parameter numperlist corresponds +to the number of diagnostics requested in each output stream. + +\noindent +In order to define and include as part of the diagnostic output any +field that is desired for a particular experiment, two steps must be +taken. The first is to enable the ``User Diagnostic'' in +data.diagnostics. This is accomplished by adding one of the ``User +Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level +fields, or SDIAG1 through SDIAG10 for single level fields) to the +data.diagnostics namelist in one of the output streams. These fields +are listed in the diagnostics menu. The second step is to add a call +to diagnostics\_fill from the subroutine in which the quantity desired +for diagnostic output is computed. + +\noindent +In order to add a new diagnostic to the permanent set of diagnostics +that the main model or any package contains as part of its diagnostics +menu, the subroutine diagnostics\_add2list should be called during the +initialization phase of the main model or package. For the main model, +the call should be made from subroutine diagnostics\_main\_init, and +for a package, the call should probably be made from somewhere in the +packages\_init\_fixed sequence (probaby from inside the particular +package's init\_fixed routine). A typical code sequence to set the input arguments to diagnostics\_add2list would look like: -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> diagName = 'THETA ' \\ -\> diagTitle = 'Potential Temperature (degC,K)' \\ -\> diagUnits = 'Degrees K ' \\ -\> diagCode = 'SM MR ' \\ -\> CALL DIAGNOSTICS\_ADD2LIST( diagNum, \\ -\> I diagName, diagCode, diagUnits, diagTitle, myThid ) \\ -\\ -\end{tabbing} - -\noindent If the new diagnostic quantity is associated with either a vector -pair or a diagnostic counter, the diagCode argument must be filled with the -proper index for the ``mate''. The output argument from diagnostics\_add2list -that is called diagNum here contains a running total of the number of diagnostics -defined in the code up to any point during the run. The sequence number for the -next two diagnostics defined (the two components of the vector pair, for instance) -will be diagNum+1 and diagNum+2. The definition of the first component of the vector -pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2. -Since the subroutine increments diagNum, the definition of the second component of -the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for -this case would look like: - -\noindent -\begin{tabbing} -XXXXXXXXX\=XXXXXX\= \kill -\> diagName = 'UVEL ' \\ -\> diagTitle = 'Zonal Velocity ' \\ -\> diagUnits = 'm / sec ' \\ -\> diagCode = 'SM MR ' \\ -\> write(diagCode,'(A,I3.3,A)') 'VV ', diagNum+2 ,'MR ' \\ -\> call diagnostics\_add2list( diagNum, \\ -\> I diagName, diagCode, diagUnits, diagTitle, myThid ) \\ -\> diagName = 'VVEL ' \\ -\> diagTitle = 'Meridional Velocity ' \\ -\> diagUnits = 'm / sec ' \\ -\> diagCode = 'SM MR ' \\ -\> write(diagCode,'(A,I3.3,A)') 'VV ', diagNum ,'MR ' \\ -\> call diagnostics\_add2list( diagNum, \\ -\> I diagName, diagCode, diagUnits, diagTitle, myThid ) \\ -\\ -\end{tabbing} +\begin{verbatim} + diagName = 'THETA ' + diagTitle = 'Potential Temperature (degC,K)' + diagUnits = 'Degrees K ' + diagCode = 'SM MR ' + CALL DIAGNOSTICS\_ADD2LIST( diagNum, + I diagName, diagCode, diagUnits, diagTitle, myThid ) +\end{verbatim} + +\noindent If the new diagnostic quantity is associated with either a +vector pair or a diagnostic counter, the diagCode argument must be +filled with the proper index for the ``mate''. The output argument +from diagnostics\_add2list that is called diagNum here contains a +running total of the number of diagnostics defined in the code up to +any point during the run. The sequence number for the next two +diagnostics defined (the two components of the vector pair, for +instance) will be diagNum+1 and diagNum+2. The definition of the first +component of the vector pair must fill the ``mate'' segment of the +diagCode as diagnostic number diagNum+2. Since the subroutine +increments diagNum, the definition of the second component of the +vector fills the ``mate'' part of diagCode with diagNum. A code +sequence for this case would look like: + +\begin{verbatim} + diagName = 'UVEL ' + diagTitle = 'Zonal Velocity ' + diagUnits = 'm / sec ' + diagCode = 'SM MR ' + write(diagCode,'(A,I3.3,A)') 'VV ', diagNum+2 ,'MR ' + call diagnostics\_add2list( diagNum, + I diagName, diagCode, diagUnits, diagTitle, myThid ) + diagName = 'VVEL ' + diagTitle = 'Meridional Velocity ' + diagUnits = 'm / sec ' + diagCode = 'SM MR ' + write(diagCode,'(A,I3.3,A)') 'VV ', diagNum ,'MR ' + call diagnostics\_add2list( diagNum, + I diagName, diagCode, diagUnits, diagTitle, myThid ) +\end{verbatim} \input{part7/diagnostics-menu.tex} @@ -385,9 +405,21 @@ different MITgcm packages, follow the link to the diagnostics menu in the manual section describing the package: -\filelink{part6/fizhi-diagnostics-menu.tex}{pkg-fizhi-fizhi-diagnostics-menu.tex} +aim: \ref{sec:pkg:aim:diagnostics} +exf: \ref{sec:pkg:exf:diagnostics} +gchem: \ref{sec:pkg:gchem:diagnostics} +generic_advdiff: \ref{sec:pkg:generic_advdiff:diagnostics} +gridalt: \ref{sec:pkg:gridalt:diagnostics} +gmredi: \ref{sec:pkg:gmredi:diagnostics} +fizhi: \ref{sec:pkg:fizhi:diagnostics} +kpp: \ref{sec:pkg:kpp:diagnostics} +land: \ref{sec:pkg:land:diagnostics} +mom_common: \ref{sec:pkg:mom_common:diagnostics} +obcs: \ref{sec:pkg:obcs:diagnostics} +thsice: \ref{sec:pkg:thsice:diagnostics} +shap_filt: \ref{sec:pkg:shap_filt:diagnostics} -\subsubsection{Dos and Donts} +\subsection{Dos and Donts} -\subsubsection{Diagnostics Reference} +\subsection{Diagnostics Reference}