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

## Module Damping_driver_mod

         Contact:   Bruce Wyman
         Reviewers:

         Tags/Status

#### OVERVIEW

         A variety of damping processes are controlled by this module.

         The following damping parameterizations are controlled
         through this module:

           1) Rayleigh damping of momentum fields
           2) Namelist control for gravity wave drag.

         Rayleigh damping uses the following formula:

            d(S)/dt = -D*(S-So)

            where S  = momentum quantity to be damped (u,v)
                  D  = user defined coefficient

            for Rayleigh damping: So = 0.

            The damping coefficient D is specified only for the top level.
            The value of D decreases hyperbolicly with level.
            The following formula is used to determine D at lower levels.

                                    P2(1)-P2(k)
               D(k) = D(1) * [ 1. + -----------  ]
                                    P2(1)+P2(k)

               P2    = P**2 (pressure squared)
               ..(1) = value at level 1 (top)
               ..(k) = value at level k

#### OTHER MODULES USED

           mg_drag_mod
         utilities_mod
      diag_manager_mod
      time_manager_mod
         constants_mod

#### PUBLIC INTERFACE

      use damping_driver_mod  [, only:  damping_driver,
                                        damping_driver_init,
                                        damping_driver_end    ]

      damping_driver      - Called every time step to compute damping terms
                            and/or call gravity wave drag.

      damping_driver_init - Must be called once before damping_driver to
                            initialize the module, read namelist input, and
                            to call initialization routines for other
                            modules used.

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

      Notes:
       1) A namelist interface controls runtime options and selects fields
          for diagnostics output.
       2) No other data files are needed.

#### PUBLIC ROUTINES

    call damping_driver ( is, js, Time, delt, pfull, phalf, zfull, zhalf,
                          u, v, t, q, r,  udt, vdt, tdt, qdt, rdt,
                          [mask, kbot] )

    Input

        is, js      starting i,j indices for the sub-window of the
                    global grid   [integer]

        Time        current time  [time_type]

        delt        time step in seconds  [real]

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

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

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

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

        u, v        zonal wind (u) and meridional wind (v) in m/s
                      [real, dimension(:,:,nlev)]

        t, q        temperature (t) in deg K, and specific humidity (q)
                    in kg vapor/kg air
                      [real, dimension(:,:,nlev)]

        r           multiple ntrace tracer fields at
                    full model levels
                      [real, dimension(:,:,nlev,ntrace)]

    Input/Output

        udt, vdt    tendencies for zonal wind (udt) and meridional
                    wind (vdt) in m/s2
                      [real, dimension(:,:,nlev)]

        tdt, qdt    temperature tendency (tdt) in degK/scc, and specific
                    humidity tendency (qdt) in kg vapor/kg air/sec.
                      [real, dimension(:,:,nlev)]

        rdt         tendency for multiple ntrace tracer fields
                       [real, dimension(:,:,nlev,ntrace)]

    Input (Optional)

        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 damping_driver_init (lonb, latb, axes, Time)

    input

       lonb      The longitude in radians of the grid box edges.
                    [real, dimension(:)]

       latb      The latitude in radians of the grid box edges.
                    [real, dimension(:)]

       axes      The axis indices that are returned by previous calls to
                 diag_axis_init. The values of this array corresponds 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 damping_driver_end

      There are no arguments to this routine.

#### NAMELIST

     &damping_driver_nml

        trayfric      damping time in seconds for Rayleigh damping of
                      momentum fields in the top nlev_rayfric layers
                      (if Trayfric < 0 then time in days)
                         [real, default: Trayfric=0.]

        nlev_rayfric  number of levels at the top of the model where
                      Rayleigh friction of momentum is performed
                      (if trayfric=0. then nlev_rayfric has no effect)
                        [integer, default: nlev_rayfric=1]

        do_mg_drag    flag for mountain gravity wave drag
                        [logical, default: do_mg_drag=.false.]

        do_conserve_energy  If TRUE the heating due to the dissipation of kinetic energy
                            by Rayleigh damping will be computed.
                             [logical, default: do_conserve_energy=.false.]

#### DIAGNOSTIC FIELDS

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

    Diagnostic fields for module name: damping

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

       udt_rdamp        u wind tendency for Rayleigh damping (m/s2)
       vdt_rdamp        u wind tendency for Rayleigh damping (m/s2)
       tdt_diss_rdamp   Dissipative heating from Rayleigh damping (deg_k/s)
       diss_heat_rdamp  Integrated dissipative heating from Rayleigh damping (W/m2)
       udt_gwd          u wind tendency for gravity wave drag (m/s2)
       vdt_gwd          v wind tendency for gravity wave drag (m/s2)
       tdt_diss_gwd     Dissipative heating from gravity wave drag (deg_k/s)
       diss_heat_gwd    Integrated dissipative heating from gravity wave drag (W/m2)
       taub             base flux for gravity wave drag (kg/m/s2)
       sgsmtn           sub-grid scale topography for gravity wave drag (m)

#### CHANGE HISTORY

    CVS Revision history

    Changes prior to CVS version control

    Changes (1/24/2000)

      * Removed the sponge damping option. This option cannot be considered
        column physics. Several namelist variables and diagnostic fields
        were removed but the interface argument lists did not chnage.
        This option may eventually be added to the dynamical core.

    Changes (10/4/1999)

      * MPP version created. Minor changes in 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.

      * There were no changes made that would cause answers to changes.

#### ERROR MESSAGES

    damping_driver

        damping_driver_init must be called first

#### REFERENCES

         None.

#### KNOWN BUGS

         There are no known bugs.

#### NOTES

         None.

#### FUTURE PLANS

         Interface and diagnostics for topographic drag will be added.