Wave Field Amplitudes and Packet Envelopes in WPIT

The wave-amplitude functions in WaveProperties_mod resolve an obliquely propagating whistler-mode wave into its six electromagnetic field components (Bx, By, Bz, Ex, Ey, Ez) in a coordinate system where z is aligned with the background magnetic field B₀. Three normalisation conventions are provided: Bell (1984), which normalises to the By component; Li et al. (2015), which normalises to the total wave magnetic-field amplitude; and Jasna et al. (1992), which normalises to the Poynting flux (power density). The wave-packet functions provide parameterised spatial envelopes (Gaussian or tanh-based) for simulating the latitudinal amplitude profile of magnetospheric wave emissions.

import WPIT.WaveProperties_mod as wave

`wave_amplitudes_bell`

Computes all six wave electromagnetic field components for an obliquely propagating whistler-mode wave using the polarisation relations derived by Bell (1984). The input wave amplitude is specified as the By component; all other components are expressed as ratios relative to By. Reference: Bell, T. F. (1984). The nonlinear gyroresonance interaction between energetic electrons and coherent VLF waves propagating at an arbitrary angle with respect to the Earth’s magnetic field. JGR: Space Physics 89, 905–918.

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_bell(
    mu_arg, P_arg, D_arg, S_arg, Byw_arg, theta_arg
)

Parameters

mu_arg

float

required

Refractive index η (dimensionless). Obtain from refr_index_full, refr_index_appleton, or refr_index_warm.

P_arg

float

required

Stix P parameter (from stix_parameters or stix_parameters_warm).

D_arg

float

required

Stix D parameter.

S_arg

float

required

Stix S parameter.

Byw_arg

float

required

Amplitude of the By wave magnetic field component [T]. This sets the absolute scale of all returned field components.

theta_arg

float

required

Wave normal angle θ with respect to B₀ [rad].

Returns

Bxw_arg

float

Bx component of the wave magnetic field [T].

Byw_arg

float

By component of the wave magnetic field [T]. Equal to the input Byw_arg.

Bzw_arg

float

Bz component of the wave magnetic field [T].

Exw_arg

float

Ex component of the wave electric field [V m⁻¹].

Eyw_arg

float

Ey component of the wave electric field [V m⁻¹].

Ezw_arg

float

Ez component of the wave electric field [V m⁻¹].

In all component formulae, f1 = P − η² sin²θ. The polarisation ratios diverge when S = η² (wave at Buchsbaum resonance) or P = 0 (upper hybrid resonance); avoid these limits.

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w     = 2 * np.pi * 5e3
theta = np.deg2rad(20)
By0   = 1e-10                   # 100 pT

# Compute Stix parameters and refractive index first
S, D, P, R, L = wave.stix_parameters(w, 1e7, 0.9e7, 0.05e7, 0.05e7, 3e-5)
_, _, eta, *_ = wave.refr_index_full(theta, w, S, P, R, L)

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_bell(eta, P, D, S, By0, theta)

print(f"Bx = {Bx:.4e} T,  By = {By:.4e} T,  Bz = {Bz:.4e} T")
print(f"Ex = {Ex:.4e} V/m, Ey = {Ey:.4e} V/m, Ez = {Ez:.4e} V/m")

`wave_amplitudes_li`

Computes the six wave electromagnetic field components using the normalisation convention of Li et al. (2015), where the amplitude is set by the total wave magnetic field magnitude |B_w|. An intermediate normalisation factor I_w is derived from |B_w| and the Stix parameters, ensuring that sqrt(Bx² + By² + Bz²) = |B_w| by construction. Reference: Li, J., Bortnik, J., Xie, L., Pu, Z., Chen, L., Ni, B., et al. (2015). Comparison of formulas for resonant interactions between energetic electrons and oblique whistler-mode waves. Physics of Plasmas 22, 052902.

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_li(
    mu, P, D, S, Bw_tot_li, psi
)

Parameters

float

required

Refractive index η (dimensionless).

float

required

Stix P parameter.

float

required

Stix D parameter.

float

required

Stix S parameter.

Bw_tot_li

float

required

Total wave magnetic field magnitude |B_w| [T]. This is the observationally reported amplitude that satellite instruments typically measure.

psi

float

required

Wave normal angle ψ with respect to B₀ [rad].

Returns

Bxw_li

float

Bx component [T].

Byw_li

float

By component [T].

Bzw_li

float

Bz component [T].

Exw_li

float

Ex component [V m⁻¹].

Eyw_li

float

Ey component [V m⁻¹].

Ezw_li

float

Ez component [V m⁻¹].

