MagnetoIonic

MagnetoIonic

Tools for magnetoionic wave propagation in a cold, magnetized, collisional plasma such as the ionosphere.

The package computes the complex refractive index of the ordinary (O) and extraordinary (X) modes from the Appleton-Hartree equation (returned as n²), the characteristic plasma and electron gyrofrequencies, and the resulting radio wave absorption. Inputs are accepted either as scalars (field magnitude and wave normal angle) or as vectors (geomagnetic field and wave normal direction), and in either angular frequency (rad s⁻¹) or ordinary frequency (Hz).

Exported functions

• plasma_frequency_rad, plasma_frequency_hz, plasma_frequency_rad_sq, plasma_frequency_hz_sq
• gyrofrequency_rad, gyrofrequency_hz, gyrofrequency_rad_sq, gyrofrequency_hz_sq
• appleton_hartree_rad, appleton_hartree_hz
• radio_absorption_rad, radio_absorption_hz

_appleton_hartree_kernel(X, Y, Z, sinθ, cosθ)

Evaluate the Appleton-Hartree equation from precomputed dimensionless parameters and return the squared refractive indices of the two magnetoionic modes.

Arguments

• X: squared plasma-to-wave frequency ratio ωp²/ω²
• Y: gyro-to-wave frequency ratio ωH/ω
• Z: collision-to-wave frequency ratio ν/ω
• sinθ, cosθ: sine and cosine of the angle between the wave normal and the magnetic field

Returns

• NamedTuple (O, X) of the complex squared refractive indices for the + and - roots of the discriminant, respectively

Notes

• Internal helper; not part of the public API.
• The collision term enters through U = 1 + iZ, so the result is complex and its imaginary part carries the collisional damping.
• YL = Y cosθ and YT = Y sinθ are the longitudinal and transverse components of the magnetoionic Y parameter.
• The O and X fields correspond to the + and - signs of the discriminant. Their identification with the physical ordinary and extraordinary modes is regime-dependent and can interchange across the reflection condition X = 1; callers needing a guaranteed physical labeling should check the regime explicitly.

_magnetoionic_parameters(Ne, ν, B, ω)

Return the dimensionless magnetoionic parameters (X, Y, Z) used by the Appleton-Hartree equation.

Arguments

• Ne: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B: magnetic field strength in T
• ω: wave angular frequency in rad s⁻¹

Returns

• Tuple (X, Y, Z) where
  • X = ωp² / ω² is the squared plasma-to-wave frequency ratio
  • Y = ωH / ω is the gyro-to-wave frequency ratio
  • Z = ν / ω is the collision-to-wave frequency ratio

Notes

• Internal helper; not part of the public API.

appleton_hartree_hz(n_e, ν, B_vec, k, f)

Return the squared index of refraction for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• k: wave normal direction as a 3-vector (need not be normalized)
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This is the ''full'' Appleton-Hartree equation, including collisions and valid for any angle θ.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: equivalent function for rad s⁻¹ input

appleton_hartree_hz(n_e, ν, B_vec, f)

Return the squared index of refraction for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This assumes a vertical wave normal (parallel to the local vertical), so the angle θ is determined solely by the orientation of the magnetic field vector.
• This is the ''full'' Appleton-Hartree equation, including collisions.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: equivalent function for rad s⁻¹ input

appleton_hartree_hz(n_e, ν, B, θ, f)

Return the squared index of refraction for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B: magnetic field strength in T
• θ: angle between the wave normal and the magnetic field in radians
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This is the ''full'' Appleton-Hartree equation, including collisions and valid for any angle θ.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: equivalent function for rad s⁻¹ input

appleton_hartree_rad(n_e, ν, B_vec, k, ω)

Return the squared index of refraction for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• k: wave normal direction as a 3-vector (need not be normalized)
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This is the ''full'' Appleton-Hartree equation, including collisions and valid for any angle θ.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_hz: equivalent function for Hz input

appleton_hartree_rad(n_e, ν, B_vec, ω)

Return the squared index of refraction for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This assumes a vertical wave normal (parallel to the local vertical), so the angle θ is determined solely by the orientation of the magnetic field vector.
• This is the ''full'' Appleton-Hartree equation, including collisions.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_hz: equivalent function for Hz input

appleton_hartree_rad(n_e, ν, B, θ, ω)

Return the squared index of refraction for the O and X modes as calculated using the Appleton-Hartree equation.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B: magnetic field strength in T
• θ: angle between the wave normal and the magnetic field in radians
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the squared indices of refraction for the O and X modes, respectively

Notes

• This is the ''full'' Appleton-Hartree equation, including collisions and valid for any angle θ.
• The squared indices of refraction are returned directly, as they are the natural output of the core calculation.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Appleton1932]: Appleton, E. V. (1932), Wireless studies of the ionosphere, Int. J. Electr. Eng., 71, 642–650.
• [Budden1985]: Budden, K. G. (1985), The propagation of radio waves, Cambridge Univ. Press, Cambridge.
• [Haselgrove1960]: Haselgrove, C. B., and J. Haselgrove (1960), Twisted ray paths in the ionosphere, Proc. Phys. Soc. London, 75, 357–363.
• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_hz: equivalent function for Hz input

