This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# general/cotrans/special

- MATRIX_ARRAY_LIB
- TCROSSP
- TDOTP
- TINTERPOL_MXN
- TNORMALIZE
- TTENSOR_ROTATE
  Wrapper for tvector_rotate, to allow rotation of pressure and
- TVECTOR_ROTATE

# Routine Descriptions

## MATRIX_ARRAY_LIB

[Next Routine] [List of Routines]

     matrix_array_lib

     Helpful functions for dealing with arrays of 3x3 matrixes (Nx3x3)

     $LastChangedBy: aaflores $
     $LastChangedDate: 2016-04-29 17:15:55 -0700 (Fri, 29 Apr 2016) $
     $LastChangedRevision: 20987 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/cotrans/special/matrix_array_lib.pro $

(See general/cotrans/special/matrix_array_lib.pro)

## TCROSSP

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

    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
     multiplier: scale factor to multiply by
     Outputs(optional):
       out:
         Returns output in array format, if this argument is present, no tplot variable will be created

     Example:
       TPLOT;
         tcrossp,'tvarname1','tvarname2'
       Array:
         tcrossp,array_2d_1,array_2d_2,out=array_output

    NOTES:

(See 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 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(source) = 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(target) = 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 = set this keyword to specify linear
                interpolation(this is the default behavior)

                /QUADRATIC = set this keyword to specify quadratic
                interpolation

                /SPLINE = set this keyword to specify spline
                interpolation

                /NEAREST_NEIGHBOR = set this keyowrd to specify repeat
                nearest neighbor 'interpolation'

                /NO_EXTRAPOLATE = set this keyword to prevent
                extrapolation of data values in V passed it's start and
                end points

                /NAN_EXTRAPOLATE = set this keyword to extrapolate past
                the endpoints using NaNs as a fill value

                /REPEAT_EXTRAPOLATE = set this keyword to repeat first and last finite data value past the endpoints

                /IGNORE_NANS = set this keyword to remove nans in the data before interpolation

                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',newname='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: nikos $
     $LastChangedDate: 2021-08-06 11:54:27 -0700 (Fri, 06 Aug 2021) $
     $LastChangedRevision: 30180 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/cotrans/special/tinterpol_mxn.pro $

(See 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/spdsoft/trunk/general/cotrans/special/tnormalize.pro $

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

## TTENSOR_ROTATE

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

    NAME:
     ttensor_rotate
    PURPOSE:
     Wrapper for tvector_rotate, to allow rotation of pressure and
     momentum flux tensors defined as ntimes, 6 arrays
     CALLING SQEUENCE: (same as tvector_rotate)
      Using tplot variables:
        ttensor_rotate, 'matrix_var', 'tensor_var' [,newname='out_var']
                        [,invert=invert] [,suffix=suffix] [,error=error]
                        [,/vector_skip_nonmonotonic]
                        [,/matrix_skip_nonmonotonic]

    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.
     tens_var_in: The name of tplot variable(s) storing a pressure or mf tensor
                  The y component of the tplot variable's data
                  struct should be an Nx6 array.
     newname(optional): the name of the output variable, defaults to
                        tens_var_in + '_rot'
                        Newname should only be used if a single tensor
                        variable is rotated
     suffix: The suffix to be appended to the tplot variable(s)
             (Default: '_rot')
     error(optional): named variable in which to return the error state
     of the computation.  1 = success 0 = failure
    NOTES: the program will change the input tensor or tplot variable(s)
           to mx3x3 inputs suitable for tvector_rotate and reset at the end
    SEE ALSO:  tvector_rotate.pro, mva_matrix_make.pro,
               fac_matrix_make.pro,rxy_matrix_make
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-02-05 15:58:04 -0800 (Tue, 05 Feb 2019) $
     $LastChangedRevision: 26557 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/cotrans/special/ttensor_rotate.pro $

(See general/cotrans/special/ttensor_rotate.pro)

## TVECTOR_ROTATE

[Previous Routine] [List of Routines]

    Procedure:
      tvector_rotate

    Purpose:
        Rotates array data by a set of coordinate
        transformation matrices and outputs 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,*]))

        If the target is also an array of matrices then it is equivalent to:
          for i=0,n_ele-1 do out[i,*,*] = reform(m[i,*,*]) # reform(v[i,*,*])
        If the target is a tensor, KEYWORD_SET = tensor_rotation
        then it is equivalent to
          for i=0,n_ele-1 do out[i,*,*] = reform(m[i,*,*]) #
            reform(v[i,*,*]) # transpose(reform(m[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.

    CALLING SEQUENCE:
      Using tplot variables:
        tvector_rotate, 'matrix_var', 'vector_var' [,newname='out_var']
                        [,invert=invert] [,suffix=suffix] [,error=error]
                        [,/vector_skip_nonmonotonic]
                        [,/matrix_skip_nonmonotonic]
                        [,/tensor_rotate]

      Using arrays:
        tvector_rotate, matrix_array, vector_array, newname=output_array ...

    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 or tensor 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.
                 The tplot variable may also contain matrices.
                 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 Nx3x3 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.

     tensor_rotate: set if the input is a pressure, or momentum flux
                    tensor, requiring an extra matrix multiplication
    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: jimm $
     $LastChangedDate: 2019-07-24 12:01:53 -0700 (Wed, 24 Jul 2019) $
     $LastChangedRevision: 27496 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/cotrans/special/tvector_rotate.pro $

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