The Li et al. convention is preferred when comparing with in-situ satellite observations that report the root-mean-square magnetic fluctuation amplitude. The normalisation factor I_w is derived internally and should not be confused with wave intensity.

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w       = 2 * np.pi * 5e3
psi     = np.deg2rad(25)
Bw_tot  = 3e-10                 # 300 pT total amplitude

S, D, P, R, L = wave.stix_parameters(w, 1e7, 0.9e7, 0.05e7, 0.05e7, 3e-5)
_, _, eta, *_ = wave.refr_index_full(psi, w, S, P, R, L)

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_li(eta, P, D, S, Bw_tot, psi)

B_mag = np.sqrt(Bx**2 + By**2 + Bz**2)
print(f"|B| = {B_mag:.4e} T  (should equal {Bw_tot:.4e} T)")

`wave_amplitudes_jasna`

Computes the six wave electromagnetic field components using the Jasna et al. (1992) normalisation, where the wave amplitude is set by the Poynting flux (power density) power_arg in mW m⁻². The function first derives the By amplitude from the Poynting flux expression, then applies Bell (1984) polarisation ratios internally. Reference: Jasna, D., Inan, U. S., and Bell, T. F. (1992). Precipitation of suprathermal (100 eV) electrons by oblique whistler waves. Geophysical Research Letters 19, 1639–1642.

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_jasna(
    P_arg, S_arg, D_arg, theta_arg, ref_arg, power_arg
)

Parameters

P_arg

float

required

Stix P parameter.

S_arg

float

required

Stix S parameter.

D_arg

float

required

Stix D parameter.

theta_arg

float

required

Wave normal angle θ with respect to B₀ [rad].

ref_arg

float

required

Refractive index η (dimensionless).

power_arg

float

required

Wave Poynting flux (power density) [mW m⁻²]. Values from global VLF propagation models are typically in the range 10⁻⁴ – 10⁻¹ mW m⁻².

Returns

Bxw_arg

float

Bx component of the wave magnetic field [T].

Byw_arg

float

By component of the wave magnetic field [T]. Derived from the Poynting-flux normalisation.

Bzw_arg

float

Bz component of the wave magnetic field [T].

Exw_arg

float

Ex component of the wave electric field [V m⁻¹].

Eyw_arg

float

Ey component of the wave electric field [V m⁻¹].

Ezw_arg

float

Ez component of the wave electric field [V m⁻¹].

The Jasna convention is well suited for global VLF propagation models that output Poynting flux rather than field amplitude. The intermediate variable Byw_sq is computed from the Poynting flux using the Xstix factor and polarisation ratio rho2, then passed to Bell (1984) relations to obtain the remaining components.

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w      = 2 * np.pi * 5e3
theta  = np.deg2rad(15)
power  = 1e-3                    # 1e-3 mW m^-2

S, D, P, R, L = wave.stix_parameters(w, 1e7, 0.9e7, 0.05e7, 0.05e7, 3e-5)
_, _, eta, *_ = wave.refr_index_full(theta, w, S, P, R, L)

Bx, By, Bz, Ex, Ey, Ez = wave.wave_amplitudes_jasna(
    P, S, D, theta, eta, power
)
print(f"By = {By:.4e} T from {power} mW/m^2 Poynting flux")

`wave_packet_gauss`

Returns the wave magnetic field amplitude at a given magnetic latitude by modulating the peak amplitude Bw0_arg with a Gaussian envelope centred on the magnetic equator (λ = 0). This is a standard parameterisation for chorus and whistler-mode wave packets near the equator.

Bwave = wave.wave_packet_gauss(Bw0_arg, lamda_arg, lamda_range)

Parameters

Bw0_arg

float

required

Peak (equatorial) wave magnetic field amplitude [T].

lamda_arg

float

required

Magnetic latitude λ at the point of interest [rad].

lamda_range

float

required

Characteristic half-width of the Gaussian envelope [rad]. The amplitude falls to 1/e of the peak at |λ| = lamda_range.

Returns

Bwave

float

Wave magnetic field amplitude at latitude λ [T]. Bwave = Bw0 * exp(−λ² / λ_range²)

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

Bw0         = 1e-9                      # 1 nT peak
lamda_range = np.deg2rad(5)             # 5° half-width
latitudes   = np.deg2rad(np.linspace(-20, 20, 200))

Bwave = np.array([
    wave.wave_packet_gauss(Bw0, lat, lamda_range) for lat in latitudes
])

import matplotlib.pyplot as plt
plt.plot(np.rad2deg(latitudes), Bwave * 1e9)
plt.xlabel("Magnetic latitude (°)")
plt.ylabel("B_wave (nT)")
plt.title("Gaussian wave packet")
plt.show()

