Input Flux API

AbstractSpectrum

Abstract supertype for all electron energy spectrum shapes.

Concrete subtypes: FlatSpectrum, GaussianSpectrum, MaxwellianSpectrum, FileSpectrum.

FlatSpectrum(IeE_tot; E_min=0.0)

Flat (constant) differential number flux spectrum above a minimum energy.

The flux is uniform in #e⁻/m²/s/eV for energies above E_min, and zero below. Normalized so that the integrated field-aligned (vertical) energy flux equals IeE_tot.

Arguments

• IeE_tot: total field-aligned (vertical) energy flux (W/m²), i.e. the energy flux crossing the horizontal top boundary.

Keyword Arguments

• E_min=0.0: minimum energy threshold (eV). Flux is zero below this energy.

Examples

FlatSpectrum(1e-2)                  # flat from lowest energy
FlatSpectrum(1e-2; E_min=2900.0)    # flat above 2900 eV

GaussianSpectrum(IeE_tot, E₀, ΔE)

Gaussian energy spectrum centered at E₀ with width ΔE.

The spectral shape is Φ(E) ∝ exp(-(E - E₀)² / ΔE²), normalized so that the integrated field-aligned (vertical) energy flux equals IeE_tot.

Arguments

• IeE_tot: total field-aligned (vertical) energy flux (W/m²), i.e. the energy flux crossing the horizontal top boundary.
• E₀: center energy (eV)
• ΔE: energy width (eV)

Examples

GaussianSpectrum(1e-2, 5000.0, 500.0)

MaxwellianSpectrum(IeE_tot, E₀; low_energy_tail=true)

Maxwellian energy spectrum with optional low-energy tail (LET).

Based on the corrected implementation of Meier/Strickland/Hecht/Christensen JGR 1989 (pages 13541-13552).

Arguments

• IeE_tot: total field-aligned (vertical) energy flux (W/m²), i.e. the energy flux crossing the horizontal top boundary.
• E₀: characteristic energy (eV)

Keyword Arguments

• low_energy_tail=true: include a low-energy tail following Meier et al. 1989

Examples

MaxwellianSpectrum(1e-2, 1000.0)
MaxwellianSpectrum(1e-2, 1000.0; low_energy_tail=false)

FileSpectrum(filename; interpolation=:constant)

Energy spectrum loaded from a .mat file.

The file contains the complete flux distribution (possibly time-dependent). When used inside an InputFlux, this spectrum type requires ConstantModulation because the file already contains the full temporal behavior.

Arguments

• filename: path to the .mat file containing the flux data

Keyword Arguments

• interpolation=:constant: interpolation scheme for resampling the file's time grid. Either :constant, :linear, or :pchip.

File format

The .mat file must contain:

• Ie_total: flux array of shape [n_μ, n_t_file, n_E]
• t_top: time grid (s), as a vector [n_t_file]. Optional when n_t_file == 1.

Examples

FileSpectrum("path/to/flux.mat")
FileSpectrum("path/to/flux.mat"; interpolation=:linear)

evaluate_spectrum(spec::AbstractSpectrum, model::AuroraModel)

Evaluate the energy spectrum on the model's energy grid, returning a vector of differential number flux per eV (#e⁻/m²/s/eV) of length n_E.

This function does not distribute over beams or apply temporal modulation. Use compute_flux for the full 3D flux array.

AbstractModulation

Abstract supertype for all temporal modulation types.

Concrete subtypes: ConstantModulation, SinusoidalFlickering, SquareFlickering, SmoothOnset.

ConstantModulation()

No temporal modulation — the flux is constant in time.

Used as the default modulation for steady-state simulations and for file-based input where the time dependence is already contained in the file.

SinusoidalFlickering(f; amplitude=1.0)

Sinusoidal temporal modulation of the electron flux.

The flux oscillates between (1 - amplitude) and 1 of the base flux, using the pattern 1 - cos²(πft). With amplitude=1.0, the flux modulates fully between 0 and 1.

Arguments

• f: modulation frequency (Hz)

Keyword Arguments

• amplitude=1.0: modulation depth. 0 = constant flux, 1 = full on/off modulation.

Examples

SinusoidalFlickering(10.0)                  # 10 Hz, full modulation
SinusoidalFlickering(5.0; amplitude=0.5)    # 5 Hz, partial modulation

SquareFlickering(f; amplitude=1.0)

Square-wave temporal modulation of the electron flux.

The flux alternates between (1 - amplitude) and 1 of the base flux at the given frequency. With amplitude=1.0, the flux alternates fully between 0 and 1.

Arguments

• f: modulation frequency (Hz)

Keyword Arguments

• amplitude=1.0: modulation depth. 0 = constant flux, 1 = full on/off modulation.

Examples

SquareFlickering(10.0)                  # 10 Hz, full modulation
SquareFlickering(5.0; amplitude=0.5)    # 5 Hz, partial modulation

SmoothOnset(t_start, t_end)

