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	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=========================================================================