PUBLIC INTERFACE / DATA / ROUTINES / NAMELIST / CHANGES / ERRORS / REFERENCES / NOTES

## module my25_turb_mod

         Contact:   Joe Sirutis, Bruce Wyman
         Reviewers:

         Tags/Status

#### OVERVIEW

         Mellor/Yamada level 2.5 turbulent closure parameterization.

         This module provides mixing coefficients for wind, temperature
         and moisture that are used in the vertical diffusion code.

         Given potential temperature and wind profiles at the model's
         pressure levels, this module returns mixing coefficients for
         wind, temperature and moisture based on the Mellor/Yamada
         level 2.5 turbulent closure parameterization. These coefficients
         are then used in the vertical diffusion code.

         The level 2.5 scheme has a prognostic equation for turbulent
         kinetic energy, and a diagnostic relationship for temperature
         variance. The prognostication of the turbulent kinetic energy,
         with the exception of the advection and horizontal diffusion
         terms, is also done in this module.

         This module also handles the initialization of the turbulent
         kinetic energy, along with the input/output of a restart file
         for the turbulent kinetic energy.

#### OTHER MODULES USED

              constants_mod
            tridiagonal_mod
              utilities_mod
          monin_obukhov_mod

#### PUBLIC INTERFACE

    use my25_turb_mod [,only: my25_turb_init, my25_turb, tke_surf, my25_turb_end]

    my25_turb_init  - Called once to initialize my25_turb. Also reads namelist,
                      and restart data for turbulent kinetic energy.
                      Must be called before my25_turb.

    my25_turb       - Called every time step. Computes mixing coefficients
                      for momentum, heat, and moisture. Also updates turbulent
                      kinetic energy.

    tke_surf        - Prescribes lower boundary condition for
                      turbulent kinetic energy

    my25_turb_end  - Called at the end of the model run to write restart
                     data for turbulent kinetic energy.

    Notes:
     1) A namelist interface controls runtime options.
     2) A restart file for TKE is generated by this module.

#### PUBLIC DATA

      real, public, allocatable, dimension(:,:,:) :: TKE

      TKE - global turbulent kinetic energy at model half levels in m^2/sec^2
            If there are "kx" model levels then TKE will have
            "kx+1" half levels.

#### PUBLIC ROUTINES

    call my25_turb_init (ix, jx, kx)

    input

        ix, jx    number of horizontal grid points in the global
                  fields along the x and y axis, respectively.
                  [integer]

        kx        number of vertical points in a column of the atmosphere
                  [integer]

    ---------------------------------------------------------------------

    call my25_turb( delt, fracland, phalf, pfull, theta, &
                    um,   vm,       zhalf, zfull, z0,    &
                    TKE,  el0,      el,    akm,   akh,   &
                    mask, kbot)

    input

        delt       Model time step in seconds
                   [real]

        fracland   Fractional amount of land beneath a grid box
                   [real, dimension(:,:)]

        phalf      Pressure at half levels in pascals
                   [real, dimension(:,:,nlev+1)]

        pfull      Pressure at full levels in pascals
                   [real, dimension(:,:,nlev)]

        theta      Potential temperature [deg K] at full model levels
                   [real, dimension(:,:,nlev)]

        um         Zonal wind component [m/s] at full model levels,
                   [real, dimension(:,:,nlev)]

        vm         Meridional wind component [m/s] at full model levels,
                   [real, dimension(:,:,nlev)]

        zhalf      Height at half levels in meters
                   [real, dimension(:,:,nlev+1)]

        zfull      Height at full levels in meters
                   [real, dimension(:,:,nlev)]

        z0         Surface roughness length in meters
                   [real, dimension(:,:)]

    input/output

        TKE        Turbulent kinetic energy in m^2/sec^2.
                   [real, dimension(:,:,nlev+1)]

    output

        el0        Characteristic length scale in meters.
                   [real, dimension(:,:)]

        el         Master length scale in meters.
                   [real, dimension(:,:,nlev+1)]

        akm        Mixing coefficient for momentum in m^2/sec.
                   [real, dimension(:,:,nlev)]

        akh        Mixing coefficient for heat and moisture in m^2/sec.
                   [real, dimension(:,:,nlev)]

    input (optional)

        - for use with the step-mountain (eta) vertical coordinate

        mask      Mask (1. or 0.) for grid boxes above or below the ground.
                  [real, dimension(:,:,nlev)]

        kbot      Index of the lowest model level
                  [integer, dimension(:,:)]

        - for use in diagnosing PBL depth

        ustar     Friction velocity at the surface (meters/sec)
                  [real, dimension(:,:)]

        bstar     Buoyancy scale at the surface (meters/sec**2.)
                  [real, dimension(:,:)]

    output (optional)

        h         pbl depth (meters)
                  [real, dimension(:,:)]

    ---------------------------------------------------------------------

     call tke_surf ( u_star, TKE, kbot )

    input

        u_star    Surface friction velocity (m/s)
                  [real, dimension(:,:)]

    input/output

        TKE        Turbulent kinetic energy, in m^2/sec^2.
                   [real, dimension(:,:,nlev+1)]

    input (optional) - for use with the step-mountain (eta) vertical coordinate

        kbot      Index of the lowest model level
                  [integer, dimension(:,:)]

    ---------------------------------------------------------------------

      call my25_turb_end()

        There are no arguments to this routine.