Smooth flux onset using a C∞-smooth transition function.

The flux transitions smoothly from 0 to 1 over the interval [t_start, t_end]. Before t_start, the flux is 0; after t_end, the flux is 1.

When t_start == t_end, this acts as a step function (Heaviside) at t_start.

Arguments

• t_start: start time of the transition (s)
• t_end: end time of the transition (s)

Examples

SmoothOnset(0.0, 0.1)    # smooth ramp from t=0 to t=0.1 s
SmoothOnset(0.0, 0.0)    # step function at t=0

apply_modulation(mod::AbstractModulation, t_shifted)

Apply temporal modulation to a time grid, returning a vector of modulation factors (values between 0 and 1) for each time step.

t_shifted is the time grid shifted for energy- and angle-dependent electron travel times, important in case a z_source was specified in the InputFlux.

InputFlux{S<:AbstractSpectrum, M<:AbstractModulation}

A unified electron precipitation input, combining an energy spectrum shape with a temporal modulation and beam selection.

Fields

• spectrum: the energy spectrum shape (any AbstractSpectrum)
• modulation: the temporal modulation (any AbstractModulation)
• beams: indices of the electron beams with precipitating flux
• z_source: altitude of the precipitation source (km)

Constructors

# Steady-state (constant modulation is the default)
InputFlux(FlatSpectrum(1e-2; E_min=2900); beams=1:2)
InputFlux(MaxwellianSpectrum(1e-2, 1000); beams=1:2)

# Time-dependent with modulation
InputFlux(FlatSpectrum(1e-2; E_min=100), SinusoidalFlickering(5.0);
          beams=1, z_source=3000)

# From file (modulation must be and is by default ConstantModulation)
InputFlux(FileSpectrum("path.mat"))

compute_flux(flux::InputFlux, model::AuroraModel, t)

Compute the full 3D electron flux array for a time-dependent simulation.

Evaluates the energy spectrum, distributes it over beams, and applies temporal modulation (including energy- and angle-dependent electron travel-time delays if a z_source was specified in the InputFlux).

The spectrum is spread over the selected downward-going beams proportionally to their solid angle, and normalized so that the field-aligned (vertical) energy flux crossing the horizontal top boundary equals IeE_tot, independent of the beam selection.

Arguments

• flux: an InputFlux describing the precipitation
• model: an AuroraModel with grids and atmosphere/ionosphere
• t: simulation time grid (s). Range or Vector

Returns

• Ie_top: electron number flux (#e⁻/m²/s). Array [n_beams, n_t, n_E]

compute_flux(flux::InputFlux, model::AuroraModel)

Compute the electron flux array for a steady-state simulation.

This method is for steady-state runs: it evaluates the energy spectrum and distributes it over beams without any time dependence or travel-time delays. As in the time-dependent method, the spectrum is normalized so that the field-aligned (vertical) energy flux equals IeE_tot, independent of the beam selection.

Only ConstantModulation is allowed for steady-state. Other modulation types will raise an error.

Arguments

• flux: an InputFlux describing the precipitation
• model: an AuroraModel with grids and atmosphere

Returns

• Ie_top: electron number flux (#e⁻/m²/s). Array [n_beams, 1, n_E]

Ie_top_from_file(t, E, μ_center, filename; interpolation=:constant)

Load a time-dependent electron flux from a .mat file and resample it onto the simulation time grid t.

Arguments

• t: full simulation time grid (s). Range or Vector [n_t]
• E: energy grid (eV). Vector [n_E]
• μ_center: electron beams average pitch angle cosine. Vector [n_μ]
• filename: path to the .mat file containing the flux data

Keyword Arguments

• interpolation=: interpolation scheme used to resample the file's time grid onto the simulation time grid. Either:
  • :constant (default): each file value is held constant until the next sample.
  • :linear: linear interpolation between consecutive file samples.
  • :pchip: piecewise cubic Hermite interpolation.

Returns

• Ie_top: electron number flux (#e⁻/m²/s). Array [nμ, nt, n_E]

File format

The .mat file must contain:

• Ie_total: flux array of shape [n_μ, n_t_file, n_E]
• t_top: time grid (s) of the file, as a vector [n_t_file]. Optional when n_t_file == 1.

Time grid handling

The file's time grid (t_top) does not need to match the simulation time grid. It is treated as relative: t_top[1] is always aligned with t[1], regardless of the absolute values stored in the file. Only the duration and spacing of t_top matter. Any combination of time step sizes and grid lengths is supported:

• Different dt: the file is resampled onto the simulation grid via interpolation.
• File finer than simulation: the flux is point-sampled, which may miss rapid variations.
• File shorter than simulation: flux is set to zero for times beyond the file duration.
• File longer than simulation: the file is simply evaluated up to t[end].

Notes

• Upward-going beams (μ_center > 0) are always set to zero.
• The energy dimension of the file may be larger than length(E); only the first length(E) bins are used. It cannot be smaller.