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