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

## Module hs_forcing_mod

         Contact:   Isaac Held, Bruce Wyman
         Reviewers:
         Change history: WebCVS Log for hs_forcing.f90

#### OVERVIEW

        Routines for computing heating and dissipation
          for "Held-Suarez" benchmark integration of a dry GCM

#### OTHER MODULES USED

               fms_mod
         constants_mod
      time_manager_mod
      diag_manager_mod
     field_manager_mod
    tracer_manager_mod

#### PUBLIC INTERFACE

      use hs_forcing_mod [,only: hs_forcing_init,   &
                                 hs_forcing         ]

    hs_forcing_init           : initializes module
    hs_forcing                : adds tendencies to existing tendencies

    Notes:

     Optional namelist input can be read from file input.nml.
     Diagnostic fields are specified in file diag_table.
     No restart files are needed or generated by this module.
     No data files are needed.

#### PUBLIC ROUTINES

    call hs_forcing_init ( axes, Time )

     INPUT:

        axes -- integer, dimension(4)
            axis indices (x,y,zfull,zhalf) returned by module diag_manager_mod

        Time -- type(time_type)
            the current time

    call hs_forcing ( is, ie, js, je, dt, Time, lat, phalf, pfull,
                      u, v, t, r, um, vm, tm, rm, udt, vdt, tdt, rdt
                      [, mask, kbot] )

     INPUT:  is, ie, js, je, dt, Time, lat, p_half, p_full, u, v, t, r

        is, ie, js, je -- integer, scalar
            global indices of the data window being passed

        dt -- real, scalar
            the time step (seconds)

        Time -- type(time_type)
            the current time

        lat -- real, dimension(:,:)
            latitudes of grid points in radians

        phalf -- real, dimension(:,:.:)
            half_level pressures (Pa)

        pfull -- real, dimension(:,:.:)
            full_level pressures (Pa)
            size(p_full,3) = size(p_half,3)-1

        u, v, t -- real, dimension(:,:.:)
            full level zonal wind (m/s), meridional wind(m/s), temperature (K),
            size(u,3) = size(v,3) = size(t,3) = size(p_full,3)

        r -- real, dimension(:,:.:,:)
            full level tracers
            size(r,3) = size(p_full,3)
            size(r,4) = number of tracers

     IN/OUT:

        udt, vdt, tdt -- real, dimension(:,:,:)
           udt = du/dt = tendency of u (m/(s^2)), etc
           output has heating and friction added to input tendencies

        rdt -- real, dimension(:,:.:,:)
           tendency of tracers

      OPTIONAL INPUT:  mask, kbot

        mask -- real, dimension(:,:,:)
           step-mountain/eta coordinate field mask

        kbot -- real, dimension(:,:)
           index of lowest model level (adjacent to step-mountain surface)

#### NAMELIST

    (all values listed are default values)
    (TE = radiative equilibrium -- see Held and Suarez)

    logical :: no_forcing = .false.  Turns off all Held Suarez physics.
                                     (Interfaces become dummy routines)
    				 This switch facilitates code development and testing.

    real    :: delh      =  60. (K) horizontal TE contrast from equator to pole
    real    :: t_zero    = 315. (K) TE at equator at surface
    real    :: t_strat   = 200. (K) stratospheric temperature
    real    :: delv      =  10. (K) parameter controling static stability of TE
    real    :: eps       = 0.0  (K)  not in Held and Suarez (2*eps = TE difference
                                    between NP and SP ( TE => TE + eps*sin(lat) )

    damping times
    units are (1/s) , value is inverse of damping time, if positive
              (days), value is damping time, if negative

    real    :: ka        =-40.0   radiative damping above the planetary boundary layer
    real    :: ks        =-4.0    radiative damping within the planetary boundary layer
    real    :: kf        =-1.0    frictional (Rayleigh) damping within the planetary boundary layer

    real    :: sigma_b   = 0.7    top of planetary boundary layer in sigma coordinates

    logical :: do_conserve_energy =.true.  if true, kinetic energy dissipated by friction
                                           is added to enthalpy, to conserve energy

       real :: trflux = 1.e-5   !  surface flux for optional tracer
       real :: trsink = -4.     !  damping time for tracer

#### DIAGNOSTIC FIELDS

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

    Diagnostic fields for module name identifier: hs_forcing

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

       teq              equilibrium temperature (deg_K)
       tdt_ndamp        temperture tendency for newtonian damping (deg_K/sec)
       udt_rdamp        zonal wind tendency for rayleigh damping (m/s2)
       vdt_rdamp        meridional wind tendency for rayleigh damping (m/s2)
       tdt_diss_rdamp   Dissipative heating from Rayleigh damping (deg_K/sec)
       diss_heat_rdamp  Integrated dissipative heating for Rayleigh damping (W/m2)

    NOTES

       1) Fields tdt_diss_rdamp and diss_heat_rdamp can only be output
          when namelist variable do_conserve_energy =.true.
       2) Field teq can be stored as packed data (valid range = 100,400).

#### ERROR MESSAGES

    FATAL errors in hs_forcing_mod

        have not called hs_forcing_init
            You have not called hs_forcing_init before hs_forcing.

#### REFERENCES

    Held, I. M., and M. J. Suarez, 1994: A proposal for the intercomparison
    of the dynamical cores of atmospheric general circulation models. Bulletin
    of the American Meteorological Society, 75(10), 1825-1830.

#### NOTES

    This module computes a source-sink term for all prognostic tracers.
    The source term is a globally uniform surface flux given by namelist
    variable trflux. The sink term is computed everywhere as coeff*tracer.
    The default coefficient is given by namelist variable trsink.

    The behavior of the source-sink term can also be controlled by
    field_table method "tracer_sms".
    Examples:
               "tracer_sms", "NONE"
               "tracer_sms", "ON",  "flux=1.e-3,sink=-2."

#### FUTURE PLANS

        None.