`wave_packet_one_sided`

Returns the wave amplitude modulated by a one-sided hyperbolic-tangent (tanh) envelope, producing a profile that rises from near zero and approaches the peak amplitude Bw0_arg in either the northern or southern hemisphere. This represents a wave packet that is spatially confined to one hemisphere.

Bwave = wave.wave_packet_one_sided(Bw0_arg, lamda_arg, shape, location, direction)

Parameters

Bw0_arg

float

required

Maximum (plateau) wave magnetic field amplitude [T].

lamda_arg

float

required

Magnetic latitude at the point of interest [rad].

shape

float

required

Controls the steepness of the envelope edge. Higher values produce sharper transitions. Dimensionless; typical values: 1–10.

location

float

required

Latitude of the half-maximum point [degrees]. The envelope reaches 50% of its plateau at this latitude.

direction

str

required

Hemisphere of propagation. Must be "north" (packet active at northern latitudes) or "south" (packet active at southern latitudes).

Returns

Bwave

float

Wave magnetic field amplitude at latitude λ [T]. Computed as Bw0 * (tanh(dir * shape * rad2deg(λ) − 2 * location) + 1) / 2 where dir is +1 for north and −1 for south.

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

Bw0       = 1e-9                         # 1 nT
latitudes = np.deg2rad(np.linspace(0, 30, 200))

Bwave_N = np.array([
    wave.wave_packet_one_sided(Bw0, lat, shape=3, location=10, direction='north')
    for lat in latitudes
])

The location parameter is in degrees even though lamda_arg is in radians. The function converts lamda_arg to degrees internally via np.rad2deg before applying the tanh formula.

`wave_packet_two_sided`

Returns the wave amplitude modulated by a symmetric two-sided tanh envelope that is peaked near the equator and rolls off towards both hemispheres. This models a wave packet active near the magnetic equator with a well-defined latitudinal extent.

Bwave = wave.wave_packet_two_sided(Bw0_arg, lamda_arg, shape, location)

Parameters

Bw0_arg

float

required

Equatorial (peak) wave magnetic field amplitude [T].

lamda_arg

float

required

Magnetic latitude at the point of interest [rad].

shape

float

required

Controls steepness of the roll-off. Higher values produce sharper packet edges. Dimensionless.

location

float

required

Latitude of the half-maximum point [degrees].

Returns

Bwave

float

Wave magnetic field amplitude at latitude λ [T]. The envelope is symmetric about the equator: for λ less than 0 the southern tanh roll-off is applied; for λ greater than or equal to 0 the northern roll-off is applied, both anchored at location degrees.

Example

import WPIT.WaveProperties_mod as wave
import numpy as np

Bw0       = 1e-9
latitudes = np.deg2rad(np.linspace(-20, 20, 400))

Bwave_2s = np.array([
    wave.wave_packet_two_sided(Bw0, lat, shape=4, location=8)
    for lat in latitudes
])

Unlike wave_packet_gauss, the two-sided tanh envelope has a flat top near the equator for small location values. Increase shape to steepen the edges and decrease location to narrow the packet.

Environment Module

Wave Properties Module

WPI Module

Landau Damping Module

Wave Field Amplitudes and Packet Envelopes in WPIT

`wave_amplitudes_bell`

Parameters

Returns

Example

`wave_amplitudes_li`

Parameters

Returns

Example

`wave_amplitudes_jasna`

Parameters

Returns

Example

`wave_packet_gauss`

Parameters

Returns

Example

`wave_packet_one_sided`

Parameters

Returns

Example

`wave_packet_two_sided`

Parameters

Returns

Example

Build docs developers (and LLMs) love

Environment Module

Wave Properties Module

WPI Module

Landau Damping Module

Documentation Index

​wave_amplitudes_bell

​Parameters

​Returns

​Example

​wave_amplitudes_li

​Parameters

​Returns

​Example

​wave_amplitudes_jasna

​Parameters

​Returns

​Example

​wave_packet_gauss

​Parameters

​Returns

​Example

​wave_packet_one_sided

​Parameters

​Returns

​Example

​wave_packet_two_sided

​Parameters

​Returns

​Example

Build docs developers (and LLMs) love

`wave_amplitudes_bell`

Parameters

Returns

Example

`wave_amplitudes_li`

Parameters

Returns

Example

`wave_amplitudes_jasna`

Parameters

Returns

Example

`wave_packet_gauss`

Parameters

Returns

Example

`wave_packet_one_sided`

Parameters

Returns

Example

`wave_packet_two_sided`

Parameters

Returns

Example