module diffusivity

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

## Module diffusivity_mod

         Contact:   Steve Klein and Isaac Held
         Reviewers:

         Tags/Status

#### OVERVIEW

         This routine computes the atmospheric vertical diffusivity
         coefficients of momentum and temperature plus tracers at all
         half-levels interior to the atmosphere.

         The vertical diffusivity coefficients are calculated separately
         for the planetary boundary layer (PBL) and the free atmosphere.
         Note that the diffusivity coefficient for temperature is the same
         as that for all tracers.

         In the PBL, the default prescription of diffusivities is the
         K-profile boundary layer scheme. A second method is to do the
         Old Climate Model's version.  In the free atmosphere there
         there are two options, one of which duplicates that used in
         the old Skyhii model.

         A full description can be found here.

#### OTHER MODULES USED

    utilities_mod
    constants_mod
    monin_obukhov_mod

#### PUBLIC INTERFACE

    use diffusivity_mod [,only: diffusivity]

    diffusivity -         called every physics time step to compute diffusivity
                          coefficients.

    Notes:

     1) A namelist interface controls runtime options
     2) An initialization routine is called upon the first call to
        diffusivity.
     2) No restart file is generated by this module.
     3) No other data files are needed.

#### PUBLIC ROUTINES

    call diffusivity (t, q, u, v, p_full, p_half, z_full, z_half,
                             u_star, b_star, h, k_m, k_t, kbot)

    input:

           t     : temperature (K) [real, dimension(:,:,:) -- (:,:,pressure),
                   third index running from top of atmosphere to bottom]

           q     : water vapor specific humidity (nondimensional)
                   [real, dimension(:,:,:)]

           u     : zonal wind (m/s) [real, dimension(:,:)]

           v     : meridional wind (m/s) [real, dimension(:,:,:)]

           p_full : pressure at full levels (pascals)

           p_half : pressure at half levels (pascals)

           z_full : height of full levels (m)
                    [real, dimension(:,:,:), size(z_full,3) = size(t,3)]

           z_half : height of  half levels (m)
                    [real, dimension(:,:,:), size(z_half,3) = size(t,3) +1
                    z_half(:,:,size(z_half,3)) must be height of surface
                    (for non-eta models)!]

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

           b_star: buoyancy scale (m/s**2)
                   [real, dimension(:,:)]

                       surface stress = ustar*ustar
                       surface buoyancy flux = ustar*bstar
                          bstar > 0 => upward flux

                     (u_star and b_star are output from
                      mo_drag in monin_obukhov_mod
                      along with the drag_coeffcients )

    output:

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

           k_m     : momentum diffusivity coefficient ((meters)**2./second)
                     [real, dimension(:,:,:)]

           k_t     : temperature, vapor and scalars diffusivity coefficient
                     ((meters)**2./second)
                     [real, dimension(:,:,:)]

                    defined at half-levels
                    size(k_m and k_t,3) should be at least as large as size(t,3)
                    only the returned values at
                          levels 2 to size(t,3) are meaningful
                    other values will be returned as zero
                    That is k_m(:,:,2) is the diffusivity coefficient
                    between full model levels 1 and 2. (Full model level 1
                    is the top level of the model.)

    optional input:

           kbot    : lowest true model level (for use with eta grid point model)
                     [integer, dimension(:,:)]

#### NAMELIST

    &diffusivity_nml

    fixed_depth         should the boundary layer depth be fixed?
                        [logical, default: fixed_depth = .false.]

    depth_0             height of fixed depth boundary (meters)
                        [real, default: depth_0 = 5000.]

    frac_inner          height of the surface layer as a fraction of
                        the boundary layer depth
                        [real, default: frac_inner = 0.1]

    rich_crit_pbl       critical richardson number used to compute
                        boundary layer depth in the neutral or stable
                        case
                        [real, default: rich_crit_pbl = 1.0]

    entr_ratio          ratio of entrainment buoyancy flux to surface
                        buoyancy flux (must be >= 0.)
                        [real, default: entr_ratio = 0.2]

    parcel_buoy         scaling factor for the excess buoyancy of the
                        parcel used to determine the boundary layer
                        depth in the unstable case
                        [real, default: parcel_buoy = 2.]

    znom                nominal boundary layer depth used only in the
                        calculation of surface layer vertical velocity
                        scale.  this velocity scale is used only in
                        the calculation of parcel buoyancy in the unstable
                        case (meters)
                        [real, default: znom = 1000.]

    free_atm_diff       should there be richardson number dependent
                        mixing in the free atmosphere?
                        [logical, default: free_atm_diff = .false.]

    free_atm_skyhi_diff should the free atmospheric diffusion
                        depend on model level thickness and the
                        prandtl number depend on the richardson number
                        (as in the formulation previously used in skyhi)?
                        [logical, default: free_atm_skyhi_diff = .false.]

    pbl_mcm             When .true., the pbl K profile is that of the Manabe Climate Model.
                        [logical, default: pbl_mcm = .false.]

    rich_crit_diff      critical richardson number beneath which free
                        atmospheric diffusion occurs
                        [real, default: rich_crit_diff = 0.25 ]

    mix_len             mixing length used in free atmospheric diffusion
                        (meters)
                        [real, default: mix_len = 30.]

    rich_prandtl        Prandtl number used in the scaling of k_m to
                        k_t in the free atmospheric diffusion
                        [real, default: rich_prandtl = 1.]

    background_m        background value of K for momentum (m**2/sec)
                        [real, default: background_m = 0.]

    background_t        background value of K for temperature and tracers
                        (m**2/sec)
                        [real, default: background_t = 0.]

    Notes:  (1) To get Climate Model's PBL diffusivities set
                pbl_mcm to TRUE, fixed_depth to TRUE,
                depth_0 to 5000. and frac_inner to 0.015.

            (2) To get K-profile diffusivities, pbl_mcm
                must be FALSE (default) and fixed_depth must be
                FALSE (default).

            (3) To have any vertical diffusion in the free atmosphere
                free_atm_diff must be set to TRUE.

            (4) To get skyhi free atmospheric diffusivities, both
                free_atm_skyhi_diff and free_atm_diff must be set
                to true.

#### CHANGE HISTORY

    Revision history

    changes (10/4/1999)

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

    changes (8/16/1999)

         Code to set background diffusivities is moved out of
         diffusivity_free subroutine and into the diffusivity subroutine
         so that it is possible to set a background level of diffusivity
         even if free_atm_diff = FALSE.
         (This was impossible in previous revisions).

#### ERROR MESSAGES

    diffusivity_init:

         namelist parameters are checked to see if valid selections
         have been made.  The following settings are prohibited and
         the model will shut down if any are chosen:

         (1) frac_inner <= 0 or frac_inner >= 1.
         (2) rich_crit_pbl < 0.
         (3) entr_ratio < 0.
         (4) znom < 0.
         (5) free_atm_skyhi_diff = TRUE and free_atm_diff = FALSE
         (6) rich_crit_diff <= 0.
         (7) mix_len < 0.
         (8) rich_prandtl < 0.
         (9) background_m < 0.
         (10) background_t < 0.

#### REFERENCES

         See technical documention.

#### NOTES

        None.

#### FUTURE PLANS

        None.