pkg/flt/README.flt

C $Header: $
C $Name: $
c
c     ==============================
c     FLOAT Package for the MITgcmUV
c     ==============================
c
c
c     This package allows the advection of floats during a model run.
c     Although originally intended to simulate PALACE floats
c     (floats that drift in at depth and to the surface at a defined
c     time interval) it can also run ALACE floats (non-profiling) 
c     and surface drifters as well as sample moorings (simply a 
c     non-advective, profiling float).
c
c     The stepping of the float advection is done using a second
c     order Runga-Kutta scheme (Press et al., 1992, Numerical
c     Recipes), whereby velocities and positions are bilinear
c     interpolated between the grid points.
c
c     Current version: 1.0                              06-AUG-2001
c
c     Please report any bugs and suggestions to:
c            
c            Arne Biastoch (abiastoch@ucsd.edu)
c
c     
c     Implementation in MITgcmUV
c     --------------------------
c
c     The package has only few interfaces to the model. Despite a 
c     general introduction of the flag useFLT and an initialization in 
c     packages_init_fixed.F the interfaces are in:
c
c     - forward_step.F where the main float routine is called:
c
c     #ifdef ALLOW_FLT
c     C--    Calculate float trajectories
c           if (useFLT) then
c                   CALL TIMER_START('FLOATS    [THE_MAIN_LOOP]',myThid)
c                   CALL FLT_MAIN(myIter,myTime, myThid)
c                   CALL TIMER_STOP ('FLOATS     [THE_MAIN_LOOP]',myThid)
c           endif
c     #endif
c
c     - write_checkpoint.F where float positions are written to a restart file: 
c
c     #ifdef ALLOW_FLT
c           if (useFLT) then
c                  CALL FLT_RESTART (myCurrentTime, myCurrentIter, myThid )
c           endif
c     #endif
c
c     The rest is done in the routines residing in pkg/flt. Please make
c     sure that this directory is enabled in genmake when compiling the
c     Makefile.
c
c
c     Settings at compilation time
c     ----------------------------
c
c     The main flag for switching on the float package has to be done
c     in CPP_OPTIONS.h where
c        #define ALLOW_FLT   has to be set
c
c     The package itself has its own option file called FLT_CPPOPTIONS.h.
c     Currently there are only two flags available:
c        #define FLT_NOISE   to add white noise to the advection velocity
c        #undef ALLOW_3D_FLT to allow three-dimensional float advection 
c                            (not tested yet!) instead of drifting on a
c                            pre-defined (integer) vertical level.
c
c     Other specifications are done in FLT.h:
c
c     parameter (max_npart_tile = 300) 
c        is the maximum number of floats per tile. Should be smaller
c        than the total number of floats when running on a parallel
c        environment but as small as possible to avoid too large
c        arrays. The model will stop if the number of floats per tile
c        exceeds max_npart_tile at any time.
c     parameter (max_npart_exch = 50)
c        is the maximum number of floats per tile that can be exchanged 
c        with other tiles to one side (there are 4 arrays) in one 
c        timestep. Should be generally small because only few floats 
c        leave the tile exactly at the same time.     
c
c
c     Settings at runtime
c     -------------------
c
c     useFLT=.TRUE.    
c        has to be set in namelist PACKAGES (data.pkg) to use floats
c
c     data.flt contains a namelist FLT_NML with the parameters:
c        flt_int_traj  is the time interval in seconds to sample
c                      float position and dynamic variables (T,S,U,V,Eta).
c                      To capture the whole profile cycle of a PALACE float
c                      this has to be at least as small as the
c                      shortest surface time
c
c        flt_int_prof  is the time interval in seconds to sample
c                      a whole profile of T,S,U,V (as well as
c                      positions and Eta). This has to chosen at
c                      least as small as the shortest profiling
c                      interval.
c                      Note: All profiling intervals have to be an integer
c                            multiple of this interval
c                      Note: The profile is always taken over the whole
c                            water column
c
c        Example: if one would set two sets of profiling floats,
c        - one with  5 days profiling interval and 24 hours surface time
c        - one with 10 days profiling interval and 12 hours surface time
c        one would have to set 
c        - flt_int_traj=43200
c        - flt_int_prof=432000 
c        to capture all of the floats motions
c
c        flt_noise     If FLT_NOISE is defined this is the amplitude
c                      that is added to the advection velocity by the 
c                      random number generator.
c
c        flt_file      the base filename of the float positions
c                      without tile information and ending (e.g. float_pos) 
c
c
c     Input
c     -----
c
c     The initialization is written in a way that it first looks for a
c     global file (e.g. float_pos.data). A global file is mainly used
c     for first-time initialization. If that not exists the routine looks
c     for local files (e.g. float_pos.001.001.data, etc.) that have
c     been used for storing the float positions for restart (note that
c     float restarts are ALWAYS local files). The structure of the
c     file is always the same:
c
c     Each float contains a 9 element double precision record of a 
c     direct access file. The records are:
c     
c     - npart   A unique float identifier (1,2,3,...)
c     - tstart  start date of integration of float (in s)
c               Note: If tstart=-1 floats are integrated right from the 
c               beginning
c     - xpart   x position of float (in units of XC)
c     - ypart   y position of float (in units of YC)
c     - kpart   actual vertical level of float
c     - kfloat  target level of float (should be the same as kpart at
c               the beginning)
c     - iup     flag if the float 
c               - should profile   ( >  0 = return cycle (in s) to surface) 
c               - remain at depth  ( =  0 )
c               - is a 3D float    ( = -1 ).
c               - should be advected WITHOUT additional noise ( = -2 ). 
c                 (This implies that the float is non-profiling)
c               - is a mooring     ( = -3 ), i.e. the float is not advected
c     - itop    time of float the surface (in s)
c     - tend    end  date of integration of float (in s)
c               Note: If tend=-1 floats are integrated till the end of
c               the integration
c
c     In addition the first line of the file contains a record with 
c     - the number of floats on that tile in the first record
c     - the total number of floats in the sixth record
c     Note: At first-time initialization in a global file both fields
c     should be the same.
c
c     An example how to write a float file (write_float.F) is included
c     in the verification experiment (see below)
c
c
c     Output/Visualization
c     --------------------
c
c     The output always consists of 3 series of local files:
c     - files with last positions of floats that can be used for restart
c     - files with trajectories of floats and actual values at depth
c     - files with profiles throughout the whole water column
c
c     Examples and conversion routines for the second and third series
c     into NetCDF are included in verification/flt_example/aux/.
c
c
c     Verification Experiment
c     -----------------------
c
c     The verification experiment is based on exp 4 (flow over a
c     Gaussian in a channel). There are, however, two main differences
c     to the original experiment:
c
c     - The domain has closed boundaries. Currently the float package
c       is not able to treat floats that leave the domain via open boundaries
c     - There is an additional wind forcing to speed up the currents
c       to get significant advection rates in time
c
c
c     ToDo
c     ----
c
c     - testing of 3D-floats
c     - allow floats to leave the domain via open boundaries
c
c
c     History
c     -------
c
c     - first release: Arne Biastoch (abiastoch@ucsd.edu)  06-AUG-2001
c       implemented and verified for checkpoint 40pre1
c     - incorporated into c40p9 by adcroft@mit.edu on 11/13/01
c
c=========================================================================
1	adcroft	1.1	C $Header: $
2			C $Name: $
3			c
4			c ==============================
5			c FLOAT Package for the MITgcmUV
6			c ==============================
7			c
8			c
9			c This package allows the advection of floats during a model run.
10			c Although originally intended to simulate PALACE floats
11			c (floats that drift in at depth and to the surface at a defined
12			c time interval) it can also run ALACE floats (non-profiling)
13			c and surface drifters as well as sample moorings (simply a
14			c non-advective, profiling float).
15			c
16			c The stepping of the float advection is done using a second
17			c order Runga-Kutta scheme (Press et al., 1992, Numerical
18			c Recipes), whereby velocities and positions are bilinear
19			c interpolated between the grid points.
20			c
21			c Current version: 1.0 06-AUG-2001
22			c
23			c Please report any bugs and suggestions to:
24			c
25			c Arne Biastoch (abiastoch@ucsd.edu)
26			c
27			c
28			c Implementation in MITgcmUV
29			c --------------------------
30			c
31			c The package has only few interfaces to the model. Despite a
32			c general introduction of the flag useFLT and an initialization in
33			c packages_init_fixed.F the interfaces are in:
34			c
35			c - forward_step.F where the main float routine is called:
36			c
37			c #ifdef ALLOW_FLT
38			c C-- Calculate float trajectories
39			c if (useFLT) then
40			c CALL TIMER_START('FLOATS [THE_MAIN_LOOP]',myThid)
41			c CALL FLT_MAIN(myIter,myTime, myThid)
42			c CALL TIMER_STOP ('FLOATS [THE_MAIN_LOOP]',myThid)
43			c endif
44			c #endif
45			c
46			c - write_checkpoint.F where float positions are written to a restart file:
47			c
48			c #ifdef ALLOW_FLT
49			c if (useFLT) then
50			c CALL FLT_RESTART (myCurrentTime, myCurrentIter, myThid )
51			c endif
52			c #endif
53			c
54			c The rest is done in the routines residing in pkg/flt. Please make
55			c sure that this directory is enabled in genmake when compiling the
56			c Makefile.
57			c
58			c
59			c Settings at compilation time
60			c ----------------------------
61			c
62			c The main flag for switching on the float package has to be done
63			c in CPP_OPTIONS.h where
64			c #define ALLOW_FLT has to be set
65			c
66			c The package itself has its own option file called FLT_CPPOPTIONS.h.
67			c Currently there are only two flags available:
68			c #define FLT_NOISE to add white noise to the advection velocity
69			c #undef ALLOW_3D_FLT to allow three-dimensional float advection
70			c (not tested yet!) instead of drifting on a
71			c pre-defined (integer) vertical level.
72			c
73			c Other specifications are done in FLT.h:
74			c
75			c parameter (max_npart_tile = 300)
76			c is the maximum number of floats per tile. Should be smaller
77			c than the total number of floats when running on a parallel
78			c environment but as small as possible to avoid too large
79			c arrays. The model will stop if the number of floats per tile
80			c exceeds max_npart_tile at any time.
81			c parameter (max_npart_exch = 50)
82			c is the maximum number of floats per tile that can be exchanged
83			c with other tiles to one side (there are 4 arrays) in one
84			c timestep. Should be generally small because only few floats
85			c leave the tile exactly at the same time.
86			c
87			c
88			c Settings at runtime
89			c -------------------
90			c
91			c useFLT=.TRUE.
92			c has to be set in namelist PACKAGES (data.pkg) to use floats
93			c
94			c data.flt contains a namelist FLT_NML with the parameters:
95			c flt_int_traj is the time interval in seconds to sample
96			c float position and dynamic variables (T,S,U,V,Eta).
97			c To capture the whole profile cycle of a PALACE float
98			c this has to be at least as small as the
99			c shortest surface time
100			c
101			c flt_int_prof is the time interval in seconds to sample
102			c a whole profile of T,S,U,V (as well as
103			c positions and Eta). This has to chosen at
104			c least as small as the shortest profiling
105			c interval.
106			c Note: All profiling intervals have to be an integer
107			c multiple of this interval
108			c Note: The profile is always taken over the whole
109			c water column
110			c
111			c Example: if one would set two sets of profiling floats,
112			c - one with 5 days profiling interval and 24 hours surface time
113			c - one with 10 days profiling interval and 12 hours surface time
114			c one would have to set
115			c - flt_int_traj=43200
116			c - flt_int_prof=432000
117			c to capture all of the floats motions
118			c
119			c flt_noise If FLT_NOISE is defined this is the amplitude
120			c that is added to the advection velocity by the
121			c random number generator.
122			c
123			c flt_file the base filename of the float positions
124			c without tile information and ending (e.g. float_pos)
125			c
126			c
127			c Input
128			c -----
129			c
130			c The initialization is written in a way that it first looks for a
131			c global file (e.g. float_pos.data). A global file is mainly used
132			c for first-time initialization. If that not exists the routine looks
133			c for local files (e.g. float_pos.001.001.data, etc.) that have
134			c been used for storing the float positions for restart (note that
135			c float restarts are ALWAYS local files). The structure of the
136			c file is always the same:
137			c
138			c Each float contains a 9 element double precision record of a
139			c direct access file. The records are:
140			c
141			c - npart A unique float identifier (1,2,3,...)
142			c - tstart start date of integration of float (in s)
143			c Note: If tstart=-1 floats are integrated right from the
144			c beginning
145			c - xpart x position of float (in units of XC)
146			c - ypart y position of float (in units of YC)
147			c - kpart actual vertical level of float
148			c - kfloat target level of float (should be the same as kpart at
149			c the beginning)
150			c - iup flag if the float
151			c - should profile ( > 0 = return cycle (in s) to surface)
152			c - remain at depth ( = 0 )
153			c - is a 3D float ( = -1 ).
154			c - should be advected WITHOUT additional noise ( = -2 ).
155			c (This implies that the float is non-profiling)
156			c - is a mooring ( = -3 ), i.e. the float is not advected
157			c - itop time of float the surface (in s)
158			c - tend end date of integration of float (in s)
159			c Note: If tend=-1 floats are integrated till the end of
160			c the integration
161			c
162			c In addition the first line of the file contains a record with
163			c - the number of floats on that tile in the first record
164			c - the total number of floats in the sixth record
165			c Note: At first-time initialization in a global file both fields
166			c should be the same.
167			c
168			c An example how to write a float file (write_float.F) is included
169			c in the verification experiment (see below)
170			c
171			c
172			c Output/Visualization
173			c --------------------
174			c
175			c The output always consists of 3 series of local files:
176			c - files with last positions of floats that can be used for restart
177			c - files with trajectories of floats and actual values at depth
178			c - files with profiles throughout the whole water column
179			c
180			c Examples and conversion routines for the second and third series
181			c into NetCDF are included in verification/flt_example/aux/.
182			c
183			c
184			c Verification Experiment
185			c -----------------------
186			c
187			c The verification experiment is based on exp 4 (flow over a
188			c Gaussian in a channel). There are, however, two main differences
189			c to the original experiment:
190			c
191			c - The domain has closed boundaries. Currently the float package
192			c is not able to treat floats that leave the domain via open boundaries
193			c - There is an additional wind forcing to speed up the currents
194			c to get significant advection rates in time
195			c
196			c
197			c ToDo
198			c ----
199			c
200			c - testing of 3D-floats
201			c - allow floats to leave the domain via open boundaries
202			c
203			c
204			c History
205			c -------
206			c
207			c - first release: Arne Biastoch (abiastoch@ucsd.edu) 06-AUG-2001
208			c implemented and verified for checkpoint 40pre1
209			c - incorporated into c40p9 by adcroft@mit.edu on 11/13/01
210			c
211			c=========================================================================