C $Header: /home/ubuntu/mnt/e9_copy/MITgcm/pkg/flt/README.flt,v 1.1 2001/09/13 17:43:55 adcroft Exp $ C $Name: checkpoint45b_post $ 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=========================================================================