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_ADDTOLIST (pkg/diagnostics/diagnostics_addtolist.F): 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_ADDTOLIST (
     O     diagNum,
     I     diagName, diagCode, diagUnits, diagTitle, diagMate,
     I     myThid )

     where:
       diagNum   = diagnostic Id number - Output from routine
       diagName  = name of diagnostic to declare
       diagCode  = parser code for this diagnostic
       diagUnits = field units for this diagnostic
       diagTitle = field description for this diagnostic
       diagMate  = diagnostic mate number
       myThid    = my Thread Id number

DIAGNOSTICS_FILL (pkg/diagnostics/diagnostics_fill.F): 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(
       I             inpFld, diagName,
       I             kLev, nLevs, bibjFlg, bi, bj, myThid )

     where:
        inpFld   = Field to increment diagnostics array
        diagName = diagnostic identificator name (8 characters long)
        kLev     = Integer flag for vertical levels:
                   > 0 (any integer): WHICH single level to increment in qdiag.
                   0,-1 to increment "nLevs" levels in qdiag,
                   0 : fill-in in the same order as the input array
                   -1: fill-in in reverse order.
        nLevs    = indicates Number of levels of the input field array
                   (whether to fill-in all the levels (kLev<1) or just one (kLev>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 (with overlap regions)
                      (local array here means that it has no bi-bj dimensions)
                 = 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 overlap region (interior only)
                   NOTE - bibjFlg can be NEGATIVE to indicate not to increment counter
        bi       = X-direction tile number - used for bibjFlg=1-3
        bj       = Y-direction tile number - used for bibjFlg=1-3
        myThid   =  my thread Id number

DIAGNOSTICS_SCALE_FILL (pkg/diagnostics/diagnostics_scale_fill.F): 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(
       I             inpFld, scaleFact, power, diagName,
       I             kLev, nLevs, bibjFlg, bi, bj, myThid )


     where all the arguments are the same as for DIAGNOSTICS_FILL with
     the addition of:
        scaleFact   = Scaling factor to apply to the input field product
        power       = Integer power to which to raise the input field (after scaling)

DIAGNOSTICS_FRACT_FILL (pkg/diagnostics/diagnostics_fract_fill.F): This is a specific alternative routine to DIAGNOSTICS_[SCALE]_FILL for the case of a diagnostics which is associated to a fraction-weight factor (referred to as the diagnostics "counter mate"). This fraction-weight field is expected to vary during the simulation and is provided as argument to DIAGNOSTICS_FRACT_FILL in order to perform fraction-weighted time-average diagnostics. Note that the fraction-weight field has to correspond to the diagnostics counter-mate which has to be filled independently with a call to DIAGNOSTICS_FILL. 

        CALL DIAGNOSTICS_FRACT_FILL(
       I             inpFld, fractFld, scaleFact, power, diagName,
       I             kLev, nLevs, bibjFlg, bi, bj, myThid )


     where all the arguments are the same as for DIAGNOSTICS_SCALE_FILL with
     the addition of:
        fractFld    = fraction used for weighted average diagnostics

DIAGNOSTICS_IS_ON: Function call to inquire whether a diagnostic is active and should 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 = diagnostic identificator name (8 characters long)
        myThid   = my thread Id number

DIAGNOSTICS_COUNT (pkg/diagnostics/diagnostics_utils.F): This subroutine increments the diagnostics counter only. In general, the diagnostics counter is incremented at the same time as the diagnostics is filled, by calling DIAGNOSTICS_FILL. However, there are few cases where the counter is not incremented during the filling (e.g., when the filling is done level per level but level 1 is skipped) and needs to be done explicitly with a call to subroutine DIAGNOSTICS_COUNT. The call sequence is: 

        CALL DIAGNOSTICS_COUNT(
       I                        diagName, bi, bj, myThid )

     where:
        diagName  = name of diagnostic to increment the counter
        bi        = X-direction tile number, or 0 if called outside bi,bj loops
        bj        = Y-direction tile number, or 0 if called outside bi,bj loops
        myThid    = my thread Id number


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 $ Used for Level Integrated output: cumulate levels
  $ \rightarrow $ r same but cumulate product by model level thickness
  $ \rightarrow $ R same but cumulate product by hFac & level thickness
parse(4) $ \rightarrow $ P Positive Definite Diagnostic
parse(5) $ \rightarrow $ C with Counter array
  $ \rightarrow $ P post-processed (not filled up) from other diags
  $ \rightarrow $ D Disabled Diagnostic for output
parse(6-8)   retired, formerly: 3-digit mate number
parse(9) $ \rightarrow $ U model-level plus 1/2
  $ \rightarrow $ M model-level middle
  $ \rightarrow $ L model-level minus 1/2
parse(10) $ \rightarrow $ 0 levels = 0
  $ \rightarrow $ 1 levels = 1
  $ \rightarrow $ R levels = Nr
  $ \rightarrow $ L levels = MAX(Nr,NrPhys)
  $ \rightarrow $ M levels = MAX(Nr,NrPhys) - 1
  $ \rightarrow $ G levels = Ground_level Number
  $ \rightarrow $ I levels = sea-Ice_level Number
  $ \rightarrow $ X free levels option (need to be set explicitly)

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*16 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.

As an example, consider a diagnostic whose associated GDIAG parameter is equal to ``UUR MR''. From GDIAG we can determine that this diagnostic is a U-vector component located at the C-grid U-point, model mid-level (M) with Nr levels (last R).

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 2018-01-23