Public Interface

Documentation of LongwaveModePropagator.jl's exported structs and functions.

Contents

Basic Functions

LongwaveModePropagator.propagateFunction
propagate(waveguide::HomogeneousWaveguide, tx::Emitter, rx::AbstractSampler;
          modes::Union{Nothing,Vector{ComplexF64}}=nothing, mesh=nothing,
          params=LMPParams())

Compute electric field E, amplitude, and phase at rx.

Precomputed waveguide modes can optionally be provided as a Vector{ComplexF64}. By default modes are found with findmodes.

If mesh = nothing, use defaultmesh to generate mesh for the mode finding algorithm. This is ignored if modes is not nothing.

source
propagate(waveguide::SegmentedWaveguide, tx::Emitter, rx::AbstractSampler;
          mesh=nothing, params=LMPParams())

Compute electric field E, amplitude, and phase at rx through a SegmentedWaveguide.

If mesh = nothing, use defaultmesh to generate mesh for the mode finding algorithm.

source
propagate(file::AbstractString, outfile=missing; incrementalwrite=false, append=false,
          mesh=nothing)

Run the model scenario described by file and save the results as outfile.

If outfile = missing, the output file name will be $(file)_output.json.

source
LongwaveModePropagator.LMPParamsType
LMPParams{T,T2,H <: AbstractRange{Float64}}

Parameters for the LongwaveModePropagator module with defaults:

  • topheight::Float64 = 110e3: starting height for integration of the ionosphere reflection coefficient.
  • earthradius::Float64 = 6369e3: Earth radius in meters.
  • earthcurvature::Bool = true: toggle inclusion of Earth curvature in calculations. This is not supported by all functions.
  • curvatureheight::Float64 = 50e3: reference height for Earth curvature in meters. At this height, the index of refraction is 1, and is therefore the reference height for eigenangles.
  • approxsusceptibility::Bool = false: use a cubic interpolating spline representation of susceptibility during the integration of dRdz.
  • susceptibilitysplinestep::Float64 = 10.0: altitude step in meters used to build the spline representation of susceptibility if approxsusceptibility == true.
  • grpfparams::GRPFParams = GRPFParams(100000, 1e-5, true): parameters for the GRPF complex root-finding algorithm.
  • integrationparams::IntegrationParams{T} = IntegrationParams(solver=Vern7(), tolerance=1e-5): parameters passed to DifferentialEquations.jl for integration of the ionosphere reflection coefficient.
  • wavefieldheights::H = range(topheight, 0, length=513): heights in meters at which wavefields will be integrated.
  • wavefieldintegrationparams::IntegrationParams{T2} = IntegrationParams(solver=Tsit5(), tolerance=1e-6): parameters passed to DifferentialEquations.jl for integration of the wavefields used in mode conversion. The solver cannot be lazy.

The struct is created using Parameters.jl @with_kw and supports that package's instantiation capabilities, e.g.:

p = LMPParams()
p2 = LMPParams(earth_radius=6370e3)
p3 = LMPParams(p2; grpf_params=GRPFParams(100000, 1e-6, true))

See also: IntegrationParams

source

Mode Finder

LongwaveModePropagator.findmodesFunction
findmodes(modeequation::ModeEquation, mesh=nothing; params=LMPParams())

Find eigenangles associated with modeequation.waveguide within the domain of mesh.

mesh should be an array of complex numbers that make up the original grid over which the GRPF algorithm searches for roots of modeequation. If mesh === nothing, it is computed with defaultmesh.

There is a check for redundant modes that requires modes to be separated by at least 1 orders of magnitude greater than grpfparams.tolerance in real and/or imaginary component. For example, if grpfparams.tolerance = 1e-5, then either the real or imaginary component of each mode must be separated by at least 1e-4 from every other mode.

source
LongwaveModePropagator.PhysicalModeEquationType
PhysicalModeEquation{W<:HomogeneousWaveguide} <: ModeEquation

Parameters for solving the physical mode equation $\det(Rg*R - I)$.

Fields:

