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 forcing_mod [,only: forcing_init,   &
                             forcing         ]

forcing_init           : initializes module
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 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 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 forcing and the desired field names (given below)
in file diag_table. See the documentation for diag_manager.

Diagnostic fields for module name identifier: 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 forcing_mod

    have not called forcing_init
        You have not called forcing_init before 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.