Home Contact Us Site Map  
 
       
    next up previous contents
Next: 7.1.4 Usage Notes Up: 7.1 Diagnostics-A Flexible Infrastructure Previous: 7.1.2 Equations   Contents


7.1.3 Key Subroutines and Parameters

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.

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. 

        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

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. 

        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

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: 

        flag = diagnostics_is_on( diagName, myThid )

     where:
        diagName = Character *8 expression for diagnostic
        myThid   = Current Thread number

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. 

        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

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: 

        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

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: 

       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

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: 

        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

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 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 7.1.


Table 7.1: Diagnostic Parsing Array
Diagnostic Parsing Array
Array Value Description
parse(1) $ \rightarrow $ S Scalar Diagnostic
  $ \rightarrow $ U U-vector component Diagnostic
  $ \rightarrow $ V V-vector component Diagnostic
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 (Corner) Point
parse(3) $ \rightarrow $ R Not Currently in Use
parse(4) $ \rightarrow $ P Positive Definite Diagnostic
parse(5) $ \rightarrow $ C Counter Diagnostic
  $ \rightarrow $ D Disabled Diagnostic for output
parse(6-8) $ \rightarrow $ C 3-digit integer corresponding to
    vector or counter component mate

As an example, consider a diagnostic whose associated GDIAG parameter is equal 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, C-grid location, etc.) defined internally. The Output routines use this information in order to determine what type of transformations need to be performed. Any interpolations are done at the time of output rather than during each model step. In this way the User has flexibility in determining the type of gridded data which is output.

next up previous contents
Next: 7.1.4 Usage Notes Up: 7.1 Diagnostics-A Flexible Infrastructure Previous: 7.1.2 Equations   Contents
mitgcm-support@mitgcm.org
Copyright © 2006 Massachusetts Institute of Technology Last update 2011-01-09