- θ::ComplexF64
- frequency::Float64
- waveguide::W
source
LongwaveModePropagator.IntegrationParamsType
IntegrationParams{T}

Parameters passed to OrdinaryDiffEq.jl during the integration of the ionosphere reflection coefficient matrix in modefinder.jl.

Fields

  • tolerance::Float64 = 1e-5: integration atol and rtol.
  • solver::T = Vern7(): a DifferentialEquations.jl solver.
  • dt::Float64 = 1.0: height step in meters (many methods use a variable step size).
  • force_dtmin::Bool = false: if true, continue integration when solver reaches minimum step size.
  • maxiters::Int = 100_000: maximum number of iterations before stopping.
source

EigenAngle

LongwaveModePropagator.attenuationFunction
attenuation(ea, frequency)

Compute attenuation of eigenangle ea at the ground for a wave frequency in Hertz.

This function internally references ea to the ground.

source
LongwaveModePropagator.phasevelocityFunction
phasevelocity(ea; params=LMPParams())

Compute the relative phase velocity $v/c$ associated with the eigenangle ea.

This function internally references θ to the ground.

source

Geophysics

LongwaveModePropagator.BFieldType
BField

Background magnetic field vector of strength B in Tesla with direction cosines dcl, dcm, and dcn corresponding to $x$, $y$, and $z$ directions parallel, perpendicular, and up to the waveguide.

source
LongwaveModePropagator.SpeciesType
Species

Ionosphere constituent Species.

Fields

  • charge::Float64: signed species charged in Coulombs.
  • mass::Float64: species mass in kilograms.
  • numberdensity: a callable that returns number density in number per cubic meter as a function of height in meters.
  • collisionfrequency: a callable that returns the collision frequency in collisions per second as a function of height in meters.
Note

numberdensity and collisionfrequency will be converted to FunctionerWrapper types that tell the compiler that these functions will always return values of type Float64. A limited test is run to check if this is true, but otherwise it is up to the user to ensure these functions return only values of type Float64.

source
LongwaveModePropagator.waitprofileFunction
waitprofile(z, h′, β; cutoff_low=0, threshold=1e12)

Compute the electron number density in electrons per cubic meter at altitude z in meters using Wait's exponential profile [[Wait1964]; [Thomson1993]] with parameters h′ in kilometers and β in inverse kilometers.

The profile is:

\[Nₑ = 1.43 × 10¹³ \exp(-0.15 h') \exp[(β - 0.15)(z/1000 - h')]\]

Optional arguments:

  • cutoff_low=0: when z is below cutoff_low, return zero.
  • threshold=1e12: when density is greater than threshold, return threshold.

See also: electroncollisionfrequency, ioncollisionfrequency

References

[Wait1964]: J. R. Wait and K. P. Spies, “Characteristics of the earth-ionosphere waveguide for VLF radio waves,” U.S. National Bureau of Standards, Boulder, CO, Technical Note 300, Dec. 1964.

[Thomson1993]: N. R. Thomson, “Experimental daytime VLF ionospheric parameters,” Journal of Atmospheric and Terrestrial Physics, vol. 55, no. 2, pp. 173–184, Feb. 1993, doi: 10.1016/0021-9169(93)90122-F.

source
LongwaveModePropagator.electroncollisionfrequencyFunction
electroncollisionfrequency(z)

Compute the electron-neutral collision frequency in collisions per second at height z in meters based on Wait's conductivity profile [[Wait1964]; [Thomson1993]].

The profile is:

\[νₑ(z) = 1.816 × 10¹¹ \exp(-0.15⋅z/1000)\]

See also: waitprofile, ioncollisionfrequency

References

[Wait1964]: J. R. Wait and K. P. Spies, “Characteristics of the earth-ionosphere waveguide for VLF radio waves,” U.S. National Bureau of Standards, Boulder, CO, Technical Note 300, Dec. 1964.

[Thomson1993]: N. R. Thomson, “Experimental daytime VLF ionospheric parameters,” Journal of Atmospheric and Terrestrial Physics, vol. 55, no. 2, pp. 173–184, Feb. 1993, doi: 10.1016/0021-9169(93)90122-F.

