c $Header: /home/ubuntu/mnt/e9_copy/MITgcm/pkg/exf/Attic/README,v 1.2 2002/12/28 10:11:11 dimitri Exp $
c
c
c   =========================================
c   External Forcing Package for the MITgcmUV
c   =========================================
c
c   Current Version: 0.2.1 (20-Dec-2002)
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   The following CPP options are available for this package:
c
c   >>> INCLUDE_EXTERNAL_FORCING_PACKAGE <<<
c       Include this package into the setup.
c
c   >>> EXF_VERBOSE <<<
c       Do a bit more printout for the log file than usual.
c
c   >>> ALLOW_BULKFORMULAE <<<
c       Allows the use of bulk formulae in order to estimate
c       the turbulent fluxes at the ocean's surface.
c                                        
c   >>> ALLOW_ATM_TEMP <<<
c       Allows the use the atmospheric temperature and specific
c       humidity to estimate the sensible and latent heat fluxes.
c
c   >>> ALLOW_ATM_WIND <<<
c       Allows the use the atmospheric wind field to estimate the
c       wind stress at the ocean's surface.
c
c   >>> EXF_NO_BULK_COMPUTATIONS <<<
c       If defined, no bulk formulae computations are carried out
c       within pkg/exf.  This option, in combination with
c       ALLOW_BULKFORMULAE, ALLOW_ATM_TEMP, and ALLOW_ATM_WIND
c       can be used to read-in the atmospheric state and pass it
c       on to a separate package for bulk formulae computations.
c
c   >>> EXF_READ_EVAP <<<
c       If defined, evaporation is read-in from a file, rather than
c       computed from atmospheric state.
c
c   >>> ALLOW_CLIM_CYCLIC <<<
c       If defined, relaxation file record numbers are assumed 1 to
c       12 corresponding to Jan. through Dec.  Otherwise relaxation
c       file record numbers are specified in data.exf_clim
c
c   >>> ALLOW_CLIMTEMP_RELAXATION <<<
c       Allow the relaxation to a monthly climatology of potential
c       temperature, e.g. the Levitus climatology.
c
c   >>> ALLOW_CLIMSALT_RELAXATION <<<
c       Allow the relaxation to a monthly climatology of salinity,
c       e.g. the Levitus climatology.
c
c   >>> ALLOW_CLIMSST_RELAXATION <<<
c       Allow the relaxation to a monthly climatology of sea surface
c       temperature, e.g. the Reynolds climatology.
c
c   >>> ALLOW_CLIMSSS_RELAXATION <<<
c       Allow the relaxation to a monthly climatology of sea surface
c       salinity, e.g. the Levitus climatology.
c
c
c
c   Unit and sign conventions for forcing fields (valid for c28 !)
c   --------------------------------------------------------------

- tflux/qnet: net heat flux (ATTENTION: distinguish qnet vs. qnet-sw)
---------------------------
        -> read in as tflux:   W/m**2 = kg/s**3 (>0 for oceanic cooling)
        -> scaled to qnet:     scal_hfl = +1
        -> transformed to gT:  Qnet     ->   Qnet/(rhonil*Cp*dR)
                               W/m**2   ->   K/s
        -> usage in gT:        gT = gT - qnet[K/s]

- swflux/qsw: shortwave flux
----------------------------
        -> read in as swflux: W/m**2 = kg/s**3 (>0 for oceanic cooling)
        -> for bulk forcing:  swflux ADDED to hfl = tflux
        -> scaled to qsw:     scal_swf = +1
        -> transformed to gT: only for #ifdef SHORTWAVE_HEATING
                              (currently not used)

- lwflux/qlw: longwave flux
---------------------------
        -> read in as lwflux:  m/s (>0 for oceanic cooling)
        -> for bulk forcing:  lwflux ADDED to hfl = tflux
        -> scaled to qlw:     not used.
        -> transformed to gT: not used.

- sflux/empmr: freshwater flux (Evap. minus precip. minus runoff)
------------------------------
        -> read in as tflux:   m/s (>0 for ocean salting)
        -> scaled to empmr:    scal_hfl = +1
        -> transformed to gS:  empmr     ->   empmr*35./*dR
                               m/s       ->   psu/s
        -> usage in gS:        gS = gS + empmr[psu/s]

- ustress/fu: zonal wind stress (West/East)
-------------------------------
        -> read in as ustress: N/m**2 (>0 from West to East)
        -> scaled to fu   :    scal_ust = -1
        -> transformed to gU:  fu        ->   fu/(rhoNil*dR)
                               N/m**2    ->   m/s**2
        -> usage in gU:        gU = gU + fu[m/s**2]

- vstress/fv: meridional wind stress (South/North)
------------------------------------
        -> read in as vstress: N/m**2 (>0 from South to North)
        -> scaled to fv   :    scal_vst = -1
        -> transformed to gV:  fv        ->   fv/(rhoNil*dR)
                               N/m**2    ->   m/s**2
        -> usage in gV:        gV = gV + fv[m/s**2]
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   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   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
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
c            - Changed Routine names (package prefix: exf_)
c
c            Christian Eckert eckert@mit.edu  02-May-2000
c
c            - CVS version of the package.
c
c            Patrick Heimbach, heimbach@mit.edu  04-May-2000
c
c            - Added computation of evaporation rate for
c              ALLOW_ATM_TEMP case
c
c            - changed the handling of precip and sflux with respect
c              to CPP options ALLOW_BULKFORMULAE and ALLOW_ATM_TEMP
c
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
c            - statement functions discarded and external functions
c              initialised.
c
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
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
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
c            - sign change of ustress/vstress incorporated into
c              scaling factors scal_ust, scal_vst in exf_mapfields.F
c
c            - Corrected description on how to implement exf package
c              for c27 onwards.
c
c            - Included unit and sign conventions valid for c28
c              in README.
c
c            Dimitris Menemenlis menemenlis@jpl.nasa.gov 20-Dec-2002
c
c            - Modifications for using pkg/exf with pkg/seaice.
c
c   ==================================================================