GitHub

Coordinate Systems

This package defines common coordinate systems used in heliophysics and space physics research.

Coordinate Transformations

SPEDAS.rotate — Function
rotate(ts::AbstractMatrix, mat::AbstractMatrix)

Coordinate-aware transformation of vector/matrix by rotation matrix(s) mat(s). Assume ts is a matrix of shape (n, 3).

source

Standard Coordinate Systems

  • GSE (Geocentric Solar Ecliptic)
  • GSM (Geocentric Solar Magnetic)
  • GEI (Geocentric Equatorial Inertial)
  • SM (Solar Magnetic)
  • GEO (Geographic)
  • J2000

More information can be found in the the following links

Implementation Status

Transformations between these coordinate systems are planned but not yet implemented.

Specialized Coordinate Systems

The package also provides transformations for analysis-specific coordinate systems:

Field-Aligned Coordinates (FAC)

A local coordinate system defined relative to the ambient magnetic field direction, useful for studying plasma waves and particle distributions.

SPEDAS.fac_mat — Function
fac_mat(vec::AbstractVector; xref=[1.0, 0.0, 0.0])

Generates a field-aligned coordinate (FAC) transformation matrix for a vector.

Arguments

  • vec: A 3-element vector representing the magnetic field
source

Minimum Variance Analysis (MVA) and Boundary Normal Coordinates (LMN)

A coordinate system derived from the eigenvalues and eigenvectors of the magnetic field variance matrix, commonly used in analyzing current sheets, discontinuities, and wave propagation.

References:

SPEDAS.mva_eigen — Function
mva_eigen(B::AbstractMatrix; sort=(;), check=false) -> F::Eigen

Perform minimum variance analysis, returning Eigen factorization object F which contains the eigenvalues in F.values and the eigenvectors in the columns of the matrix F.vectors.

Set check=true to check the reliability of the result.

The kth eigenvector can be obtained from the slice F.vectors[:, k].

source
SPEDAS.mva — Function
mva(V, B=V; kwargs...)

Rotate a timeseries V into the LMN coordinates based on the reference field B.

Arguments

  • V: The timeseries data to be transformed, where each column represents a component
  • B: The reference field used to determine the minimum variance directions, where each column represents a component

See also: mva_eigen, rotate

source
SPEDAS.check_mva_eigen — Function
check_mva_eigen(F; r=5, verbose=false)

Check the quality of the MVA result.

If λ₁ ≥ λ₂ ≥ λ₃ are 3 eigenvalues of the constructed matrix M, then a good indicator of nice fitting LMN coordinate system should have λ₂ / λ₃ > r.

source

Error estimates for MVA:

SPEDAS.Δφij — Function
Δφij(λᵢ, λⱼ, λ₃, M)

Calculate the phase error between components i and j according to: |Δφᵢⱼ| = |Δφⱼᵢ| = √(λ₃/(M-1) * (λᵢ + λⱼ - λ₃)/(λᵢ - λⱼ)²)

Parameters:

  • λᵢ: eigenvalue i
  • λⱼ: eigenvalue j
  • λ₃: smallest eigenvalue (λ₃)
  • M: number of samples
source
SPEDAS.B_x3_error — Function

Calculate the composite statistical error estimate for ⟨B·x₃⟩: |Δ⟨B·x₃⟩| = √(λ₃/(M-1) + (Δφ₃₂⟨B⟩·x₂)² + (Δφ₃₁⟨B⟩·x₁)²)

Parameters:

  • λ₁, λ₂, λ₃: eigenvalues in descending order
  • M: number of samples
  • B: mean magnetic field vector
  • x₁, x₂, x₃: eigenvectors
source

See also: Comparison with PySPEDAS.

Reference