field_magnitude_and_angle(B_vec, k)

Return a tuple (|B|, θ) given a geomagnetic field vector and wave normal.

Arguments

• B_vec: geomagnetic field as a 3-vector in Tesla
• k: wave normal direction as a 3-vector (need not be normalized)

Returns

• Tuple (B, θ) where B is magnitude in Tesla and θ is in radians

field_magnitude_and_angle(B_vec)

Return a tuple (|B|, θ) given a geomagnetic field vector and assumed vertical wave normal.

Arguments

• B_vec: geomagnetic field as a 3-vector in Tesla

Returns

• Tuple (B, θ) where B is magnitude in Tesla and θ is in radians

field_magnitude_and_dircos(B_vec, k)

Return (|B|, sinθ, cosθ) given a geomagnetic field vector and wave normal, where θ is the angle between k and B_vec.

Arguments

• B_vec: geomagnetic field as a 3-vector in Tesla
• k: wave normal direction as a 3-vector (need not be normalized)

Returns

• Tuple (B, s, c) where B = |B_vec| in Tesla, s = sinθ, and c = cosθ

Notes

• Computes cosθ directly as a clamped direction cosine and obtains sinθ from √(1 - cos²θ), avoiding an acos/sincos round trip.
• cosθ is clamped to [-1, 1] to guard against floating point excursions when k and B_vec are nearly (anti)parallel.
• sinθ ≥ 0 always, since θ ∈ [0, π].

See Also

• field_magnitude_and_angle: returns (|B|, θ) instead of direction cosines

field_magnitude_and_dircos(B_vec)

Return (|B|, sinθ, cosθ) given a geomagnetic field vector and an assumed vertical wave normal.

Arguments

• B_vec: geomagnetic field as a 3-vector in Tesla

Returns

• Tuple (B, s, c) where B = |B_vec| in Tesla, s = sinθ, and c = cosθ, with θ measured from the local vertical

See Also

• field_magnitude_and_dircos: two-argument form for an explicit wave normal

gyrofrequency_hz(B)

Return the electron gyrofrequency fH in Hz.

Arguments

• B: geomagnetic field magnitude in Tesla, or field vector in Tesla

Returns

• fH in Hz

See Also

• gyrofrequency_rad: equivalent in rad s⁻¹

gyrofrequency_hz_sq(B)

Return the squared electron gyrofrequency fH² in Hz².

Arguments

• B: geomagnetic field magnitude in Tesla, or field vector in Tesla

Returns

• fH² in Hz²

See Also

• gyrofrequency_rad: base calculation in rad s⁻¹
• gyrofrequency_rad_sq: equivalent in rad² s⁻²

gyrofrequency_rad(B_vec)

Return the electron gyrofrequency ωH in rad s⁻¹.

Computes the gyrofrequency from the magnitude of a geomagnetic field vector.

Arguments

• B_vec: geomagnetic field vector in Tesla

Returns

• ωH in rad s⁻¹

gyrofrequency_rad(B)

Return the electron gyrofrequency ωH in rad s⁻¹.

Arguments

• B: geomagnetic field magnitude in Tesla as a scalar

Returns

• ωH in rad s⁻¹

gyrofrequency_rad_sq(B)

Return the squared electron gyrofrequency ωH² in rad² s⁻².

Arguments

• B: geomagnetic field magnitude in Tesla, or field vector in Tesla

Returns

• ωH² in rad² s⁻²

See Also

• gyrofrequency_rad: base calculation in rad s⁻¹
• gyrofrequency_hz_sq: equivalent in Hz²

plasma_frequency_hz(n_e)

Return the plasma frequency fp in Hz.

Computed as sqrt(ωp²) / (2π) to defer the Hz conversion until after the square root.

Arguments

• n_e: electron number density in m⁻³

Returns

• fp in Hz

Notes

The plasma frequency represents the natural oscillation frequency of the electron gas and is a key parameter in the Appleton-Hartree equation. For the D-region ionosphere, typical values range from a few kHz at night to several MHz during daytime solar maximum conditions.

See Also

• plasma_frequency_rad: equivalent in rad s⁻¹
• plasma_frequency_hz_sq: the squared form in Hz²

plasma_frequency_hz_sq(n_e)

Return the squared plasma frequency fp² in Hz².

Computed as ωp² / (4π²) to defer the Hz conversion until after the core rad² s⁻² calculation, minimizing floating point operations.

Arguments

• n_e: electron number density in m⁻³

Returns

• fp² in Hz²

See Also

• plasma_frequency_rad_sq: the primary internal computation
• plasma_frequency_hz: the unsquared form in Hz

