Warning, /doc/outp_pkgs/flt.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 1e528bb7 on 2019-09-30 03:03:39 UTC
5ab6faf8fd gael*0001
0002 Introduction
0003 ------------
0004
1e528bb74e gael*0005 This section describes the :filelink:`pkg/flt` package and is largely based on the original documentation provided by `Arne Biastoch` and `Alistair Adcroft` circa 2001.
0006 :filelink:`pkg/flt` computes float trajectories and simulates the behavior of profiling floats during a model run.
0007 Profiling floats (e.g.) Argo) typically drift at depth and go back to the surface at pre-defined time intervals.
0008 However, :filelink:`pkg/flt` can also simulate observing devices such as non-profiling floats or surface drifters.
0009
0010 The package's core functionalities are operated by the `flt_main` call in `forward_step` (see below for details). Checkpointing is supported via `flt_write_pickup` called in `packages_write_pickup`.
0011
0012 Time-stepping of float locations is based on a second- or fourth-order Runga-Kutta scheme (Press et al., 1992, Numerical Recipes).
0013 Velocities and positions are interpolated between grid points to the simulated device location, and various types of noise can be added the simulated displacements.
0014 Spatial interpolation is bilinear close to boundaries and otherwise a polynomial interpolation. Float positions are expressed in local grid index space.
0015
0016
0017 Compile-time options in `FLT_OPTIONS.h`
0018 ---------------------------------------
0019
0020 .. tabularcolumns:: |\Y{.4}|L|L|
0021
0022
0023 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0024 | CPP Flag Name | Default | Description |
0025 +===============================================+=========+======================================================================================================================+
0026 | :varlink:`ALLOW_3D_FLT` | #define | allow three-dimensional float displacements |
0027 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0028 | :varlink:`USE_FLT_ALT_NOISE` | #define | use alternative method of adding random noise |
0029 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0030 | :varlink:`ALLOW_FLT_3D_NOISE` | #define | add noise also to the vertical velocity of 3D floats |
0031 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0032 | :varlink:`FLT_SECOND_ORDER_RUNGE_KUTTA` | #undef | revert to old second-order Runge-Kutta |
0033 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0034 | :varlink:`FLT_WITHOUT_X_PERIODICITY` | #undef | prevent floats to re-enter the opposite side of a periodic domain |
0035 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0036 | :varlink:`FLT_WITHOUT_Y_PERIODICITY` | #undef | prevent floats to re-enter the opposite side of a periodic domain |
0037 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0038 | :varlink:`DEVEL_FLT_EXCH2` | #undef | allow experimentation with pkg/flt + exch2 despite incomplete implementation |
0039 +-----------------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
0040
0041 Compile-time parameters in `FLT_SIZE.h` include:
0042 ------------------------------------------------
5ab6faf8fd gael*0043
0044 parameter (`max_npart_tile` = 300)
0045 is the maximum number of floats per tile. Should be smaller
0046 than the total number of floats when running on a parallel
0047 environment but as small as possible to avoid too large
0048 arrays. The model will stop if the number of floats per tile
0049 exceeds max_npart_tile at any time.
0050 parameter (`max_npart_exch` = 50)
0051 is the maximum number of floats per tile that can be exchanged
0052 with other tiles to one side (there are 4 arrays) in one
0053 timestep. Should be generally small because only few floats
0054 leave the tile exactly at the same time.
0055
1e528bb74e gael*0056 Run-time options in `data.flt` include:
0057 ---------------------------------------
5ab6faf8fd gael*0058
0059 `flt_int_traj`
0060 is the time interval in seconds to sample float position and dynamic variables (T,S,U,V,Eta).
0061 To capture the whole profile cycle of a PALACE float this has to be at least as small as the shortest surface time
0062
0063 `flt_int_prof`
0064 is the time interval in seconds to sample a whole profile of T,S,U,V (as well as
0065 positions and Eta). This has to chosen at least as small as the shortest profiling interval.
0066
0067 `flt_noise`
0068 If `FLT_NOISE` is defined then this is the amplitude that is added to the advection velocity by the random number generator.
0069
0070 `flt_file`
0071 is the base filename of the float positions without tile information and ending (e.g. `float_pos`)
0072
1e528bb74e gael*0073 `flt_selectTrajOutp`
0074 selects variables to output following float trajectories (=0 : none ; =1 : position only ; =2 : +p,u,v,t,s)
0075
0076 flt_selectProfOutp`
0077 selects variables to output when floats profile (=0 : none ; =1 : position only ; =2 : +p,u,v,t,s)
0078
0079 `flt_deltaT`
0080 is equal to `deltaTClock` by default
0081
0082 `FLT_Iter0`
0083 is the time step when floats are initialized
0084
0085 `mapIniPos2Index`
0086 converts float initial positions to local, fractional indices (`.TRUE.` by default)
0087
0088 *Notes:* `flt_int_prof` is the time between getting profiles, not the the return cycle of the float to the surface. The latter can be specified individually for every float. Because the mechanism
0089 for returning to the surface is called in the profiling routine flt_int_prof has to be the minimum of all iup(max_npart). The subsampling of profiles can be done later in the analysis.
0090
0091 *Notes:* All profiling intervals have to be an integer multiple of `flt_int_prof`. The profile is always taken over the whole water column.
0092 For example, let's assume that one wants a first set of floats with 5 days profiling interval and 24 hours surface time, and another one with 10 days profiling interval and 12 hours surface time.
0093 To capture all of the floats motions, one then would have to set `flt_int_traj=43200` and `flt_int_prof=432000`.
0094
0095 Input Files
0096 -----------
0097
0098 If `nIter0.EQ.FLT_Iter0` then `flt_init_varia` first looks for a global file (e.g. `float_pos.data`).
0099 If that file does not exists then `flt_init_varia` looks for local files (e.g. `float_pos.001.001.data`, etc.)
0100 or for local pickup files that have been generated during a previous model run (e.g. `pickup_flt.ckptA.001.001.data`, etc.).
0101
0102
0103 The first line of these input file provides:
0104
0105 - the number of floats on that tile in the first record
0106 - the total number of floats in the sixth record
0107
0108 *Notes:* when using a global file at first-time initialization both fields should be the same.
5ab6faf8fd gael*0109
1e528bb74e gael*0110 Afterwards the input files contain one 9-element double-precision record for each float:
5ab6faf8fd gael*0111
0112 ::
0113
0114 npart A unique float identifier (1,2,3,...)
0115 tstart start date of integration of float (in s)
0116 - If tstart=-1 floats are integrated right from the beginning
0117 xpart x position of float (in units of XC)
0118 ypart y position of float (in units of YC)
0119 kpart actual vertical level of float
0120 kfloat target level of float
0121 - should be the same as kpart at the beginning
0122 iup flag if the float
0123 - should profile ( > 0 = return cycle (in s) to surface)
0124 - remain at depth ( = 0 )
0125 - is a 3D float ( = -1 ).
0126 - should be advected WITHOUT additional noise ( = -2 ).
0127 (This implies that the float is non-profiling)
0128 - is a mooring ( = -3 ), i.e. the float is not advected
0129 itop time of float the surface (in s)
0130 tend end date of integration of float (in s)
0131 - If tend=-1 floats are integrated till the end of the integration
0132
1e528bb74e gael*0133 *Notes:* an example how to write a float file (`write_float.F`) is included in the verification experiment documented below.
5ab6faf8fd gael*0134
1e528bb74e gael*0135 Output Files
0136 ------------
5ab6faf8fd gael*0137
1e528bb74e gael*0138 The output consists of 3 sets of local files:
5ab6faf8fd gael*0139
1e528bb74e gael*0140 - `pickup_flt*` : last positions of floats that can be used for restart
0141 - `float_trajectories*` : trajectories of floats and actual values at depth
0142 - `float_profiles*` : profiles throughout the whole water column
5ab6faf8fd gael*0143
1e528bb74e gael*0144 Verification Experiment
0145 -----------------------
5ab6faf8fd gael*0146
1e528bb74e gael*0147 The verification experiment is based on `exp4` (flow over a Gaussian in a channel). The two main difference is that an additional wind forcing was introduced to speed up the currents.
5ab6faf8fd gael*0148
1e528bb74e gael*0149 A few utilities are included that were supposedly used to prepare input for `pkg/flt` and / or visualize its output:
5ab6faf8fd gael*0150
1e528bb74e gael*0151 ::
5ab6faf8fd gael*0152
1e528bb74e gael*0153 extra/cvfloat.F90
0154 extra/cvprofiles.F
0155 extra/write_float.F
0156 input/convert_ini.m
0157 input/read_flt_traj.m
5ab6faf8fd gael*0158
1e528bb74e gael*0159 Algorithm details
0160 -----------------
5ab6faf8fd gael*0161
1e528bb74e gael*0162 A summary of what `flt_main.F` currently does is as follows:
0163
0164 ::
0165
0166 CALL FLT_RUNGA4
0167 CALL FLT_TRILINEAR
0168 or CALL FLT_BILINEAR
0169 or CALL FLT_RUNGA2
0170 CALL FLT_TRILINEAR
0171 or CALL FLT_BILINEAR
0172 CALL FLT_EXCH2
0173 CALL EXCH2_SEND_PUT_VEC_RL
0174 CALL EXCH2_RECV_GET_VEC_RL
0175 or CALL FLT_EXCHG
0176 CALL EXCH_SEND_PUT_VEC_X_RL
0177 CALL EXCH_RECV_GET_VEC_X_RL
0178 CALL EXCH_SEND_PUT_VEC_Y_RL
0179 CALL EXCH_RECV_GET_VEC_Y_RL
0180 CALL FLT_UP
0181 CALL FLT_DOWN
0182 CALL FLT_TRAJ
5ab6faf8fd gael*0183
0184 A summary of included fortran files is provided inside `flt_main.F`:
0185
0186 ::
0187
0188 Main Routines:
0189 C
0190 C o flt_main - Integrates the floats forward and stores
0191 C positions and vertical profiles at specific
0192 C time intervals.
0193 C o flt_readparms - Read parameter file
0194 C o flt_init_fixed - Initialise fixed
0195 C o flt_init_varia - Initialise the floats
0196 C o flt_restart - Writes restart data to file (=> renamed: flt_write_pickup)
0197 C
0198 C Second Level Subroutines:
0199 C
0200 C o flt_runga2 - Second order Runga-Kutta inetgration (default)
0201 C o flt_exchg - Does a new distribution of floats over tiles
0202 C after every integration step.
0203 C o flt_up - moves float to the surface (if flag is set)
0204 C and stores profiles to file
0205 C o flt_down - moves float to its target depth (if flag is set)
0206 C o flt_traj - stores positions and data to file
0207 C o flt_interp_linear - contains blinear interpolation scheme
0208 C o flt_mapping - contains mapping functions & subroutine
0209 C o flt_mdsreadvector - modified mdsreadvector to read files
