Annotation of /MITgcm/pkg/exf/README

c $Header: /u/gcmpack/MITgcm/pkg/exf/README,v 1.1.4.3 2003/02/12 07:55:53 dimitri Exp $
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   ==================================================================
1	dimitri	1.3	c $Header: /u/gcmpack/MITgcm/pkg/exf/README,v 1.1.4.3 2003/02/12 07:55:53 dimitri 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.3	c Current Version: 0.2.2 (11-Jan-2003)
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	dimitri	1.3	c See EXF_CPPOPTIONS.h for definition of pkg/exf CPP options.
68	heimbach	1.1	c
69			c
70			c Data files:
71			c -----------
72			c
73	dimitri	1.2	c data.exf :: variables related to surface fluxes
74			c data.exf_clim :: variables for relaxation to climatological fields
75	heimbach	1.1	c
76	dimitri	1.3	c
77	heimbach	1.1	c Routines:
78			c ----------
79			c
80			c The package consists of two sets of routines. The first set is
81			c related to surface fluxes, the second set allows one to include
82			c relaxation to climatological fields.
83			c
84	dimitri	1.3	c
85	heimbach	1.1	c Call trees:
86			c -----------
87			c
88	dimitri	1.2	c exf_readparms
89			c \|
90			c \|---- exf_summary
91			c \|---- exf_clim_readparms
92			c \|---- exf_clim_summary
93			c
94	heimbach	1.1	c
95			c exf_Init
96			c \|
97	dimitri	1.2	c \|---- exf_init_hflux
98			c \|---- exf_init_sflux
99			c \|---- exf_init_ustress
100			c \|---- exf_init_vstress
101			c \|---- exf_init_evap
102			c \|---- exf_init_runoff
103			c \|---- exf_init_atemp
104			c \|---- exf_init_aqh
105			c \|---- exf_init_lwflux
106			c \|---- exf_init_swflux
107			c \|---- exf_init_precip
108			c \|---- exf_init_uwind
109			c \|---- exf_init_vwind
110			c \|---- exf_clim_init
111	heimbach	1.1	c
112			c
113			c exf_GetForcing
114			c \|
115	dimitri	1.2	c \|---- exf_getclim
116			c \|---- exf_getffields
117	heimbach	1.1	c \|---- exf_GetSurfaceFluxes
118			c \|---- exf_MapFields
119			c
120			c
121			c ===============
122			c Surface fluxes:
123			c ===============
124			c
125			c Getting the forcing fields:
126			c
127	dimitri	1.2	c o exf_init_??? - Initialise external forcing fields ???.
128	heimbach	1.1	c
129			c o exf_GetsurfaceFluxes - Mid-level routine for adding fluxes as
130			c control variables.
131			c
132			c o exf_GetFFields - Get the current field values.
133			c
134			c o exf_SwapFFields - Swap data fields.
135			c
136			c Routines specific to bulk formulae:
137			c
138	dimitri	1.2	c o exf_bulkqsat - Compute the saturation specific humidity.
139	heimbach	1.1	c
140	dimitri	1.2	c o exf_bulkcdn - Evaluate the neutral drag coefficient as a
141	heimbach	1.1	c function of the mean wind speed at a given
142			c height.
143			c
144	dimitri	1.2	c o exf_bulkrhn - Evaluate the Stanton number.
145	heimbach	1.1	c
146			c Getting the time data (calendar):
147			c
148			c o exf_GetFFieldsRec - Get the record number for the current
149			c timestep of a given field, some flags,
150			c and the linear interpolation factor.
151			c
152			c Reading the forcing data:
153			c
154	dimitri	1.2	c o exf_set_atemp - Read an atmospheric temperature record.
155	heimbach	1.1	c
156	dimitri	1.2	c o exf_set_aqh - Read an atmospheric humidity record.
157	heimbach	1.1	c
158	dimitri	1.2	c o exf_set_hflux - Read an atmospheric heat flux record.
159	heimbach	1.1	c
160	dimitri	1.2	c o exf_set_ustress - Read an atmospheric zonal wind stress record.
161	heimbach	1.1	c
162	dimitri	1.2	c o exf_set_vstress - Read an atmospheric meridional wind stress
163	heimbach	1.1	c record.
164			c
165	dimitri	1.2	c o exf_set_uwind - Read an atmospheric zonal wind record.
166	heimbach	1.1	c
167	dimitri	1.2	c o exf_set_vwind - Read an atmospheric meridional wind record.
168	heimbach	1.1	c
169	dimitri	1.2	c o exf_set_precip - Read a precipitation record.
170	heimbach	1.1	c
171	dimitri	1.2	c o exf_set_sflux - Read a salt flux record.
172	heimbach	1.1	c
173	dimitri	1.2	c o exf_set_lwflux - Read a long wave radiative flux record.
174	heimbach	1.1	c
175	dimitri	1.2	c o exf_set_swflux - Read a short wave radiative flux record.
176	heimbach	1.1	c
177			c
178			c At the moment, a basic premise of this package is that the external
179			c forcing fields are available as data sets that are regularly spaced
180			c in time and space. In later versions this assumption will be relaxed
181			c for time as well as for space.
182			c
183			c
184			c ============
185			c Climatology:
186			c ============
187			c
188	dimitri	1.2	c o exf_clim_init - Initialise the climatology code.
189	heimbach	1.1	c
190	dimitri	1.2	c o exf_set_climtemp - Get the temperature climatology's
191	heimbach	1.1	c value for a given model timestep.
192			c
193	dimitri	1.2	c o exf_set_climsalt - Get the salinity climatology's
194	heimbach	1.1	c value for a given model timestep.
195			c
196	dimitri	1.2	c o exf_set_climsst - Get the sea surface temp. climatology's
197	heimbach	1.1	c value for a given model timestep.
198			c
199	dimitri	1.2	c o exf_set_climsss - Get the sea surface salin. climatology's
200	heimbach	1.1	c value for a given model timestep.
201			c
202			c
203			c HOW TO GET STARTED?
204			c
205	dimitri	1.2	c There are two verification experiments, global_with_exf and
206			c lab_sea that use pkg/exf. Experiment verification/global_with_exf
207			c is a repeat of verification/global_ocean.90x40x15, except that it
208			c uses the pkg/exf and pkg/cal instead of the external_fields_load
209			c routine. Experiment verification/lab_sea gives exaples of using
210			c pkg/exf in conjunction with pkg/seaice.
211	heimbach	1.1	c
212			c
213			c ATTENTION:
214			c ==========
215			c
216			c Users of this package are urged to CHECK THE SIGNS AND UNITS of
217			c their data sets, especially in relation to the sign conventions
218			c of the MITgcmUV!
219			c
220			c Relevant MITgcmUV routines are:
221			c
222			c calc_gt.F
223			c calc_gs.F
224			c calc_mom_rhs.F
225			c external_forcing.F
226			c
227			c Relevant external forcing package routines are:
228			c
229	dimitri	1.2	c exf_set_hflux
230	heimbach	1.1	c .
231			c .
232	dimitri	1.2	c exf_set_vwind
233	heimbach	1.1	c exf_MapFields
234			c
235			c All adaptations of signs and units to specific data sets should be
236			c done in the routines that read the respective data. Users should
237			c neither modify "external_forcing" nor "exf_MapFields" for this
238			c purpose.Each data set has its own read routine. This eases customi-
239			c zation (signs and units etc.).
240			c
241			c Some routines have to be customized for the current specific
242			c application:
243			c
244	dimitri	1.2	c e.g. exf_set_climtemp
245			c exf_set_climsalt
246			c exf_set_climsst
247			c exf_set_climsss
248	heimbach	1.1	c
249			c
250			c ========
251			c HISTORY:
252			c ========
253			c
254			c started: Christian Eckert eckert@mit.edu 30-Jun-1999
255			c
256			c changed: Christian Eckert eckert@mit.edu 11-Jan-2000
257			c - Restructured the code in order to create a package
258			c for the MITgcmUV.
259			c
260			c Christian Eckert eckert@mit.edu 12-Feb-2000
261			c - Changed Routine names (package prefix: exf_)
262			c
263			c Christian Eckert eckert@mit.edu 02-May-2000
264			c - CVS version of the package.
265			c
266			c Patrick Heimbach, heimbach@mit.edu 04-May-2000
267			c - Added computation of evaporation rate for
268			c ALLOW_ATM_TEMP case
269			c - changed the handling of precip and sflux with respect
270			c to CPP options ALLOW_BULKFORMULAE and ALLOW_ATM_TEMP
271			c - included some CPP flags ALLOW_BULKFORMULAE to make
272			c sure ALLOW_ATM_TEMP, ALLOW_ATM_WIND are used only in
273			c conjunction with defined ALLOW_BULKFORMULAE
274			c - statement functions discarded and external functions
275			c initialised.
276			c - file precision and field type are now prescribed in
277			c data.exf;
278			c separately possible for exf_sflx.h and exf_clim.h
279			c related fields.
280			c - created exf_constants.h that contains
281			c 1. numbers
282			c 2. physical constants
283			c 3. empirical parameters
284			c 4. control parameters
285			c
286			c Ralf Giering ralf.giering@fastopt.de 18-Jun-2000
287			c - exf_getffields.F:
288			c Swapping of forcing fields has to be switched off
289			c if TAMC is used, because of generation of spurious
290			c dependencies. (P.H.)
291			c
292			c Patrick Heimbach heimbach@mit.edu 20-Jun-2000
293			c - sign change of ustress/vstress incorporated into
294			c scaling factors scal_ust, scal_vst in exf_mapfields.F
295			c - Corrected description on how to implement exf package
296			c for c27 onwards.
297			c - Included unit and sign conventions valid for c28
298			c in README.
299	dimitri	1.2	c
300	dimitri	1.3	c mods for pkg/seaice: menemenlis@jpl.nasa.gov 20-Dec-2002
301	heimbach	1.1	c
302			c ==================================================================