plasma_frequency_rad(n_e)

Return the plasma angular frequency ωp in rad s⁻¹.

Arguments

• n_e: electron number density in m⁻³

Returns

• ωp in rad s⁻¹

See Also

• plasma_frequency_rad_sq: the squared form used internally
• plasma_frequency_hz: equivalent in Hz

plasma_frequency_rad_sq(n_e)

Return the squared plasma angular frequency ωp² in rad² s⁻².

Arguments

• n_e: electron number density in m⁻³

Returns

• ωp² in rad² s⁻²

Notes

The plasma frequency is defined as the natural oscillation frequency of the electron gas in the absence of a magnetic field: ωp² = n_e * e² / (m_e * ε₀)

radio_absorption_hz(n_e, ν, B_vec, k, f)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• k: wave normal direction as a 3-vector (need not be normalized)
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• Converts the frequency to angular frequency (ω = 2πf) and forwards to radio_absorption_rad.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• radio_absorption_rad: equivalent function for rad s⁻¹ input
• appleton_hartree_hz: the refractive index this is derived from, including references

radio_absorption_hz(n_e, ν, B_vec, f)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• This assumes a vertical wave normal (parallel to the local vertical), so the angle θ is determined solely by the orientation of the magnetic field vector.
• Converts the frequency to angular frequency (ω = 2πf) and forwards to radio_absorption_rad.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• radio_absorption_rad: equivalent function for rad s⁻¹ input
• appleton_hartree_hz: the refractive index this is derived from, including references

radio_absorption_hz(n_e, ν, B, θ, f)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B: magnetic field strength in T
• θ: angle between the wave normal and the magnetic field in radians
• f: wave frequency in Hz

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• Converts the frequency to angular frequency (ω = 2πf) and forwards to radio_absorption_rad.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• radio_absorption_rad: equivalent function for rad s⁻¹ input
• appleton_hartree_hz: the refractive index this is derived from, including references

radio_absorption_rad(n_e, ν, B_vec, k, ω)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• k: wave normal direction as a 3-vector (need not be normalized)
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• The absorption coefficient describes the spatial decay of wave power, P(z) = P₀ · 10^(-α z / 10) with α in dB m⁻¹.
• It is obtained from the imaginary part of the refractive index n = √(n²), where the squared index n² is returned by the Appleton-Hartree equation, as α = 2 · imag(n) · ω / c, a power absorption coefficient in Np m⁻¹, then converted to dB m⁻¹ via the factor 10 · log₁₀(e).
• Absorption is non-zero when the medium is lossy (collisions present) or the wave is evanescent.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: the refractive index this is derived from, including references
• radio_absorption_hz: equivalent function for Hz input

radio_absorption_rad(n_e, ν, B_vec, ω)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B_vec: magnetic field as a 3-vector in T
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• This assumes a vertical wave normal (parallel to the local vertical), so the angle θ is determined solely by the orientation of the magnetic field vector.
• See the five-argument method for the definition of the absorption coefficient.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: the refractive index this is derived from, including references
• radio_absorption_hz: equivalent function for Hz input

radio_absorption_rad(n_e, ν, B, θ, ω)

Return the power absorption coefficient for the O and X modes.

Arguments

• n_e: electron number density in m⁻³
• ν: effective collision frequency in s⁻¹
• B: magnetic field strength in T
• θ: angle between the wave normal and the magnetic field in radians
• ω: wave angular frequency in rad s⁻¹

Returns

• NamedTuple (O, X) where O and X are the absorption coefficients in dB m⁻¹ for the O and X modes, respectively

Notes

• See the B_vec, k method for the definition of the absorption coefficient.
• See [Zawdie2017] for a detailed discussion on the choice of collision frequency.

References

• [Zawdie2017]: Zawdie, K. A., D. P. Drob, D. E. Siskind, and C. Coker (2017), Calculating the absorption of HF radio waves in the ionosphere, Radio Sci., 52, 767–783, doi:10.1002/2017RS006256.

See Also

• appleton_hartree_rad: the refractive index this is derived from, including references
• radio_absorption_hz: equivalent function for Hz input

vertical_wave_normal_angle(B_vec)

Return θ for vertical incidence propagation given a geomagnetic field vector, i.e. the angle between vertical and B.

Equivalent to the magnetic dip angle measured from vertical rather than from horizontal.

Arguments

• B_vec: geomagnetic field as a 3-vector in any consistent coordinate system where the third component is vertical

Returns

• θ in radians

wave_normal_angle(k, B_vec)

Return the angle θ in radians between wave normal vector k and geomagnetic field vector B.

Arguments

• k: wave normal direction as a 3-vector (need not be normalized)
• B_vec: geomagnetic field as a 3-vector in Tesla

Returns

• θ in radians

Notes

This is clamped at ±1 before applying acos to avoid NaN results from floating point imprecision when k and B_vec are nearly parallel or antiparallel.