PUBLIC INTERFACE / ROUTINES / NAMELIST / DIAGNOSTICS / ERRORS

## Module vert_turb_driver_mod

         Contact:   Bruce Wyman, Steve Klein
         Reviewers:

#### OVERVIEW

         Controls the selection of schemes to determine diffusion
         coefficents in the free atmosphere and outputs related
         diagnostic quantities.

         The follow processes are controlled by this module:

            1) Mellor-Yamada 2.5 turbulence closure scheme
            2) Generalized diffusivity scheme
            3) Shallow convection scheme
            4) Calculation of gustiness

#### OTHER MODULES USED

             my25_turb_mod
           diffusivity_mod
          shallow_conv_mod
          diag_manager_mod
          time_manager_mod
             constants_mod
             utilities_mod

#### PUBLIC INTERFACE

    use vert_turb_driver_mod [,only: vert_turb_driver_init,
                                     vert_turb_driver, vert_turb_driver_end]

    vert_turb_driver_init - Must be called once before vert_turb_driver to
                            initialize the module (reads namelist input)
                            and other modules used.

    vert_turb_driver      - Called every time step to compute diffusion
                            coefficients.

    vert_turb_driver_end  - Called at the end of the model run to terminate
                            the vert_turb_driver module and other modules used.

    Notes:
     1) A namelist interface controls runtime options and selects fields
        for diagnostics output.

#### PUBLIC ROUTINES

    call vert_turb_driver_init (id, jd, kd, axes, Time)

    input

        id, jd    number of horizontal grid points in the global
                  fields along the i and j axis, repectively.
                     [integer]

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

        axes      The axis indices that are returned by previous calls to
                  diag_axis_init. The values of this array correspond to the
                  x, y, full (p)level, and half (p)level axes. These are the
                  axes that diagnostic fields are output on.
                     [integer, dimension(4)]

        Time      The current time.  [time_type]

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

    call vert_turb_driver (is, js, Time, Time_next, dt, frac_land,
                           p_half, p_full, z_half, z_full,
                           u_star, b_star, rough, u, v, t, q,
                           um, vm, tm, qm, udt, vdt, tdt, qdt,
                           diff_t, diff_m, gust [, mask, kbot] )

    input

        is         starting i index for current window [integer]

        js         starting j index for current window [integer]

        Time       time at the current time level (tau) [time_type]

        Time_next  time at the next time level (tau+1) [time_type]

        dt         time step in seconds (from tau-1 to tau+1 if leapfrog)
                     [real]

        frac_land  fraction (0. to 1.) of surface which covered by land
                     [real, dimension(:,:)]

        p_half     pressure at half model levels [real, dimension(:,:,nlev+1)]

        p_full     pressure at full model levels [real, dimension(:,:,nlev)]

        z_half     height (in meters) at half model levels
                     [real, dimension(:,:,nlev+1)]

        z_full     height (in meters) at full model levels
                     [real, dimension(:,:,nlev)]

        u_star     friction velocity (m/s) for the surface layer
                     [real, dimension(:,:)]

        b_star     bouyancy scale (deg K/m ???) for the surface layer
                     [real, dimension(:,:)]

        rough      surface roughness length scale (m)   [real, dimension(:,:)]

        u          zonal wind component (m/s) at full model levels at the current time level
                     [real, dimension(:,:,nlev)]

        v          meridional wind component (m/s) at full model levels at the current time level
                     [real, dimension(:,:,nlev)]

        t          temperature (deg K) at full model levels at the current time level
                     [real, dimension(:,:,nlev)]

        q          specific humidity (kg/kg) at full model levels at the current time level
                     [real, dimension(:,:,nlev)]

        um         zonal wind component (m/s) at the previous time level
                     [real, dimension(:,:,nlev)]

        vm         meridional wind component (m/s) at the previous time level
                     [real, dimension(:,:,nlev)]

        tm         temperature (deg K) at the previous time level
                     [real, dimension(:,:,nlev)]

        qm         specific humidity (kg/kg) at the previous time level
                     [real, dimension(:,:,nlev)]

        udt        zonal wind tendency in m/s2
                     [real, dimension(:,:,nlev)]

        vdt        meridional wind tendency in m/s2
                     [real, dimension(:,:,nlev)]

        tdt        temperature tendency in deg k per sec
                     [real, dimension(:,:,nlev)]

        qdt        specific humidity tendency in kg vapor/kg air/sec
                     [real, dimension(:,:,nlev)]

    output

        diff_t     diffusion coefficients (m2/s) for heat/moisture/tracers at
                   half model levels, note that there is no surface value
                     [real, dimension(:,:,nlev)]

        diff_m     diffusion coefficients (m2/s) for momentum at
                   half model levels, note that there is no surface value
                     [real, dimension(:,:,nlev)]

        gust       surface layer gustiness (m/s), currently this returns a
                   constant value (1 m/s) everywhere
                     [real, dimension(:,:)]

    input (optional), for the step-mountain (eta) coordinate option

        mask       mask (1. or 0.) for grid boxes above or below
                   the ground, usually only necessary for the step-mountain
                   (eta) vertical coordinate  [real, dimension(:,:,nlev)]

        kbot       index of the lowest model level, usually only necessary
                   for the step-mountain (eta) vertical coordinate
                     [integer, dimension(:,:)]

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

    call vert_turb_driver_end

       There are no arguments to this routine.

