Input Flux

The input flux describes the precipitating electron flux injected at the top of the simulated ionosphere. It is the primary "forcing" of an AURORA simulation and is fully specified by an InputFlux object, which combines:

• an energy spectrum (AbstractSpectrum) — the shape of the differential number flux as a function of energy, and
• a temporal modulation (AbstractModulation) — how that flux varies in time.

Once an InputFlux is built, it is bundled with an AuroraModel into an AuroraSimulation and executed with run!. Internally, run! calls compute_flux to produce the full 3-D flux array Ie_top of shape [n_beams, n_t, n_E] (units: #e⁻/m²/s).

Spectrum types

A spectrum controls the energy shape of the input flux. All built-in spectrum types are sub-types of AbstractSpectrum and are normalized so that the integrated field-aligned (vertical) energy flux equals IeE_tot (W/m²).

FileSpectrum is the exception: it loads the complete flux distribution (including any time dependence) directly from a file, so it must be used with ConstantModulation and cannot be combined with other modulation types.

Examples

using AURORA

# Flat spectrum: 10 mW/m² above 100 eV
flat = FlatSpectrum(1e-2; E_min=100)

# Gaussian: 10 mW/m², peaked at 5 keV with 500 eV width
gauss = GaussianSpectrum(1e-2, 5000.0, 500.0)

# Maxwellian: 10 mW/m², characteristic energy 1 keV
maxw = MaxwellianSpectrum(1e-2, 1000.0)

MaxwellianSpectrum(IeE_tot=0.01 W/m², E₀=1000.0 eV + LET)

Modulation types

A modulation controls the time dependence of the flux. All modulation types are sub-types of AbstractModulation. The modulation factor (a value between 0 and 1) is multiplied by the base spectrum at every time step.

Examples

# 5 Hz sinusoidal flickering
sin_mod = SinusoidalFlickering(5.0)

# 10 Hz square wave with 50% modulation depth
sq_mod = SquareFlickering(10.0; amplitude=0.5)

# Smooth onset from 0 to 1 over the first 0.1 s
onset = SmoothOnset(0.0, 0.1)

Building an InputFlux

InputFlux is the top-level object that bundles a spectrum, a modulation, the set of pitch-angle beams that carry the precipitating electrons (beams), and an optional source altitude (z_source).

beams selects which pitch-angle beams receive precipitating flux. Beam indices correspond to the downward-pointing elements of the pitch-angle grid (i.e. beams with μ < 0). Upward-going beams are always forced to zero inside compute_flux. The spectrum is divided among the selected beams weighted by their solid angle (Ωbeam), and normalized so that the field-aligned (vertical) energy flux is preserved regardless of which beams are chosen. In other words, beams controls only the angular distribution of the precipitation, not the total energy budget reaching the atmosphere: the vertical energy flux through the top boundary always equals `IeEtot`.

z_source (km) is the altitude from which electrons are launched. If set, electrons of different energies and pitch angles acquire a travel-time delay before reaching the top of the ionosphere — faster (higher energy) electrons arrive earlier. This produces realistic energy- and angle-dependent timing when combined with a flickering modulation. If omitted (NaN, the default), all electrons arrive at the top of the ionosphere simultaneously with no delay.

Steady-state example

# Flat spectrum from 2900 eV to E_max.
# No modulation is needed; ConstantModulation is the default.
flux = InputFlux(FlatSpectrum(1e-2; E_min=2900); beams=1:2)

InputFlux:
├── Spectrum:   FlatSpectrum(IeE_tot=0.01 W/m², E_min=2900.0 eV)
├── Modulation: ConstantModulation()
├── Beams:      [1, 2]
└── Source altitude: top of ionosphere

Time-dependent examples

# Sinusoidal flickering at 5 Hz, electrons sourced 3000 km above the ionosphere top.
# The travel-time delay is applied automatically for each energy and pitch angle.
flux_td1 = InputFlux(FlatSpectrum(1e-2; E_min=100), SinusoidalFlickering(5.0);
                     beams=1, z_source=3000.0)

InputFlux:
├── Spectrum:   FlatSpectrum(IeE_tot=0.01 W/m², E_min=100.0 eV)
├── Modulation: SinusoidalFlickering(f=5.0 Hz, amplitude=1.0)
├── Beams:      [1]
└── Source altitude: 3000.0 km

# Maxwellian spectrum with a smooth onset over the first 0.1 s.
flux_td2 = InputFlux(MaxwellianSpectrum(1e-2, 1000.0), SmoothOnset(0.0, 0.1);
                     beams=1:2)

InputFlux:
├── Spectrum:   MaxwellianSpectrum(IeE_tot=0.01 W/m², E₀=1000.0 eV + LET)
├── Modulation: SmoothOnset(t_start=0.0 s, t_end=0.1 s)
├── Beams:      [1, 2]
└── Source altitude: top of ionosphere

# Square-wave flickering at 10 Hz with 50% modulation depth.
flux_td3 = InputFlux(GaussianSpectrum(1e-2, 5000.0, 500.0), SquareFlickering(10.0; amplitude=0.5);
                     beams=1)

InputFlux:
├── Spectrum:   GaussianSpectrum(IeE_tot=0.01 W/m², E₀=5000.0 eV, ΔE=500.0 eV)
├── Modulation: SquareFlickering(f=10.0 Hz, amplitude=0.5)
├── Beams:      [1]
└── Source altitude: top of ionosphere

Loading flux from a file

FileSpectrum loads a time-dependent flux distribution directly from a .mat file. This is useful when you have measured or externally computed input fluxes.

File format

The .mat file must contain the variable Ie_total with shape [n_μ, n_t_file, n_E] (units: #e⁻/m²/s), and optionally t_top (a vector of length n_t_file, in seconds).

Matching the grids

Before writing a file, build an AuroraModel with the same settings you intend to use for the simulation, then read the grids from it:

using MAT

# Build the model (same settings as the simulation that will use the file)
msis_file = find_msis_file()
iri_file  = find_iri_file()
θ_lims = 180:-10:0
E_max  = 1000.0
model  = AuroraModel([100, 600], θ_lims, E_max, msis_file, iri_file, 13)

# Extract the grids your file must be aligned to
μ_center = model.pitch_angle_grid.μ_center  # length n_μ
E_centers = model.energy_grid.E_centers     # length n_E
n_μ = length(μ_center)
n_E = length(E_centers)

Looking for an msis file that matches the parameters... found one!
   ∟ at /home/runner/work/AURORA.jl/AURORA.jl/internal_data/data_neutrals/msis_20181207-1115_76N-5E.txt
Looking for an iri file that matches the parameters... found one!
   ∟ at /home/runner/work/AURORA.jl/AURORA.jl/internal_data/data_electron/iri_20181207-1115_76N-5E.txt

Writing the file

# Example: time-dependent flux, 100 time steps
t_file = collect(0.0:0.01:0.99)   # 100 steps, dt = 10 ms
n_t_file = length(t_file)

Ie_total = zeros(n_μ, n_t_file, n_E)
# ... fill Ie_total with your flux values ...

flux_filepath = "my_flux.mat"
matwrite(flux_filepath, Dict(
    "Ie_total" => Ie_total,
    "t_top"    => t_file,
))

Using the file

flux = InputFlux(FileSpectrum(flux_filepath; interpolation=:linear))

InputFlux:
├── Spectrum:   FileSpectrum("jl_e9KrMn0XKJ.mat", interpolation=linear)
├── Modulation: ConstantModulation()
├── Beams:      [1]
└── Source altitude: top of ionosphere

Available interpolation schemes: :constant (default, nearest), :linear, :pchip (piecewise cubic Hermite).

Visualizing the input flux

AURORA provides plotting functions via a Makie extension. Load a Makie backend to visualize the input flux applied at the top boundary:

using CairoMakie   # or GLMakie for interactive plots

# Plot the input flux (requires a simulation object)
fig = plot_input(sim)

See the Visualization API page for more plotting and animation functions.