Procedure: tvector_rotate Purpose: rotates array data by a set of coordinate transformation matrices inputs and outputs are tplot variables. This is designed mainly for use with fac_matrix_make.pro and minvar_matrix_make, but can be used for more general purposes ; Assuming that the data array and matrix time-grids match, this code is the vectorized equivalent to: for i=0,n_ele-1 do out[i,*]=reform(reform(m[i,*,*])#reform(v[i,*])) Setting the "invert" keyword will produce results that are equivalent to using the '##' operation in the loop above. Warning: The transformation matrices generated by fac_matrix_make,thm_fac_matrix_make, and minvar_matrix_make are defined relative to a specific coordinate system. This means that if you use vectors in one coordinate system to generate the rotation matrices they will only correctly transform data from that coordinate system into the functional coordinate system. For example if you use magnetic field data in gsm to generate Rgeo transformation matrices using fac_matrix_make then the array being provided to tvector rotate to be transformed by those matrices should only be in gsm coordinates. Arguments: mat_var_in: the name of the tplot variable storing input matrices The y component of the tplot variable's data struct should be an Mx3x3 array, storing a list of transformation matrices. Array data can be input as well and should be an Mx3x3 array vec_var_in: The name of a tplot variable storing an array of input vectors. You can use globbing to rotate several tplot variables storing vectors with a single matrix. The y component of the tplot variable's data struct should be an Nx3 array. Array data can also be input and should be an Nx3 array. newname(optional): the name of the output variable, defaults to vec_var_in + '_rot' If you use type globbing in the vector variable If array data is used this variable should be declared. suffix: The suffix to be appended to the tplot variables that the output matrices will be stored in. (Default: '_rot') error(optional): named variable in which to return the error state of the computation. 1 = success 0 = failure invert(optional): If matrix_var naturally transforms vector_var from Coord A to B, (ie Vb = M#Va where # denotes matrix multiplication) then setting this keyword will transform vector_var from Coord B to A( ie Va = M^T#Vb This is done by transposing the input matrices, as it is a property of rotation matrices that M#M^T = I and M^T#M = I(ie M^T = M^-1) vector_skip_nonmonotonic(optional): Removes any vector data with non-ascending or repeated timestamps before SLERPing matrices rather than throwing an error. matrix_skip_nonmonotonic(optional): Removes any vector data with non-ascending timestamps before SLERPing matrices rather than throwing an error. CALLING SEQUENCE: tvector_rotate,'matrix_var','vector_var',newname = 'out_var',error=error tvector_rotate,'matrix_var','vector_var' Notes: 1. mat_var_in should store rotation or permutation matrices. (ie the columns of any matrix in mat_var_in should form an orthonormal basis) tvector_rotate will test and warn if input matrices are inalid. Permutation matrices are allowed so that coordinates can be transformed from right to left handed systems and vice-versa. This is verified via the following contraints. M#M^-1 = I and abs(determ(m)) = 1 2. transformation matrices generally only transform from one particular basis to another particular basis. Since tvector_rotate as no way to test that vector_var is in the correct basis, you need to be very careful that vector_var has the correct coordinate system and representation so that it can correctly transform the data. 3. If M!=N, then M must be >= 2 (where M,N refer to the dimensions of the input variables.) 4. Also If the x components of mat_var_in and vec_var_in data structs do not match then, the matrices will be interpolated to match the cadence of the data. Interpolation is done by turning the matrices into quaternions and performing spherical linear interpolation. As noted above this interpolation behavior will not be predictable if the matrices do anything other than rotate. 5. If the timestamps of mat_var_in are not monotonic(ascending or identical) or if the timestamps vec_var_in are not strictly monotonic(always ascending) the program will not work correctly in the event that matrix SLERPing is required. Set the keywords vector_skip_nonmonotonic or matrix_skip_nonmonotonic to have the routine remove the non-monotonic data when generating the output. Alternatively, if matrix and vector timestamps match no SLERPing will be required, also fixing nonmonotonicities manually will fix the problem. SEE ALSO: mva_matrix_make.pro, fac_matrix_make.pro,rxy_matrix_make $LastChangedBy: crussell $ $LastChangedDate: 2012-04-13 07:32:55 -0700 (Fri, 13 Apr 2012) $ $LastChangedRevision: 10324 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/cotrans/special/tvector_rotate.pro $