MODULE DIAGNOSTICS_MODULE

This module provides a diagnostic object for Poseidon.

Diagnostics are used for two main purposes:

Within the model, quantities derived from the state but which do not need to be saved to the restart can be "diagnosed" when needed, and passed among routines. The ocean object contains a T_Diagnostics item, and this item is created when the ocean object is created. Other diagnostics may be created separately, as is done in poseidon_history_module

Diagnostics may be kept to enhance budgets, debug, or pass information between routines.

A diagnostic object is a collection of items that are optional arrays (see Optional_Array_Module ). The intent is to provide a rich (almost limitless) set of possible diagnostics, but without allocating lots of space that is not needed. For each diagnostic that one can imagine, some code is placed in the model to evaluate it, and an item is put in the T_Diagnostics object to hold its value. But the items are optional arrays, which mean that they have a "wanted" property, and are allocatable so that they will not be allocated unless wanted.

For each diagnostic item, there should be some code in the model which sets the value. Each routine is called with the diagnostic object.

The typical sequence in a supervisor is:

       Type (T_Ocean) :: ocean
       call INIT_OCEAN( ..., ocean, ...)
       call CREATE_FORCING(oforce,...)
       call MarkDiagForHistory( ocean%diag, "Nu_v", .false.)
       call CREATE_OHIST(ocean, oforce, ohist, ocean%diag)

  
        if ( diag%item%wanted ) then ...

       if ( diag%item%wanted .and. diag%item%allocated ) then ...

To set the wanted property, the MarkDiagWanted routine is provided. It may be used before or after creating the diagnostic.

Use of the key codes may set more than one diagnostic to wanted status. They are defined as public integer parameters. The current ones are:

       dgWENT        sets W_ent, Vert_Heat_Flux, Vert_Salt_Flux, Vert_U_Flux, 
                          Vert_V_Flux
       dgVORTICITY   sets Ave_Press_x, Ave_Press_y, Ave_Force_x, Ave_Force_y,
                          Ave_Advct_x, Ave_Advct_y, Ave_Frict_x, Ave_Frict_y, 
                          Ext_Mass_eq
       dgMASS_FLUX   sets Uhtotal , Vhtotal ,BUtotal, BVtotal ,
                          UHctotal, VHctotal, Ext_Mass_Change, Int_Mass_Change 
       dgDIFFUSIVITY sets Ri, Kappa, Nu_u, Nu_v
       dgKFLUX       sets KFluxT, KFluxS, KFluxU, KFluxv
       dgWEZ         sets W_z
       dgSST         sets SST
       dgSSS         sets SSS

        call CREATE_DIAGNOSTICS( ocean%g, ocean%diag, dgWENT+dgVORTICITY ) 
        ocean%diag%Ave_Advct_x%wanted = .false.
        call DESTROY_OPTIONAL_ARRAY( ocean%diag%Ave_Advct_x )
        call CREATE_OHIST...

TO ADD A DIAGNOSTIC ITEM:

1. Add the appropriate optional array to T_Diagnostics .

          type T_Diagnostics
           ...
           type (T_Optional_Array2) :: NewItem
          end type T_Diagnostics

2. Increment the NItems2 or NItems3 value to reflect the fact that an item will be added to one of the databases

3. Add lines to INITIALIZE_DIAGNOSTICS_DB like

           d%items2(n)%Array        => d%NewItem
           d%items2(n)%Name         = "Newitem" 
           d%items2(n)%LongName     = "A long name for GrADS" 
           d%items2(n)%GRIB         = 99
           d%items2(n)%Units        = "m^2/s"
           d%items2(n)%Description  = "Some even longer name, if wanted" 

4. Add code to the model that sets the diagnostic val property:

        if ( diag%item%wanted ) diag%item%val(:,:) = Mystuff(:,:)

TO ADD A DIAGNOSTIC GROUP

1. Add each of the items in the group as above.

2. Declare a public integer parameter (like dgNEW) and give it a value that is 2 times larger than the largest assigned so far.

3. Add a private integer array like igNEW, that contains the database indices of the items in the group. Use negative numbers for 3-D arrays, positive for 2-D

4. Add line to MarkDiagWanted3 and MarkDiagForHistory3 like

           if ( IS_IN(key,dgNEW) )   call SetW(Diag,igNEW,val )

It is intended that the diagnostic type will grow as more and more items get added. Since the space is only allocated when needed the addition of diagnostics should be done once, then kept around. Others will pay a very small penalty for having lots of un-used diagnostics.

Module Private: