PlasmaWaves.jl

PlasmaWaves

Plasma wave analysis.

Functions

• Wave polarization analysis: twavpol, twavpol_svd, including calculating the degree of polarization, wave normal angle, helicity, ellipticity, and planarity metrics.

PlasmaWaves

Plasma wave analysis.

Functions

• Wave polarization analysis: twavpol, twavpol_svd, including calculating the degree of polarization, wave normal angle, helicity, ellipticity, and planarity metrics.

Stokes Parameters

Set of values that describe the polarization state of electromagnetic radiation

• Wikipedia

Phase factor exp (i φ) satisfies the following equation

$\exp (4 i φ) = \exp (-2 i γ)$

where

$γ = \arctan (2 Re(𝐮)^𝐓 Im(𝐮) /(Re(𝐮)^2-Im(𝐮)^2))$

polarization(S0, S1, S2, S3)
polarization(S::StokesParameters)

Compute the degree of polarization (p) from Stoke parameters or a Stokes vector.

Reference

• Wikipedia
• Stokes parameters

polarization(S)

Compute the degree of polarization (DOP) p^2 from spectral matrix S.

\[\begin{aligned} p^2 &= 1-\frac{(tr 𝐒)^2-(tr 𝐒^2)}{(tr 𝐒)^2-n^{-1}(tr 𝐒)^2} \\ &= \frac{n(tr 𝐒^2)-(tr 𝐒)^2}{(n-1)(tr 𝐒)^2} \end{aligned}\]

smooth_spectral_matrix!(S_smooth, S, aa)

In-place version of smooth_spectral_matrix that writes results to a pre-allocated array.

spectral_matrix(X, dim = 1)

Compute the spectral matrix $S(f)$ given the time series data X along dimension dim.

Returns a 3-D array of size $n, n, N_{freq}$, where $N_{freq} = \lfloor N/2 \rfloor$ and n is the dimensionality (number of components).

spectral_matrix(Xf)

Compute the spectral matrix $S$ defined by

\[S_{ij}(f) = X_i(f) X_j^*(f),\]

where $X_i(f)$=Xf[f, i] is the FFT of the $i$-th component and $*$ denotes complex conjugation.

twavpol(X; fs = nothing, nfft = 256, noverlap = div(nfft, 2))

Polarization analysis of time series data X (each column is a component) of sampling frequency fs.

If fs is not provided, it will be inferred from the times dimension of X.

See wavpol for details.

twavpol_svd(X; fs = nothing, nfft = 256, noverlap = div(nfft, 2))

Polarization analysis of time series data X (each column is a component) of sampling frequency fs, using singular value decomposition (SVD) method.

Wave normal angle is the angle between (wnx, wny) and the vertical |wnz| Use the imaginary parts of off-diagonals. Define:$A = Im(S₁₂), B = Im(S₁₃), C = Im(S₂₃)$

wavpol(X, fs=1; nfft=256, noverlap=div(nfft, 2), smooth_t=_smooth_t(nfft), smooth_f=_hamming3())

Perform polarization analysis of n-component time series data X (each column is a component) of sampling frequency fs.

For each FFT window (with specified overlap), the routine:

1. Applies a time-domain window function and computes the FFT to construct the spectral matrix $S(f)$
2. Applies frequency smoothing using a window function
3. Computes wave parameters: power, degree of polarization, wave normal angle, ellipticity, and helicity

The analysis assumes the data are in a right-handed, field-aligned coordinate system (with Z along the ambient magnetic field).

Keywords

• nfft: Number of points for FFT (default: 256)
• noverlap: Number of overlapping points between windows (default: nfft÷2)
• smooth_t: Time domain window function (default: Hann window)
• smooth_f: Frequency domain smoothing window (default: 3-point Hamming window)

Returns

A named tuple containing:

• indices: Time indices for each FFT window
• freqs: Frequency array
• power: Power spectral density, normalized by frequency bin width and window function
• degpol: Degree of polarization [0,1]
• waveangle: Wave normal angle [0,π/2]
• ellipticity: Wave ellipticity [-1,1], negative for left-hand polarized
• helicity: Wave helicity

Notes

• smooth_f is needed because otherwise the rank of the spectral matrix $S̃(f)$ is 1, yielding a constant (fully polarized) result $degpol(f) = 1$. Frequency smoothing introduces ensemble averaging, corresponding to different realizations, so $S̃(f)$ gains fuller rank.
• The cross-spectral density matrix $S(f)$ is the Fourier transform of $R(τ) = <X(t) X(t+τ)^†>$ (Wiener-Khinchin theorem).

See also: polarization, wave_normal_angle, wpol_helicity

wpol_helicity(S, waveangle)

Compute helicity and ellipticity for a single frequency.

Arguments

• S: Spectral matrix for a single frequency, size (3,3)
• waveangle: Wave normal angle for this frequency

Returns

• helicity: Average helicity across the three components
• ellipticity: Average ellipticity across the three components