#### NAMELIST

    &vert_turb_driver_nml

      do_mellor_yamada   Switch to to determine when Mellor-Yamada or
                         the generalized diffusivity scheme is used.
                           [logical, default: do_mellor_yamada=.true.]

      do_shallow_conv    Switch to turn on/off shallow convection scheme.
                           [logical, default: do_shallow_conv=.false.]

      gust_scheme        Sets the scheme used for the gustiness calculation.
                         Valid schemes (case sensitive) are:
                         = 'constant' --> use namelist value CONSTANT_GUST
                         = 'beljaars' --> use Beljaars(1994) scheme
                           [character, default: gust_scheme = 'constant']

      constant_gust      Value used for gustiness (in m/s) when
                         gust_scheme = 'constant'.
                           [real, default: constant_gust = 1.]

      use_tau        Switch to determine whether the input data (momentum, temp, sphum)
                     used to computed the diffusion coefficients and/or update TKE should
                     be for the current time level (tau) or next time level (tau+1)
                       if use_tau = true then data at tau is used (e.g., u,v,t,q)
                       if use_tau = false then data at tau+1 is used by explicitly
                                    adding the tendency to the data at tau-1
                                    (e.g., tt=t+dt*tdt)
                       [logical, default: use_tau=true ]

      do_molecular_diffusion ??????
                       [logical, default: do_molecular_diffusion = .false.]

#### DIAGNOSTIC FIELDS

    Diagnostic fields may be output to a netcdf file by specifying the
    module name vert_turb and the desired field names (given below)
    in file diag_table. See the documentation for diag_manager.

    Diagnostic fields for module name: vert_turb

       field name     field description
       ----------     -----------------

       tke            turbulent kinetic energy (m2/s2)
       lscale         turbulent length scale (m)
       lscale_0       master length scale (m)
       z_pbl          depth of planetary boundary layer (m)
       gust           gustiness (m/s)
       diff_t         vert diff coeff for temp (m2/s)
       diff_m         vert diff coeff for momentum (m2/s)
       diff_sc        vert diff coeff for shallow conv (m2/s)

    Notes:

     1) tke, lscale, and lscale_0 can only be output when the Mellor-Yamada
        scheme is used.

#### CHANGE HISTORY

    Changes prior to CVS version control

    changes (1/24/2000)

      * Minor change.

        When the Mellor-Yamada scheme is NOT selected the Mellor-Yamada
        initialization and end routines are no longer called.

    changes (10/4/1999)

      * Major changes.

      * MPP version created. Minor changes for open_file, error_mesg,
        and Fortran write statements. Answers should reproduce the
        previous version.

      * Implementation of the new MPP diagnostics package.
        This required major changes to the diagnostic interface and
        the manner in which diagnostics quantities are selected.
        There are additional arguments to several interfaces.

    changes (8/31/1999)

        Diagnostic field z_pbl, the depth of planetary boundary layer,
        may now be output for either the generalized diffusivity scheme
        or the Mellor-Yamada scheme. (In an earlier revision PBL depth
        could only be output for the diffusivity scheme.)

#### ERROR MESSAGES

    Fatal errors in vert_turb_driver_init:

        attempting to call initialization twice
           You can not call vert_turb_driver_init more than once.

        invalid value for namelist variable GUST_SCHEME
           The gustiness scheme you have selected is not valid.
           Check the namelist options for variable GUST_SCHEME.

    Fatal errors in vert_turb_driver:

        initialization has not been called
           You have not called vert_turb_driver_init before calling
           vert_turb_driver.

#### KNOWN BUGS

         There are no known bugs.

#### FUTURE PLANS

         None.