Vgrid/highlevel

The high-level interface of the Vertical Grid Descriptors module is intended to provide most of the flexibility required by users. For example, a user wishes to calculate pressures on a set of levels produced by the GEM model (version 4.0.6 onwards, other versions may require the use of the upgrade applicaton) would use the high-interface call to the levels procedure to calculate pressures in one simple step.

1 Vertical Levels

The vertical levels at each point on the grid can be computed with a single procedure call. The FST key of a prototype field is required in order to specify which set of vertical grid descriptors should be accessed, and what staggered levels (if any) should be used. This key should be obtained using the standard FST utilities. The function return a status that can be either VGD_OK (successful completion) or VGD_ERROR (error completion). These variables are defined in the Vertical Grid Descriptor module and should be used to verify that the return code does not indicate an error.

1.1 Usage Example

Canonical usage of the vertical level function vgd_levels is shown here.

 program calculate_levels
   use vGrid_Descriptors, only: vgd_levels,VGD_OK
   implicit none
   !
   ! Variable declarations
   integer :: status,count,ni,nj,nk,iun=0
   integer, dimension(1000) :: keys
   real, dimension(:,:,:), pointer :: lev=>null()
   !
   ! External functions
   integer, external :: fstinf,fnom,fstouv,fstfrm,fclos
   !
   ! Open file and get FST key for field of interest (in this case TT)
   status = fnom(iun,'test_file.fst','STD',0)
   status = fstouv(iun,'RND')
   status = fstinl(iun,ni,nj,nk,-1,' ',-1,-1,-1,' ','TT',keys,count,size(keys))
   !
   ! Calculate level information for this field
   status = vgd_levels(unit=iun,fstkeys=key(1:count),levels=lev)
   if (status /= VGD_OK) write(0,*) 'WARNING - error during level calculation'
   !
   ! Close the input file and stop
   status = fstfrm(iun)
   status = fclos(iun)
 end program calculate_levels

2 Interface Details

The interface to the vgd_levels procedure is defined here for reference; however, most usage will probably follow the example shown above.

status = vgd_levels(unit,fstkeys,levels,in_log) result(status)
    integer, intent(in) :: unit                         !File unit associated with the key
    integer, dimension(:), intent(in) :: fstkeys        !Key of prototype field
    real, dimension(:,:,:), pointer :: levels           !Physical level values
    logical, optional, intent(in) :: in_log             !Compute levels in ln() [.false.]

Note that the call returns a value of VGD_OK on success and VGD_ERROR on failure. Specifying these variables when use-associating the module will allow for error checking and handling in the calling program (see example above). The results of the calculation - in this physical position (i.e. pressure) of the coordinate surface - will be returned in levels, which should be declared as real, dimension(:,:,:), pointer. All allocations will be performed within the module, and the size of the returned field can be checked with the intrinsic size() function following the call to vgd_levels. The final in_log argument is optional (default .false.) and specifies whether or not the results should be given in full value (default) or natural log (if in_log=.true. is specified).

It is also possible to get the partial derivative of the pressure with respect to the surface pressure with the following interfaces (doc to be completed)