OVERVIEW

     Initializes a data structure containing constants
     for a hybrid sigma-pressure vertical coordinate.
     There are several public routines that operate with
     this data structure.

     This module uses the hybrid sigma-pressure vertical coordidate
     described in Simmons and Burridge (1981).  At the model's
     lower boundary the coordinate surfaces must be in the
     terrian-following, sigma coordinate. The model's upper levels
     may use constant pressure surfaces. In between there is a
     gradual transition from sigma to pressure. A transition that
     is too rapid can result in negative pressure depths for model
     layers with low surface pressure.

     Pressure p is determined by the following formula:

            p(k) = peta(k) + eta(k) * pssl

     where   (k) = the vertical index
             peta = reference pressure
             eta  = sigma/eta values (between 0. and 1.)
             pssl = ps * res
             ps   = surface pressure
             res  = 1./eta_surface (=1 for non-eta case)

             peta, eta      are dimensioned only in the vertical
             pssl, ps, res  are dimensioned only in the horizontal


     NOTE:  The B-grid dynamical core has an unsupported option that
            replaces the sigma coordinate with the eta/step-mountain
            vertical coordinate.  In the context of this module,
            references to "sigma" and "eta" are interchangeable.

OTHER MODULES USED

     constants_mod
     fms_mod

PUBLIC INTERFACE

PUBLIC DATA

 type (vert_grid_type)

   nlev  = number of vertical levels
             [integer]
   nplev = number of pure pressure levels at the top of the model
           will equal zero when not using hybrid coordinate
             [integer]
   eta   = sigma values at model layer interfaces (half levels)
           this value is sometimes refered to as "bk"
             [real, dimension(nlev+1)]
   peta  = reference pressure values at model layer interfaces (half levels)
           this value is sometimes refered to as "pk"
             [real, dimension(nlev+1)]
   deta  = sigma thickness of model layers 
             [real, dimension(nlev)]
   dpeta = reference pressure thickness of model layers
             [real, dimension(nlev)]

   pfull = pressure profile at model levels (full levels)
             [real, dimension(nlev)]
   phalf = pressure profile at model layer interfaces (half levels)
             [real, dimension(nlev)]
   fhalf = profile of geopotental height at half levels (m2/s2)
             [real, dimension(nlev+1)]
   wta,
     wtb = weights used to determine values at model levels
           (based on pressure profile, useful for hybrid coord)
             [real, dimension(nlev)]

   psmin = minimum allowable surface pressure to avoid negative mass
           in a model layer when using the hybrid coordinate 
             [real]
   hybrid = flag that indicates if the hybrid coordinate is being used
              [logical]
   pzero  = flag that indicates if the pressure at the top of the model 
            is zero (can only be non-zero if hybrid=true).
              [logical]

   pref   = reference pressure for the eta coordinate (101325. Pa)
              [real]
   tref   = reference temperature for the eta coordinate (288. degK)
              [real]
   gamma  = reference lapse rate for the eta coordinate (.0065 degK/m)
              [real]

PUBLIC ROUTINES

ERROR MESSAGES

Fatal errors in compute_pres_depth

     incorrect dimension 3 for pdepth
          The third dimension of output argument pdepth must equal
          the number of model levels.

     pressure depth <= 0.0
          The pressure depth of a model layer has a mass <= 0.
          This can only happen when running a hybrid vertical
          coordinate and the surface pressure becomes too small.
          This error may result as the model goes unstable.

Fatal errors in compute_pres_full or compute_pressures

     incorrect dimension 3 for pfull
          The third dimension of output argument pfull must equal
          the number of model levels.

Fatal errors in compute_pres_half

     incorrect dimension 3 for phalf
          The third dimension of output argument phalf must equal
          the number of model levels plus one.

Fatal errors in compute_geop_height

     incorrect dimension 3 for zfull
          The third dimension of output argument zfull must equal
          the number of model levels.

     incorrect dimension 3 for zhalf
          The third dimension of output argument zhalf must equal
          the number of model levels plus one.

REFERENCES

     Simmons, A. J. and D. M. Burridge, 1981: 
     An energy and angular-momentum conserving vertical
     finite-difference scheme and hybrid vertical coordinate.
     Mon. Wea. Rev., 109, pp.758-766.

KNOWN BUGS

    There are no known bugs.
   

NOTES

     None.

FUTURE PLANS

    1) Add public routines for generating profiles for
       sigma and hybrid levels.
    2) Compute virtual temperature in one central place.