Annotation of /MITgcm/pkg/exf/README

c $Header: /u/gcmpack/MITgcm/pkg/exf/README,v 1.1 2001/05/14 22:08:40 heimbach 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   ==================================================================
1	dimitri	1.2	c $Header: /u/gcmpack/MITgcm/pkg/exf/README,v 1.1 2001/05/14 22:08:40 heimbach Exp $
2	heimbach	1.1	c
3			c
4			c =========================================
5			c External Forcing Package for the MITgcmUV
6			c =========================================
7			c
8	dimitri	1.2	c Current Version: 0.2.1 (20-Dec-2002)
9	heimbach	1.1	c
10			c
11			c General Outline:
12			c ----------------
13			c
14			c This package contains routines to handle external forcing of the
15			c MITgcmUV general circulation model. The following features are
16			c available:
17			c
18	dimitri	1.2	c (a) Reading-in atmospheric state and/or surface fluxes from files
19			c and bi-linear interpolation in time.
20			c
21			c (b) Surface flux forcing by:
22	heimbach	1.1	c
23			c surface heat flux --> qnet
24	dimitri	1.2	c short wave radiation --> qsw (optional)
25	heimbach	1.1	c fresh water flux --> empmr
26			c zonal wind stress --> fu
27			c meridional wind stress --> fv
28			c
29			c In order to get the appropriate fluxes users can either use
30	dimitri	1.2	c flux data directly or they can provide atmospheric state
31	heimbach	1.1	c (atmospheric temperature, atmospheric specific humidity, etc.)
32	dimitri	1.2	c which is subsequently used to estimate the fluxes by using
33	heimbach	1.1	c bulk parameterizations.
34			c
35	dimitri	1.2	c (c) Relaxation to monthly climatologies of:
36	heimbach	1.1	c
37	dimitri	1.2	c sea surface temperature --> theta( k = 1 )
38			c sea surface salinity --> salt ( k = 1 )
39	heimbach	1.1	c potential temperature --> theta( k = 1,nr )
40			c salinity --> salt ( k = 1,nr )
41			c
42	dimitri	1.2	c As of version 0.2.1, pkg/exf only supports the reading-in
43			c of the relaxation fields. See TODO.txt for suggestions on
44			c completing the relaxation package.
45	heimbach	1.1	c
46			c
47	dimitri	1.2	c Interface to MITgcm release1:
48	heimbach	1.1	c -----------------------------
49	dimitri	1.2	c
50			c The following MITgcm files are affected by pkg/exf:
51			c
52			c CPPOPTIONS.h - Define INCLUDE_EXTERNAL_FORCING_PACKAGE
53			c and append desired pkg/exf CPP options.
54			c
55			c packages_readparms.F - EXF_READPARMS
56			c
57			c packages_init_variables.F - EXF_INIT
58			c
59			c the_main_loop.F - Adjoint compiler directives.
60			c
61			c forward_step.F - EXF_GETFORCING
62	heimbach	1.1	c
63			c
64			c CPP options:
65			c ------------
66			c
67			c The following CPP options are available for this package:
68			c
69			c >>> INCLUDE_EXTERNAL_FORCING_PACKAGE <<<
70			c Include this package into the setup.
71			c
72	dimitri	1.2	c >>> EXF_VERBOSE <<<
73	heimbach	1.1	c Do a bit more printout for the log file than usual.
74			c
75			c >>> ALLOW_BULKFORMULAE <<<
76	dimitri	1.2	c Allows the use of bulk formulae in order to estimate
77			c the turbulent fluxes at the ocean's surface.
78	heimbach	1.1	c
79			c >>> ALLOW_ATM_TEMP <<<
80	dimitri	1.2	c Allows the use the atmospheric temperature and specific
81	heimbach	1.1	c humidity to estimate the sensible and latent heat fluxes.
82			c
83			c >>> ALLOW_ATM_WIND <<<
84	dimitri	1.2	c Allows the use the atmospheric wind field to estimate the
85	heimbach	1.1	c wind stress at the ocean's surface.
86			c
87	dimitri	1.2	c >>> EXF_NO_BULK_COMPUTATIONS <<<
88			c If defined, no bulk formulae computations are carried out
89			c within pkg/exf. This option, in combination with
90			c ALLOW_BULKFORMULAE, ALLOW_ATM_TEMP, and ALLOW_ATM_WIND
91			c can be used to read-in the atmospheric state and pass it
92			c on to a separate package for bulk formulae computations.
93			c
94			c >>> EXF_READ_EVAP <<<
95			c If defined, evaporation is read-in from a file, rather than
96			c computed from atmospheric state.
97			c
98			c >>> ALLOW_CLIM_CYCLIC <<<
99			c If defined, relaxation file record numbers are assumed 1 to
100			c 12 corresponding to Jan. through Dec. Otherwise relaxation
101			c file record numbers are specified in data.exf_clim
102			c
103	heimbach	1.1	c >>> ALLOW_CLIMTEMP_RELAXATION <<<
104			c Allow the relaxation to a monthly climatology of potential
105			c temperature, e.g. the Levitus climatology.
106			c
107			c >>> ALLOW_CLIMSALT_RELAXATION <<<
108			c Allow the relaxation to a monthly climatology of salinity,
109			c e.g. the Levitus climatology.
110			c
111			c >>> ALLOW_CLIMSST_RELAXATION <<<
112			c Allow the relaxation to a monthly climatology of sea surface
113			c temperature, e.g. the Reynolds climatology.
114			c
115			c >>> ALLOW_CLIMSSS_RELAXATION <<<
116			c Allow the relaxation to a monthly climatology of sea surface
117			c salinity, e.g. the Levitus climatology.
118			c
119			c
120			c
121			c Unit and sign conventions for forcing fields (valid for c28 !)
122			c --------------------------------------------------------------
123
124			- tflux/qnet: net heat flux (ATTENTION: distinguish qnet vs. qnet-sw)
125			---------------------------
126			-> read in as tflux: W/m2 = kg/s3 (>0 for oceanic cooling)
127			-> scaled to qnet: scal_hfl = +1
128			-> transformed to gT: Qnet -> Qnet/(rhonilCpdR)
129			W/m**2 -> K/s
130			-> usage in gT: gT = gT - qnet[K/s]
131
132			- swflux/qsw: shortwave flux
133			----------------------------
134			-> read in as swflux: W/m2 = kg/s3 (>0 for oceanic cooling)
135			-> for bulk forcing: swflux ADDED to hfl = tflux
136			-> scaled to qsw: scal_swf = +1
137			-> transformed to gT: only for #ifdef SHORTWAVE_HEATING
138			(currently not used)
139
140			- lwflux/qlw: longwave flux
141			---------------------------
142			-> read in as lwflux: m/s (>0 for oceanic cooling)
143			-> for bulk forcing: lwflux ADDED to hfl = tflux
144			-> scaled to qlw: not used.
145			-> transformed to gT: not used.
146
147			- sflux/empmr: freshwater flux (Evap. minus precip. minus runoff)
148			------------------------------
149			-> read in as tflux: m/s (>0 for ocean salting)
150			-> scaled to empmr: scal_hfl = +1
151			-> transformed to gS: empmr -> empmr35./dR
152			m/s -> psu/s
153			-> usage in gS: gS = gS + empmr[psu/s]
154
155			- ustress/fu: zonal wind stress (West/East)
156			-------------------------------
157			-> read in as ustress: N/m**2 (>0 from West to East)
158			-> scaled to fu : scal_ust = -1
159			-> transformed to gU: fu -> fu/(rhoNil*dR)
160			N/m2 -> m/s2
161			-> usage in gU: gU = gU + fu[m/s**2]
162
163			- vstress/fv: meridional wind stress (South/North)
164			------------------------------------
165			-> read in as vstress: N/m**2 (>0 from South to North)
166			-> scaled to fv : scal_vst = -1
167			-> transformed to gV: fv -> fv/(rhoNil*dR)
168			N/m2 -> m/s2
169			-> usage in gV: gV = gV + fv[m/s**2]
170			c
171			c
172			c Data files:
173			c -----------
174			c
175	dimitri	1.2	c data.exf :: variables related to surface fluxes
176			c data.exf_clim :: variables for relaxation to climatological fields
177	heimbach	1.1	c
178			c Routines:
179			c ----------
180			c
181			c The package consists of two sets of routines. The first set is
182			c related to surface fluxes, the second set allows one to include
183			c relaxation to climatological fields.
184			c
185			c Call trees:
186			c -----------
187			c
188	dimitri	1.2	c exf_readparms
189			c \|
190			c \|---- exf_summary
191			c \|---- exf_clim_readparms
192			c \|---- exf_clim_summary
193			c
194	heimbach	1.1	c
195			c exf_Init
196			c \|
197	dimitri	1.2	c \|---- exf_init_hflux
198			c \|---- exf_init_sflux
199			c \|---- exf_init_ustress
200			c \|---- exf_init_vstress
201			c \|---- exf_init_evap
202			c \|---- exf_init_runoff
203			c \|---- exf_init_atemp
204			c \|---- exf_init_aqh
205			c \|---- exf_init_lwflux
206			c \|---- exf_init_swflux
207			c \|---- exf_init_precip
208			c \|---- exf_init_uwind
209			c \|---- exf_init_vwind
210			c \|---- exf_clim_init
211	heimbach	1.1	c
212			c
213			c exf_GetForcing
214			c \|
215	dimitri	1.2	c \|---- exf_getclim
216			c \|---- exf_getffields
217	heimbach	1.1	c \|---- exf_GetSurfaceFluxes
218			c \|---- exf_MapFields
219			c
220			c
221			c ===============
222			c Surface fluxes:
223			c ===============
224			c
225			c Getting the forcing fields:
226			c
227	dimitri	1.2	c o exf_init_??? - Initialise external forcing fields ???.
228	heimbach	1.1	c
229			c o exf_GetsurfaceFluxes - Mid-level routine for adding fluxes as
230			c control variables.
231			c
232			c o exf_GetFFields - Get the current field values.
233			c
234			c o exf_SwapFFields - Swap data fields.
235			c
236			c Routines specific to bulk formulae:
237			c
238	dimitri	1.2	c o exf_bulkqsat - Compute the saturation specific humidity.
239	heimbach	1.1	c
240	dimitri	1.2	c o exf_bulkcdn - Evaluate the neutral drag coefficient as a
241	heimbach	1.1	c function of the mean wind speed at a given
242			c height.
243			c
244	dimitri	1.2	c o exf_bulkrhn - Evaluate the Stanton number.
245	heimbach	1.1	c
246			c Getting the time data (calendar):
247			c
248			c o exf_GetFFieldsRec - Get the record number for the current
249			c timestep of a given field, some flags,
250			c and the linear interpolation factor.
251			c
252			c Reading the forcing data:
253			c
254	dimitri	1.2	c o exf_set_atemp - Read an atmospheric temperature record.
255	heimbach	1.1	c
256	dimitri	1.2	c o exf_set_aqh - Read an atmospheric humidity record.
257	heimbach	1.1	c
258	dimitri	1.2	c o exf_set_hflux - Read an atmospheric heat flux record.
259	heimbach	1.1	c
260	dimitri	1.2	c o exf_set_ustress - Read an atmospheric zonal wind stress record.
261	heimbach	1.1	c
262	dimitri	1.2	c o exf_set_vstress - Read an atmospheric meridional wind stress
263	heimbach	1.1	c record.
264			c
265	dimitri	1.2	c o exf_set_uwind - Read an atmospheric zonal wind record.
266	heimbach	1.1	c
267	dimitri	1.2	c o exf_set_vwind - Read an atmospheric meridional wind record.
268	heimbach	1.1	c
269	dimitri	1.2	c o exf_set_precip - Read a precipitation record.
270	heimbach	1.1	c
271	dimitri	1.2	c o exf_set_sflux - Read a salt flux record.
272	heimbach	1.1	c
273	dimitri	1.2	c o exf_set_lwflux - Read a long wave radiative flux record.
274	heimbach	1.1	c
275	dimitri	1.2	c o exf_set_swflux - Read a short wave radiative flux record.
276	heimbach	1.1	c
277			c
278			c At the moment, a basic premise of this package is that the external
279			c forcing fields are available as data sets that are regularly spaced
280			c in time and space. In later versions this assumption will be relaxed
281			c for time as well as for space.
282			c
283			c
284			c ============
285			c Climatology:
286			c ============
287			c
288	dimitri	1.2	c o exf_clim_init - Initialise the climatology code.
289	heimbach	1.1	c
290	dimitri	1.2	c o exf_set_climtemp - Get the temperature climatology's
291	heimbach	1.1	c value for a given model timestep.
292			c
293	dimitri	1.2	c o exf_set_climsalt - Get the salinity climatology's
294	heimbach	1.1	c value for a given model timestep.
295			c
296	dimitri	1.2	c o exf_set_climsst - Get the sea surface temp. climatology's
297	heimbach	1.1	c value for a given model timestep.
298			c
299	dimitri	1.2	c o exf_set_climsss - Get the sea surface salin. climatology's
300	heimbach	1.1	c value for a given model timestep.
301			c
302			c
303			c HOW TO GET STARTED?
304			c
305	dimitri	1.2	c There are two verification experiments, global_with_exf and
306			c lab_sea that use pkg/exf. Experiment verification/global_with_exf
307			c is a repeat of verification/global_ocean.90x40x15, except that it
308			c uses the pkg/exf and pkg/cal instead of the external_fields_load
309			c routine. Experiment verification/lab_sea gives exaples of using
310			c pkg/exf in conjunction with pkg/seaice.
311	heimbach	1.1	c
312			c
313			c ATTENTION:
314			c ==========
315			c
316			c Users of this package are urged to CHECK THE SIGNS AND UNITS of
317			c their data sets, especially in relation to the sign conventions
318			c of the MITgcmUV!
319			c
320			c Relevant MITgcmUV routines are:
321			c
322			c calc_gt.F
323			c calc_gs.F
324			c calc_mom_rhs.F
325			c external_forcing.F
326			c
327			c Relevant external forcing package routines are:
328			c
329	dimitri	1.2	c exf_set_hflux
330	heimbach	1.1	c .
331			c .
332	dimitri	1.2	c exf_set_vwind
333	heimbach	1.1	c exf_MapFields
334			c
335			c All adaptations of signs and units to specific data sets should be
336			c done in the routines that read the respective data. Users should
337			c neither modify "external_forcing" nor "exf_MapFields" for this
338			c purpose.Each data set has its own read routine. This eases customi-
339			c zation (signs and units etc.).
340			c
341			c Some routines have to be customized for the current specific
342			c application:
343			c
344	dimitri	1.2	c e.g. exf_set_climtemp
345			c exf_set_climsalt
346			c exf_set_climsst
347			c exf_set_climsss
348	heimbach	1.1	c
349			c
350			c ========
351			c HISTORY:
352			c ========
353			c
354			c started: Christian Eckert eckert@mit.edu 30-Jun-1999
355			c
356			c changed: Christian Eckert eckert@mit.edu 11-Jan-2000
357			c
358			c - Restructured the code in order to create a package
359			c for the MITgcmUV.
360			c
361			c Christian Eckert eckert@mit.edu 12-Feb-2000
362			c
363			c - Changed Routine names (package prefix: exf_)
364			c
365			c Christian Eckert eckert@mit.edu 02-May-2000
366			c
367			c - CVS version of the package.
368			c
369			c Patrick Heimbach, heimbach@mit.edu 04-May-2000
370			c
371			c - Added computation of evaporation rate for
372			c ALLOW_ATM_TEMP case
373			c
374			c - changed the handling of precip and sflux with respect
375			c to CPP options ALLOW_BULKFORMULAE and ALLOW_ATM_TEMP
376			c
377			c - included some CPP flags ALLOW_BULKFORMULAE to make
378			c sure ALLOW_ATM_TEMP, ALLOW_ATM_WIND are used only in
379			c conjunction with defined ALLOW_BULKFORMULAE
380			c
381			c - statement functions discarded and external functions
382			c initialised.
383			c
384			c - file precision and field type are now prescribed in
385			c data.exf;
386			c separately possible for exf_sflx.h and exf_clim.h
387			c related fields.
388			c
389			c - created exf_constants.h that contains
390			c 1. numbers
391			c 2. physical constants
392			c 3. empirical parameters
393			c 4. control parameters
394			c
395			c Ralf Giering ralf.giering@fastopt.de 18-Jun-2000
396			c
397			c - exf_getffields.F:
398			c Swapping of forcing fields has to be switched off
399			c if TAMC is used, because of generation of spurious
400			c dependencies. (P.H.)
401			c
402			c Patrick Heimbach heimbach@mit.edu 20-Jun-2000
403			c
404			c - sign change of ustress/vstress incorporated into
405			c scaling factors scal_ust, scal_vst in exf_mapfields.F
406			c
407			c - Corrected description on how to implement exf package
408			c for c27 onwards.
409			c
410			c - Included unit and sign conventions valid for c28
411			c in README.
412	dimitri	1.2	c
413			c Dimitris Menemenlis menemenlis@jpl.nasa.gov 20-Dec-2002
414			c
415			c - Modifications for using pkg/exf with pkg/seaice.
416	heimbach	1.1	c
417			c ==================================================================