Input Flux

Load from file

AURORA.Ie_top_from_file — Function

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.

source

Analytical flux

AURORA.Ie_top_modulated — Function

Ie_top_modulated(IeE_tot, model, Beams, t, n_loop;
                 spectrum=:flat, E_min=0.0, E₀=nothing, ΔE=nothing,
                 modulation=:none, f=0.0, amplitude=1.0,
                 z_source=model.altitude_grid.h[end]/1e3, t_start=0.0, t_end=0.0)

Create a time-dependent electron flux distribution with configurable energy spectrum shape and temporal modulation.

Returns an electron flux distribution (in #e⁻/m²/s) such that when integrated over energy (at full modulation), the total energy flux IeE_tot is recovered.

Arguments

IeE_tot: total energy flux (W/m²)
model: AuroraModel describing the grids and atmosphere
Beams: indices of the electron beams with precipitating flux
t: time grid (s). Range or Vector [n_t]
n_loop: number of loops (for repeated simulations)

Keyword Arguments

Energy spectrum shape

spectrum=:flat: energy spectrum type. Either :flat or :gaussian
E_min=0.0: minimum energy threshold (eV) - only used for spectrum=:flat
E₀=nothing: characteristic/center energy (eV) - required for spectrum=:gaussian
ΔE=nothing: energy width (eV) - required for spectrum=:gaussian

Temporal modulation

modulation=:none: temporal modulation type. One of :none, :sinus, or :square
f=0.0: modulation frequency (Hz) - used for :sinus and :square
amplitude=1.0: modulation depth. 0 = constant flux, 1 = full on/off modulation. Values between 0 and 1 give partial modulation.

Time-dependent features

z_source: altitude of the precipitation source (km). Default: top of ionosphere
t_start=0.0: start time for smooth flux onset (s) - only used for modulation=:none
t_end=0.0: end time for smooth flux onset (s) - only used for modulation=:none

Returns

Ie_top: electron number flux (#e⁻/m²/s). Matrix [nbeams, nt, n_E]

Physics

The function creates an electron precipitation spectrum with:

Energy spectrum: Either flat (uniform in #e⁻/m²/s/eV above Emin) or Gaussian (centered at E₀ with width ΔE). Both are normalized so the total energy flux equals `IeEtot`.
Energy- and angle-dependent arrival times: Lower energy electrons travel slower, arriving later at the ionosphere top. Similarly, electrons with high pitch-angles travel longer paths. This creates natural dispersion.
Temporal modulation: The flux can be constant (:none), sinusoidally modulated (:sinus), or square-wave modulated (:square). The amplitude parameter controls the modulation depth.

Examples

Flat spectrum with smooth onset:

julia> msis_file = find_msis_file(verbose=false);

julia> iri_file = find_iri_file(verbose=false);

julia> model = AuroraModel((100, 600), 180:-10:0, 10e3, msis_file, iri_file; verbose=false);

julia> Ie = Ie_top_modulated(1e-2, model, 1:2, 0:0.01:1, 1;
                             spectrum=:flat, E_min=9000.0, t_start=0.0, t_end=0.1);

Gaussian spectrum with sinusoidal modulation at 10 Hz:

julia> msis_file = find_msis_file(verbose=false);

julia> iri_file = find_iri_file(verbose=false);

julia> model = AuroraModel((100, 600), 180:-10:0, 10e3, msis_file, iri_file; verbose=false);

julia> Ie = Ie_top_modulated(1e-2, model, 1:2, 0:0.001:0.5, 1;
                             spectrum=:gaussian, E₀=5000.0, ΔE=500.0,
                             modulation=:sinus, f=10.0, amplitude=1.0);

source

Ie_top_modulated(IeE_tot, model, Beams;
                 spectrum=:flat, E_min=0.0, E₀=nothing, ΔE=nothing)

Steady-state version of Ie_top_modulated that does not include time-dependent behavior.

This overload is designed for steady-state simulations and eliminates the need to specify time-related parameters (t, n_loop, modulation, f, amplitude, z_source, etc.). It internally calls the time-dependent version with minimal time grid (1:1:1) and n_loop=1.

Arguments

IeE_tot: total energy flux (W/m²)
model: AuroraModel describing the grids and atmosphere
Beams: indices of the electron beams with precipitating flux

Keyword Arguments

spectrum=:flat: energy spectrum type. Either :flat or :gaussian
E_min=0.0: minimum energy threshold (eV) - only used for spectrum=:flat
E₀=nothing: characteristic/center energy (eV) - required for spectrum=:gaussian
ΔE=nothing: energy width (eV) - required for spectrum=:gaussian

Returns

Ie_top: electron number flux (#e⁻/m²/s). Matrix [nbeams, 1, nE]

Examples

julia> msis_file = find_msis_file(verbose=false);

julia> iri_file = find_iri_file(verbose=false);

julia> model = AuroraModel((100, 600), 180:-10:0, 10e3, msis_file, iri_file; verbose=false);

julia> Ie = Ie_top_modulated(1e-2, model, 1:2; spectrum=:flat, E_min=9000.0);

source

AURORA.Ie_with_LET — Function

Ie_with_LET(IeE_tot, E₀, model, Beams; low_energy_tail=true)

Return an electron spectra following a Maxwellian distribution with a low energy tail (LET)

This function is a corrected implementation of Meier/Strickland/Hecht/Christensen JGR 1989 (pages 13541-13552)

Arguments

IeE_tot: total energy flux (W/m²)
E₀: characteristic energy (eV)
model: AuroraModel describing the grids and atmosphere
Beams: indices of the electron beams with a precipitating flux

Keyword Arguments

low_energy_tail=true: control the presence of a low energy tail

Returns:

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

Important notes

This is a corrected version of the equations present in Meier et al. 1989 to match the results presented in Fig. 4 of their paper.
Changes were made to the factor b:

no inverse

Examples:

Calling the function with flux only in the two first beams (0 to 20°) and an "isotropic" pitch-angle distribution.

julia> msis_file = find_msis_file(verbose=false);

julia> iri_file = find_iri_file(verbose=false);

julia> model = AuroraModel((100, 600), 180:-10:0, 10e3, msis_file, iri_file; verbose=false);

julia> Ie = AURORA.Ie_with_LET(1e-2, 1e3, model, 1:2);

Calling the function with flux only in the three first beams (0 to 30°) and a custom pitch-angle distribution (1/2 of the total flux in the first beam, 1/4 in the second beam and 1/4 in the third beam).

julia> msis_file = find_msis_file(verbose=false);

julia> iri_file = find_iri_file(verbose=false);

julia> model = AuroraModel((100, 600), 180:-10:0, 10e3, msis_file, iri_file; verbose=false);

julia> Ie = Ie_with_LET(1e-2, 1e3, model, 1:3);

source