#### NAMELIST

    &my25_turb_nml

       TKEmax        Max value for TKE
                     [real, default: TKEmax = 5.0 m^2/sec^2]

       TKEmin        Min value for TKE
                     [real, default: TKEmin = 0.0 m^2/sec^2]

       akmax         Max value for akm & akh
                     [real, default: akmax = 1.0e4 m^2/sec]

       akmin_land    Min value for akm & akh over land points
                     (Applied to the lowest nk_lim levels)
                     [real, default: akmin_land = 5.0 m^2/sec]

       akmin_sea     Min value for akm & akh over all ocean points
                     (Applied to the lowest nk_lim levels)
                     [real, default: akmin_sea = 0.0 m^2/sec]

       nk_lim        Lower bound on akm & akh applied at lowest nk_lim levels
                     [integer, default: nk_lim = 2 ]

       init_iters    Number of iterations to be used in initializing TKE.
                     Only used if the input restart data does not exist.
                     [integer, default: init_iters = 20 ]

       el0max        Max value for el0
                     [real, default: el0max = 1.0e6 meters]

       el0min        Min value for el0
                     [real, default: el0min = 0.0 meters]

       alpha_land    Constant used in computing el0 ( land value )
                     [real, default: alpha_land = 0.10 ]

       alpha_sea     Constant used in computing el0 ( sea value )
                     [real, default: alpha_land = 0.10 ]

       do_thv_stab   If false, buoyancy computed using constant
                     reference potential temperature.
                     [logical, default: do_thv_stab = .true.]

       use_old_cons  If true,  use original MY constants
                     If false, use revised values
                     [logical, default: use_old_cons = .false.]

       kcrit         Mixing coefficient threshold used to diagnose PBL top.
                     PBL top is set the interpolated height where the mean
                     of the momentum and tracer diffusion coefficient first
                     falls beneath kcrit.
                     [real, default: kcrit = 0.01 m2/sec]

    Notes:

      * Diagnostic output from Mellor Yamada 2.5 is controlled by the
        namelist to vert_turb_driver module.

#### DATA SETS

         This module automatically writes restart data to file
         "RESTART/my25_turb.res". This file has one record which
         contains the global turbulent kinetic energy field (see the
         section for PUBLIC DATA).

         The input restart data is read from file "INPUT/my25_turb.res".
         If this restart file does not exist, the module will initialize
         TKE by setting TKE = TKEmin and iterating with the same input
         data "init_iters" times.  init_iters is a namelist variable.

#### CHANGE HISTORY

    Revision history

    changes (8/31/99)

        A diagnostic subroutine was added which diagnoses the pbl depth
        as the height to which the interpolated mean diffusivity coefficients
        (mean of akm and akh) falls beneath a specified value, kcrit (a
        new namelist variable which is defaulted to 0.01 m^2/sec).

#### ERROR MESSAGES

    Fatal Errors in MY25_TURB

        MY25_TURB_INIT has not been called
            The initialization routine for this module must be called
            before calling routine MY25_TURB.

        divid by zero, x1 <= 0.0
            This error should never occur.
            If it occurs, contact the developer.

        cannot request pbl depth if ustar and bstar are not also supplied
            If you request (as an optional argument to my25_turb)
            the pbl depth, h, the calculation also needs the optional
            arguments ustar, and bstar.

#### REFERENCES

         Mellor, G.L. and T. Yamada, 1974: A hierarchy of turbulent
              closure models for planetary boundary layers. J. Atmos.
              Sci., 31, 1791-1806.

         Mellor, G.L. and T. Yamada, 1982: Development of a turbulent
              closure model for geophysical fluid problems. Rev. Geophys.
              Space Phys. 20, 851-875.

#### KNOWN BUGS

         There are no known bugs.

#### NOTES

        None.

#### FUTURE PLANS

        None.