c $Header: /home/ubuntu/mnt/e9_copy/MITgcm/pkg/exf/Attic/README,v 1.4 2005/08/01 19:31:02 cnh dead $
c
c
c   =========================================
c   External Forcing Package for the MITgcmUV
c   =========================================
c
c   Current Version: 0.2.2 (11-Jan-2003)
c
c
c   General Outline:
c   ----------------
c
c   This package contains routines to handle external forcing of the
c   MITgcmUV general circulation model. The following features are
c   available:
c
c   (a) Reading-in atmospheric state and/or surface fluxes from files
c       and bi-linear interpolation in time.
c
c   (b) Surface flux forcing by:
c
c         surface heat flux        -->  qnet
c         short wave radiation     -->  qsw   (optional)
c         fresh water flux         -->  empmr
c         zonal wind stress        -->  fu
c         meridional wind stress   -->  fv
c
c         In order to get the appropriate fluxes users can either use
c         flux data directly or they can provide atmospheric state
c         (atmospheric temperature, atmospheric specific humidity, etc.)
c         which is subsequently used to estimate the fluxes by using
c         bulk parameterizations.
c
c   (c) Relaxation to monthly climatologies of:
c
c         sea surface temperature  -->  theta( k = 1 )
c         sea surface salinity     -->  salt ( k = 1 )
c         potential temperature    -->  theta( k = 1,nr )
c         salinity                 -->  salt ( k = 1,nr )
c
c         As of version 0.2.1, pkg/exf only supports the reading-in
c         of the relaxation fields.  See TODO.txt for suggestions on
c         completing the relaxation package.
c
c
c   Interface to MITgcm release1:
c   -----------------------------
c
c   The following MITgcm files are affected by pkg/exf:
c
c     CPPOPTIONS.h         - Define INCLUDE_EXTERNAL_FORCING_PACKAGE
c                            and append desired pkg/exf CPP options.
c
c     packages_readparms.F      - EXF_READPARMS
c
c     packages_init_variables.F - EXF_INIT	
c
c     the_main_loop.F           - Adjoint compiler directives.
c
c     forward_step.F            - EXF_GETFORCING
c
c
c   CPP options:
c   ------------
c
c   See EXF_CPPOPTIONS.h for definition of pkg/exf CPP options.
c
c
c   Data files:
c   -----------
c
c   data.exf      :: variables related to surface fluxes
c   data.exf_clim :: variables for relaxation to climatological fields
c
c
c   Routines:
c   ----------
c
c   The package consists of two sets of routines. The first set is
c   related to surface fluxes, the second set allows one to include
c   relaxation to climatological fields.
c
c
c   Call trees:
c   -----------
c
c   exf_readparms
c     |
c     |---- exf_summary
c     |---- exf_clim_readparms
c     |---- exf_clim_summary
c
c
c   exf_Init
c     |
c     |---- exf_init_hflux
c     |---- exf_init_sflux
c     |---- exf_init_ustress
c     |---- exf_init_vstress
c     |---- exf_init_evap
c     |---- exf_init_runoff
c     |---- exf_init_atemp
c     |---- exf_init_aqh
c     |---- exf_init_lwflux
c     |---- exf_init_swflux
c     |---- exf_init_precip
c     |---- exf_init_uwind
c     |---- exf_init_vwind
c     |---- exf_clim_init
c
c
c   exf_GetForcing
c     |
c     |----  exf_getclim
c     |----  exf_getffields
c     |----  exf_GetSurfaceFluxes
c     |----  exf_MapFields
c
c
c   ===============
c   Surface fluxes:
c   ===============
c
c   Getting the forcing fields:
c
c   o exf_init_???          - Initialise external forcing fields ???.
c
c   o exf_GetsurfaceFluxes  - Mid-level routine for adding fluxes as
c                             control variables.
c
c   o exf_GetFFields        - Get the current field values.
c
c   o exf_SwapFFields       - Swap data fields.
c
c   Routines specific to bulk formulae:
c
c   o exf_bulkqsat          - Compute the saturation specific humidity.
c
c   o exf_bulkcdn           - Evaluate the neutral drag coefficient as a
c                             function of the mean wind speed at a given
c                             height.
c
c   o exf_bulkrhn           - Evaluate the Stanton number.
c
c   Getting the time data (calendar):
c
c   o exf_GetFFieldsRec     - Get the record number for the current
c                             timestep of a given field, some flags,
c                             and the linear interpolation factor.
c
c   Reading the forcing data:
c
c   o exf_set_atemp         - Read an atmospheric temperature record.
c
c   o exf_set_aqh           - Read an atmospheric humidity record.
c
c   o exf_set_hflux         - Read an atmospheric heat flux record.
c
c   o exf_set_ustress       - Read an atmospheric zonal wind stress record.
c
c   o exf_set_vstress       - Read an atmospheric meridional wind stress
c                             record.
c
c   o exf_set_uwind         - Read an atmospheric zonal wind record.
c
c   o exf_set_vwind         - Read an atmospheric meridional wind record.
c
c   o exf_set_precip        - Read  a precipitation record.
c
c   o exf_set_sflux         - Read  a salt flux record.
c
c   o exf_set_lwflux        - Read  a long  wave radiative flux record.
c
c   o exf_set_swflux        - Read  a short wave radiative flux record.
c
c
c   At the moment, a basic premise of this package is that the external
c   forcing fields are available as data sets that are regularly spaced
c   in time and space. In later versions this assumption will be relaxed
c   for time as well as for space.
c
c
c   ============
c   Climatology:
c   ============
c
c   o exf_clim_init         - Initialise the climatology code.
c
c   o exf_set_climtemp      - Get the temperature climatology's
c                             value for a given model timestep.
c
c   o exf_set_climsalt      - Get the salinity climatology's
c                             value for a given model timestep.
c
c   o exf_set_climsst       - Get the sea surface temp. climatology's
c                             value for a given model timestep.
c
c   o exf_set_climsss       - Get the sea surface salin. climatology's
c                             value for a given model timestep.
c
c
c   HOW TO GET STARTED?
c
c   There are two verification experiments, global_with_exf and
c   lab_sea that use pkg/exf.  Experiment verification/global_with_exf
c   is a repeat of verification/global_ocean.90x40x15, except that it
c   uses the pkg/exf and pkg/cal instead of the external_fields_load
c   routine.  Experiment verification/lab_sea gives exaples of using
c   pkg/exf in conjunction with pkg/seaice.
c
c
c   ATTENTION:
c   ==========
c
c   Users of this package are urged to CHECK THE SIGNS AND UNITS of
c   their data sets, especially in relation to the sign conventions
c   of the MITgcmUV!
c
c   Relevant MITgcmUV routines are:
c
c     calc_gt.F
c     calc_gs.F
c     calc_mom_rhs.F
c     external_forcing.F
c
c   Relevant external forcing package routines are:
c
c     exf_set_hflux
c     .
c     .
c     exf_set_vwind
c     exf_MapFields
c
c   All adaptations of signs and units to specific data sets should be
c   done in the routines that read the respective data. Users should
c   neither modify "external_forcing" nor "exf_MapFields" for this
c   purpose.Each data set has its own read routine. This eases customi-
c   zation (signs and units etc.).
c
c   Some routines have to be customized for the current specific
c   application:
c
c     e.g. exf_set_climtemp
c          exf_set_climsalt
c          exf_set_climsst
c          exf_set_climsss
c
c
c   ========
c   HISTORY:
c   ========
c
c   started: Christian Eckert eckert@mit.edu  30-Jun-1999
c
c   changed: Christian Eckert eckert@mit.edu  11-Jan-2000
c            - Restructured the code in order to create a package
c              for the MITgcmUV.
c
c            Christian Eckert eckert@mit.edu  12-Feb-2000
c            - Changed Routine names (package prefix: exf_)
c
c            Christian Eckert eckert@mit.edu  02-May-2000
c            - CVS version of the package.
c
c            Patrick Heimbach, heimbach@mit.edu  04-May-2000
c            - Added computation of evaporation rate for
c              ALLOW_ATM_TEMP case
c            - changed the handling of precip and sflux with respect
c              to CPP options ALLOW_BULKFORMULAE and ALLOW_ATM_TEMP
c            - included some CPP flags ALLOW_BULKFORMULAE to make
c              sure ALLOW_ATM_TEMP, ALLOW_ATM_WIND are used only in
c              conjunction with defined ALLOW_BULKFORMULAE
c            - statement functions discarded and external functions
c              initialised.
c            - file precision and field type are now prescribed in 
c              data.exf;
c              separately possible for exf_sflx.h and exf_clim.h
c              related fields.
c            - created exf_constants.h that contains
c              1. numbers
c              2. physical constants
c              3. empirical parameters
c              4. control parameters
c
c            Ralf Giering ralf.giering@fastopt.de 18-Jun-2000
c            - exf_getffields.F:
c              Swapping of forcing fields has to be switched off
c              if TAMC is used, because of generation of spurious
c              dependencies. (P.H.)
c
c            Patrick Heimbach heimbach@mit.edu 20-Jun-2000
c            - sign change of ustress/vstress incorporated into
c              scaling factors scal_ust, scal_vst in exf_mapfields.F
c            - Corrected description on how to implement exf package
c              for c27 onwards.
c            - Included unit and sign conventions valid for c28
c              in README.
c
c   mods for pkg/seaice: menemenlis@jpl.nasa.gov 20-Dec-2002
c
c   ==================================================================