Visualization

plot_model(model::AuroraModel; panels=[:all])

Plot the model setup: atmosphere, energy grid, cross-sections, phase functions, and scattering data.

Returns a Dict{Symbol, Figure} with one figure per panel. Use the panels keyword to select which panels to plot.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

Available panels

:atmosphere, :energy_levels, :energy_grid, :cross_sections, :phase_functions, :scattering, or :all (default) to plot everything.

Examples

using CairoMakie
figs = plot_model(model)
figs = plot_model(model; panels=[:atmosphere, :cross_sections])

plot_input(sim::AuroraSimulation)

Plot the input electron flux for a simulation.

For time-dependent simulations, produces a heatmap of flux vs energy and time for each active beam. For steady-state simulations, produces a line plot of flux vs energy.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

Examples

using CairoMakie
sim = AuroraSimulation(model, flux, savedir;
                       mode=TimeDependentMode(duration=0.5, dt=0.001))
fig = plot_input(sim)

plot_excitation!(ax, data::VolumeExcitationResult;
                 field=:total, time_index=nothing, colorrange=nothing,
                 colormap=:viridis, show_contours=false, show_height_of_max=true,
                 kwargs...)

Plot a volume excitation or ionization rate onto an existing Axis.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

• If data contains one time step, or if time_index is given, plots an altitude profile (returns a Lines plot).
• Otherwise, plots a time-altitude heatmap (returns a Heatmap).

Keyword Arguments

• field = :total: which rate to plot. Can be any field of VolumeExcitationResult: :Q4278, :Q6730, :Q7774, :Q8446, :QO1D, :QO1S, :QOi, :QO2i, :QN2i, or :total which sums the three ionization rates (:QN2i + :QO2i + :QOi).
• time_index = nothing: if given, plot a single altitude profile at that time index. If nothing and the data has more than one time step, a heatmap is plotted.
• colorrange = nothing: (min, max) limits for the colorscale. Defaults to (max_value / 1e4, max_value) spanning 4 orders of magnitude.
• colormap = :viridis: Makie colormap for the heatmap.
• show_contours = false: if true, overlays black contour lines on the heatmap (heatmap mode only).
• show_height_of_max = true: if true, overlays a dashed red line at the altitude of peak rate at each time step (heatmap mode only).
• kwargs: additional keyword arguments are forwarded to the underlying heatmap! or lines! call.

plot_column_excitation!(ax, data::ColumnExcitationResult;
                        wavelengths=[:I_4278, :I_6730, :I_7774, :I_8446, :I_O1D, :I_O1S],
                        kwargs...)

Plot column-integrated emission intensities onto an existing Axis.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

Keyword Arguments

• wavelengths: vector of symbols selecting which emission lines to plot. Available values are :I_4278, :I_6730, :I_7774, :I_8446, :I_O1D, :I_O1S. Defaults to all six. O(¹D) and O(¹S) lines are plotted with a dashed linestyle.
• kwargs: additional keyword arguments are forwarded to each underlying lines! call.

plot_input!(ax, data::IeTopResult;
            beams=1, colorrange=nothing, colormap=:inferno, kwargs...)

Plot the input electron flux stored in an IeTopResult onto an existing Axis.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

Keyword Arguments

• beams = 1: pitch-angle beam index, or vector of indices, to include. Selected beams are summed and normalised by their combined solid angle, then converted to differential energy flux (#e⁻/m²/s/eV/ster).
• colorrange = nothing: (min, max) limits for the colorscale. Defaults to (max_value / 1e4, max_value) spanning 4 orders of magnitude.
• colormap = :inferno: Makie colormap for the heatmap.
• kwargs...: additional keyword arguments are forwarded to the underlying heatmap! call.

animate_Ie_in_time(directory_to_process;
                   angles_to_plot=nothing, colorrange=nothing, save_to_file=true,
                   plot_input=false, input_angle_cone=[170, 180], dt_steps=1,
                   framerate=30, max_bytes=512*1024^2)

Plot a heatmap of Ie over height and energy, and animate it in time. The animation is saved as a .mp4 file under the directory_to_process if save_to_file = true.

Requires a Makie backend (e.g. using CairoMakie or using GLMakie).

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 simulation grid 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 an animation.mp4 file (or animation_with_precipitation.mp4 when plot_input = true) inside directory_to_process.
• plot_input = false: if true, also plots the precipitating electron flux at the top of the ionosphere by loading it from simulation_data.nc.
• input_angle_cone = [170, 180]: pitch-angle cone (degrees) used to select and sum beams for the precipitation overlay. Only used when plot_input = true.
• dt_steps = 1: plot one frame every dt_steps timesteps. Increase to speed up rendering.
• framerate = 30: framerate of the animation in frames per second.
• max_bytes = 512 * 1024^2: per-chunk memory budget for streaming the flux from simulation_data.nc.

Example

# Use default angles and colorrange:
julia> animate_Ie_in_time(directory_to_process)

# Use 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_input=true)

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

Notes

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.