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

Last modified: Tue Oct 28 18:16:50 2025.

# Directory Listing of Routines

# general/cotrans/special/fac

- FAC_MATRIX_MAKE

# Routine Descriptions

## FAC_MATRIX_MAKE

[List of Routines]

    Procedure: fac_matrix_make

    Purpose:  generates a field aligned coordinate transformation matrix
    from an input B vector array(and sometimes a position vector array)
    then stores it in a tplot variable

    Arguments:
       mag_var_name=the name of the tplot variable storing the magnetic field
       vectors to be used in transformation matrix generation.  This
       variable must be in gse or gsm coordinates when passed to this procedure.
       pos_var_name(optional)=the name of the tplot variable storing the position
       vectors to be used in transformation matrix generation.  This
       variable must be in gei coordinates when passed to this procedure.
       newname(optional)=the name of the tplot variable in which to store
       the output
       error(optional) = named variable that holds the error state of the
       computation 1 = success 0 = failure
       other_dim(optional) = the second axis for the field aligned
       coordinate system.
       /DEGAP: Set to call TDEGAP to remove any gaps from the data. See TDEGAP for
               for other options that can be invoked using the _extra keyword.
               E.g. thm_fac_matrix_make, 'tha_fgs', other_dim='xgse', /degap, dt=3

       ************For all transformations Z = B************

       Warning about coordinate systems:
       B field tplot variable must be in gse or gsm coordinates,
       depending on what transformation has been selected.
       Position tplot variable must be in gei coordinates. Gei is the default coordinate
       system of thm_load_state.

       Warning:  The resulting transformation matrices will only correctly
       transform data from the coordinate system of the input variable to
       the field aligned coordinate system.  So if mag_var_name is in gse
       coordinates then you should only use the output matrices to transform
       other data in gse coordinates.

       valid second coord(other_dim) options:

             'Xgse', (DEFAULT) translates from gse or gsm into FAC
                        Definition(works on GSE, or GSM):
                        X Axis = on plane defined by Xgse - Z
                        Second coordinate definition: Y = Z x X_gse
                        Third coordinate, X completes orthogonal RHS
                        (right hand system) triad: XYZ
                        Note: X_gse is a unit vector pointing in direction from
                              earth to the sun
             'Rgeo',translate from geo into FAC using radial position vector
                        Rgeo is radial position vector, positive radialy outwards.
                        Second coordinate definition: Y = Z x Rgeo (eastward)
                        Third coordinate, X completes orthogonal RHS XYZ.
             'mRgeo',translate into FAC using radial position vector
                        mRgeo is radial position vector, positive radially inwards.
                        Second coordinate definition: Y = Z x mRgeo (westward)
                        Third coordinate, X completes orthogonal RHS XYZ.
             'Phigeo', translate into FAC using azimuthal position vector
                        Phigeo is the azimuthal geo position vector, positive Eastward
                        First coordinate definition: X = Phigeo x Z (positive outwards)
                        Second coordinate, Y ~ Phigeo (eastward) completes orthogonal RHS XYZ
             'mPhigeo', translate into FAC using azimuthal position vector
                        mPhigeo is minus the azimuthal geo position vector; positive Westward
                        First coordinate definition: X = mPhigeo x Z (positive inwards)
                        Second coordinate, Y ~ mPhigeo (Westward) completes orthogonal RHS XYZ
             'Phism', translate into FAC using azimuthal Solar Magnetospheric vector.
                     Phism is "phi" vector of satellite position in SM coordinates.
                     Y Axis = on plane defined by Phism-Z, normal to Z
                     Second coordinate definition: X = Phism x Z
                     Third completes orthogonal RHS XYZ
             'mPhism', translate into FAC using azimuthal Solar Magnetospheric vector.
                     mPhism is minus "phi" vector of satellite position in SM coordinates.
                     Y Axis = on plane defined by Phism-Z, normal to Z
                     Second coordinate definition: X = mPhism x Z
                     Third completes orthogonal RHS XYZ
             'Ygsm', translate into FAC using cartesian Ygsm position as other dimension.
                     Y Axis on plane defined by Ygsm and Z
                     First coordinate definition: X = Ygsm x Z
                     Third completes orthogonal RHS XYZ
     Example:
      fac_matrix_make,'tha_fgs',other_dim='Xgse',pos_var_name='tha_pos',newname='tha_fgs_fac_mat'

    Notes:

(See general/cotrans/special/fac/fac_matrix_make.pro)