source
LongwaveModePropagator.ioncollisionfrequencyFunction
ioncollisionfrequency(z)

Compute the ion-neutral collision frequency in collisions per second at height z in meters from [Morfitt1976].

The profile is:

\[νᵢ(z) = 4.54 × 10⁹ \exp(-0.15⋅z/1000)\]

See also: waitprofile, electroncollisionfrequency

References

[Morfitt1976]: D. G. Morfitt and C. H. Shellman, “‘MODESRCH’, an improved computer program for obtaining ELF/VLF/LF mode constants in an Earth-ionosphere waveguide,” Naval Electronics Laboratory Center, San Diego, CA, NELC/IR-77T, Oct. 1976.

source

Samplers

LongwaveModePropagator.SamplerType
Sampler{T} <: AbstractSampler{T}

Sampler types sample (measure) the electromagnetic field in the waveguide.

Fields

  • distance::T: ground distance from the transmitter in meters.
  • fieldcomponent::Fields.Field: field component measured by the Sampler.
  • altitude::Float64: height above the ground in meters.
source
LongwaveModePropagator.GroundSamplerType
GroundSampler{T} <: AbstractSampler{T}

GroundSamplers are Sampler types with an altitude of zero.

Fields

  • distance::T: ground distance from the transmitter in meters.
  • fieldcomponent::Fields.Field: field component measured by the GroundSampler.
source
LongwaveModePropagator.FieldsModule
Fields

This baremodule allows scoped enum-like access to electric field components Ex, Ey, and Ez.

Examples

julia> Fields.Ex
Ex::Field = 0
julia> Fields.Ey
Ey::Field = 1
source

Emitters

LongwaveModePropagator.TransmitterType
Transmitter{A<:Antenna} <: Emitter

Typical ground-based Transmitter.

Fields

  • name::String: transmitter name.
  • latitude::Float64: transmitter geographic latitude in degrees.
  • longitude::Float64: transmitter geographic longitude in degrees.
  • antenna::Antenna: transmitter antenna.
  • frequency: transmitter frequency in Hertz.
  • power::Float64: transmit power in Watts.
source

Waveguides

LongwaveModePropagator.HomogeneousWaveguideType
HomogeneousWaveguide{S} <: Waveguide

Defines a homogeneous segment of waveguide.

Fields

  • bfield::BField: background magnetic field.
  • species::S: ionosphere constituents.
  • ground::Ground: waveguide ground.
  • distance::Float64: distance from the Emitter at the start of the segment in meters.
source

IO

Missing docstring.

Missing docstring for BasicInput. Check Documenter's build log for details.

LongwaveModePropagator.TableInputType
TableInput <: Input

Fields

  • name::String
  • description::String
  • datetime::DateTime
  • segment_ranges::Vector{Float64}: distance from transmitter to the beginning of each HomogeneousWaveguide segment in meters.
  • altitude::Vector{Float64}: altitude above ground in meters for which the density and collision_frequency profiles are specified.
  • density::Vector{Float64}: electron density at each altitude in $m⁻³$.
  • collision_frequency::Vector{Float64}: electron-ion collision frequency at each altitude in $s⁻¹$.
  • b_dips::Vector{Float64}: magnetic field dip angles in radians for each HomogeneousWaveguide segment.
  • b_azs::Vector{Float64}: magnetic field azimuth in radians "east" of the propagation direction for each HomogeneousWaveguide segment.
  • ground_sigmas::Vector{Float64}: ground conductivity in Siemens per meter for each HomogeneousWaveguide segment.
  • ground_epsrs::Vector{Int}: ground relative permittivity for each HomogeneousWaveguide segment.
  • frequency::Float64: transmitter frequency in Hertz.
  • output_ranges::Vector{Float64}: distances from the transmitter at which the field will be calculated.
source
LongwaveModePropagator.BasicOutputType
BasicOutput <: Output

Fields

  • name::String
  • description::String
  • datetime::DateTime
  • output_ranges::Vector{Float64}
  • amplitude::Vector{Float64}
  • phase::Vector{Float64}
source