Directory Listing of Routines

ssl_general/cotrans/special

TCROSSP
TDOTP
TINTERPOL_MXN
TNORMALIZE
TVECTOR_ROTATE

Routine Descriptions

TCROSSP

PROCEDURE: TCROSSP
Purpose:
  Vectorized routine to calculate the cross product of two tplot
  variables containing arrays of 3d vectors and storing the result
  in a tplot variable.  Also, can perform vectorized cross product on
  arrays.

Arguments: 
 v1: The name of the tplot variable  or an Nx3 length array storing the first vector in the cross product
    
 v2: The name of the tplot variable or an Nx3 length array storing the second vector in the
     cross product 
 
 newname(optional): the name of the output tplot variable

 error(optional): named variable in which to return error state of
 the computation.  1 = success 0 = failure
 
 diff_tsize_ok = if set, allows the arrays to have a different number
                 of elements in time, uses data_cut, which
                 interpolates the data in v2 to the number of times
                 given by v1
 Outputs(optional):
   out:
     Returns output in array format, if this argument is present, no tplot variable will be created
 
NOTES:

(See ssl_general/cotrans/special/tcrossp.pro)

TDOTP

[Previous Routine] [Next Routine] [List of Routines]

PROCEDURE: TDOTP
Purpose:
  Vectorized routine to calculate the dot product of two tplot
  variables containing arrays of vectors and storing the results
  in a tplot variable

Arguments: 
 v1: The name of the tplot variable storing the first vector in the dot product
 v2: The name of the tplot variable storing the second vector in the
 dot product
 
 newname(optional): the name of the output tplot variable

 error(optional): named variable in which to return the error state
 of the computation.  1 = success 0 = failure

NOTES:

(See ssl_general/cotrans/special/tdotp.pro)

TINTERPOL_MXN

[Previous Routine] [Next Routine] [List of Routines]

Function: tinterpol_mxn

Purpose:
  Performs interpolation on tplot variables.
Interpolates xv_tvar to match uz_tvar.  Can also interpolate with non-tvar types
and return non-tvar types. (Helpful for interpolating matrices and time-series vectors)

This function works on any n or nxm dimensional vectors. Interpolation always occurs along first dimension(time)

              
Arguments:
            xv_tvar = tplot variable to be interpolated, the y component
            can have any dimesions, can use globbing to interpolate
            many values at once
            uses x component for x abcissa values
            Can also pass in a struct with the same format as the 
            data component for a tplot variable:
            {x:time_array,y:data_array,v:optional_y_axis_abcissas}
            
            uz_tvar = tplot variable that V will be fit to
            uses x component for u abcissa values.  Can also
            pass in an array of time values rather than a tplot 
            variable.
            
            newname = output tplot variable name(optional) defaults to
            xv_tvar+'_interp'.  If you want vector output, use the keyword "out"
            
            suffix = a suffix other than interp you can use,
            particularily useful when using globbing
            
            overwrite=set this variable if you just want
            the original variable overwritten instead of using
            newname or suffix

            Use only newname or suffix or overwrite. If you combine
            them the naming behavior may be erratic

            /LINEAR = pass this argument to specify linear
            interpolation(this is the default behavior)
            
            /QUADRATIC = pass this argument to specify quadratic
            interpolation
            
            /SPLINE = pass this argument to specify spline
            interpolation
            
            /NEAREST_NEIGBOR = pass this argument to specify repeat
            nearest neighbor 'interpolation' 
            
            /NO_EXTRAPOLATE = pass this argument to prevent
            extrapolation of data values in V passed it's start and
            end points
            
            /NAN_EXTRAPOLATE = pass this argument to extrapolate past
            the endpoints using NaNs as a fill value

            ERROR(optional): named variable in which to return the error state
            of the computation.  1 = success 0 = failure

Outputs(optional):
   out:
     Returns output as a data struct. If this argument is present, no tplot variable will be created.
     Note that only one result can be returned through this keyword.(ie You can't use this keyword with tplot name-globbing)  

CALLING SEQUENCE;
           tinterpol_mxn,'tplot_var1','tplot_var2',out_var='tplot_var_out'
           tinterpol_mxn,'tplot_var1','tplot_var2',/NO_EXTRAPOLATE
           tinterpol_mxn,'tplot_var1','tplot_var2',/SPLINE
           tinterpol_mxn,'tplot_var1','tplot_var2',out=out_data_struct ;doesn't create tplot variable, instead returns struct
           tinterpol_mxn,'tplot_var1',time_array ;This calling method doesn't require second tplot variable
           tinterpol_mxn,{x:time_array,y:data_array},'tplot_var2' ;This calling method doesn't require first tplot variable
           tinterpol_mxn,{x:time_array,y:data_array,v:y_scale_vals},time_array,out=out_data_struct ; You can mix and match calling types. This calling method doesn't use any tplot variables
         
Output: an N by D1 by D2 by ... array stored in an output tplot variabel

Notes: 
Uses a for loop over D1*D2*..., but I'm operating under the assumption that
D1*D2... << M (D1 * D2 *... is waaaay less than M)

It uses a little bit of modular arithmatic so this function is
generalized to any array dimensionality(IDL limits at 8)

Examples:
 if the input is an array of 3-d vectors(say 1,1,1 and 2,2,2) and we
 want 3 vectors out the output is 1,1,1 1.5 1.5 1.5 2,2,2
 if the input is an array of 3x3 matrices(say all ones and all twos) 
 and we want three matrices then output is all 1s all 1.5s all 2s 
 

 $LastChangedBy: aaflores $
 $LastChangedDate: 2012-01-26 16:53:10 -0800 (Thu, 26 Jan 2012) $
 $LastChangedRevision: 9628 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_7_00/cotrans/special/tinterpol_mxn.pro $

(See ssl_general/cotrans/special/tinterpol_mxn.pro)

TNORMALIZE

[Previous Routine] [Next Routine] [List of Routines]

PROCEDURE: TNORMALIZE
Purpose:
  Vectorized routine to normalize all the vectors stored in a tplot
  variable


Arguments: 
 v: The name or number of the tplot variable storing the vectors to be
 normalized, or an array of vectors to be normalized.  NOTE, if the input is
 not a tplot variable, this routine will not generate a tplot variable for output
 newname(optional): The name of the output tplot variable. Defaults
 to v+'_normalized'
 error(optional): Named variable in which to return the error state
 of the computation, 1 = success, 0 = failure
 out(optional):  If set to a named variable, the output will be stored
              in out, rather than a tplot variable.
 

NOTES:

 $LastChangedBy: aaflores $
 $LastChangedDate: 2012-01-23 16:21:34 -0800 (Mon, 23 Jan 2012) $
 $LastChangedRevision: 9592 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_7_00/cotrans/special/tnormalize.pro $

(See ssl_general/cotrans/special/tnormalize.pro)

TVECTOR_ROTATE

[Previous Routine] [List of Routines]

Procedure: tvector_rotate

Purpose: rotates a set of vectors 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

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 vectors 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.
Vector data can be input as well and should be an Mx3x3 array

vec_var_in: the name of the tplot variable storing 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. Vector data can also be input and
should also 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 vector 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 vector 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: pcruce $
$LastChangedDate: 2012-03-06 11:35:40 -0800 (Tue, 06 Mar 2012) $
$LastChangedRevision: 9956 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/tags/tdas_7_00/cotrans/special/tvector_rotate.pro $

(See ssl_general/cotrans/special/tvector_rotate.pro)