API Reference

find_msis_file(; year=2018, month=12, day=7, hour=11, minute=15,
                lat=76, lon=5, height=85:1:700)

Find or create a MSIS model data file for the specified conditions.

It first searches for an existing MSIS file matching the given parameters. If no matching file is found, it calculates new MSIS data using the Python pymsis package and saves it to a file. The pymsis package will download, compile and run some fortran code under the hood.

Keyword Arguments

• year::Int=2018: Year
• month::Int=12: Month (1-12)
• day::Int=7: Day of month (1-31)
• hour::Int=11: Hour in Universal Time (0-23)
• minute::Int=15: Minute (0-59)
• lat::Real=76: Geographic latitude in degrees North
• lon::Real=5: Geographic longitude in degrees East
• height::AbstractRange=85:1:700: Altitude range in km

Returns

• String: Full path to the MSIS data file

Notes

• Default parameters correspond to the VISIONS-2 rocket launch conditions
• Files are stored in internal_data/data_neutrals/ directory

find_iri_file(; year=2018, month=12, day=7, hour=11, minute=15,
                lat=76, lon=5, height=85:1:700)

Find or create an IRI model data file for the specified conditions.

It first searches for an existing IRI file matching the given parameters. If no matching file is found, it calculates new IRI data using the Python iri2016 package and saves it to a file. The iri2016 package will compile and run some fortran code under the hood.

Keyword Arguments

• year::Int=2018: Year
• month::Int=12: Month (1-12)
• day::Int=7: Day of month (1-31)
• hour::Int=11: Hour in Universal Time (0-23)
• minute::Int=15: Minute (0-59)
• lat::Real=76: Geographic latitude in degrees North
• lon::Real=5: Geographic longitude in degrees East
• height::AbstractRange=85:1:700: Altitude range in km

Returns

• String: Full path to the IRI data file

Notes

• Default parameters correspond to the VISIONS-2 rocket launch conditions
• Files are stored in internal_data/data_electron/ directory

Ie_with_LET(E₀, Q, E, dE, μ_center, BeamWeight, 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

• E₀: characteristic energy (eV)
• Q: total energy flux into the ionosphere (eV/m²/s)
• E: energy grid (eV). Vector [nE]
• dE: energy bin sizes(eV). Vector [nE]
• μ_center: electron beams average pitch angle cosine. Vector [n_beams]
• BeamWeight: weights of the different beams. Vector [n_beams]
• Beams: indices of the electron beams with a precipitating flux
• low_energy_tail=true: control the presence of a low energy tail

Returns:

• Ie_top: differential electron energy 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> E, dE = make_energy_grid(100e3);

julia> θ_lims = 180:-10:0;

julia> μ_center = mu_avg(θ_lims);

julia> BeamWeight = beam_weight(180:-10:0);

julia> Ie = AURORA.Ie_with_LET(1e3, 1e10, E, dE, μ_center, BeamWeight, 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> E, dE = make_energy_grid(100e3);

julia> θ_lims = 180:-10:0;

julia> μ_center = mu_avg(θ_lims);

julia> BeamWeight = [2, 1, 1];

julia> Ie = Ie_with_LET(1e3, 1e10, E, dE, μ_center, BeamWeight, 1:3);

animate_Ie_in_time(directory_to_process; angles_to_plot=nothing, colorrange=nothing, ...)

Plot a heatmap of Ie over height and energy, and animate it in time. It will load the result files one by one. The animation will be saved as a .mp4 file under the directory_to_process.

Example

julia> directory_to_process = "Visions2/Alfven_475s";

# Using defaults for angles and colorrange:
julia> animate_Ie_in_time(directory_to_process)

# Or with custom angles and colorrange:
julia> angles_to_plot = [(180, 170)  (170, 150)  (150, 120)  (120, 100)  (100, 90);   # DOWN
                         (0, 10)     (10, 30)    (30, 60)    (60, 80)    (80, 90)];   # UP
julia> animate_Ie_in_time(directory_to_process; angles_to_plot, colorrange=(1e5, 1e9), plot_Ietop=true)

# Using nothing for empty panels:
julia> angles_to_plot = [(180, 90)  nothing;
                         (0, 45)    (45, 90)];
julia> animate_Ie_in_time(directory_to_process; angles_to_plot)

The angles_to_plot is a matrix of tuples, where each tuple defines a pitch-angle range from 0° to 180° (where 180° is field-aligned down and 0° is field-aligned up). A panel will be created for each matrix element at the corresponding row/column position. Angles > 90° are labeled as "DOWN", angles < 90° as "UP". Use nothing for empty panels.

The limits of angles_to_plot need to match existing limits of the beams used in the simulation. E.g. if θ_lims = 180:-10:0 was used in the simulation, (150, 120) will be fine as 150° and 120° exist as limits, but (155, 120) will not as 155° does not exist as a limit.

Arguments

• directory_to_process: directory containing the simulation results (absolute or relative path).

Keyword Arguments

• angles_to_plot = nothing: limits of the angles to plot as a matrix of tuples with angles in range 0-180°. Use nothing for empty panels. If the whole argument is nothing, uses the θ_lims grid from the simulation with down-flux on the first row and up-flux on the second row.
• colorrange = nothing: limits for the colormap/colorbar as a tuple (min, max). If nothing, automatically computed as (maxvalue / 1e4, maxvalue) spanning 4 orders of magnitude.
• save_to_file = true: if true, saves the animation to a .mp4 file in the data directory.
• plot_Ietop = false: if true, also plots the precipitating Ie at the top of the ionosphere by loading it from the file Ie_top.mat.
• Ietop_angle_cone = [170, 180]: angle cone (in degrees) for the precipitating Ie to plot.