Results and plotting

mutable struct Results{F <: AbstractFloat, I <: Integer}

A mutable struct to store the results of simulations.

Fields

• rgi_id::String: Identifier for the RGI (Randolph Glacier Inventory).
• H::Vector{Matrix{F}}: Vector of matrices representing glacier ice thickness H over time.
• H_glathida::Matrix{F}: Optional matrix for Glathida ice thicknesses.
• H_ref::Vector{Matrix{F}}: Reference data for ice thickness.
• S::Matrix{F}: Glacier surface altimetry.
• B::Matrix{F}: Glacier bedrock.
• V::Matrix{F}: Glacier ice surface velocities.
• Vx::Matrix{F}: x-component of the glacier ice surface velocity V.
• Vy::Matrix{F}: y-component of the glacier ice surface velocity V.
• V_ref::Matrix{F}: Reference data for glacier ice surface velocities V.
• Vx_ref::Matrix{F}: Reference data for the x-component of the glacier ice surface velocity Vx.
• Vy_ref::Matrix{F}: Reference data for the y-component of the glacier ice surface velocity Vy.
• date_Vref::Vector{F}: Date of velocity observation (mean of date1 and date2).
• date1_Vref::Vector{F}: First date of velocity acquisition.
• date2_Vref::Vector{F}: Second date of velocity acquisition.
• t_dhdt::Tuple{F, F}: Time window of the mean surface elevation change.
• dhdt_ref::F: Mean surface elevation change.
• Δx::F: Grid spacing in the x-direction.
• Δy::F: Grid spacing in the y-direction.
• lon::F: Longitude of the glacier grid center.
• lat::F: Latitude of the glacier grid center.
• nx::I: Number of grid points in the x-direction.
• ny::I: Number of grid points in the y-direction.
• tspan::Vector{F}: Time span of the simulation.

Results(glacier::G, ifm::IF;
    rgi_id::String = glacier.rgi_id,
    H::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    H_glathida::Matrix{F} = glacier.H_glathida,
    H_ref::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    S::Matrix{F} = zeros(Sleipnir.Float, size(ifm.S)),
    B::Matrix{F} = zeros(Sleipnir.Float, size(glacier.B)),
    V::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    Vx::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    Vy::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    V_ref::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    Vx_ref::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    Vy_ref::Vector{Matrix{F}} = Vector{Matrix{Sleipnir.Float}}([[;;]]),
    date_Vref::Vector{F} = Vector{Sleipnir.Float}([]),
    date1_Vref::Vector{F} = Vector{Sleipnir.Float}([]),
    date2_Vref::Vector{F} = Vector{Sleipnir.Float}([]),
    t_dhdt::Union{Tuple{F, F}, Nothing} = nothing,
    dhdt_ref::Union{F, Nothing} = nothing,
    Δx::F = glacier.Δx,
    Δy::F = glacier.Δy,
    lon::F = glacier.cenlon,
    lat::F = glacier.cenlat,
    nx::I = glacier.nx,
    ny::I = glacier.ny,
    t::Vector{F} = Vector{Sleipnir.Float}([]),
    tspan::Tuple{F, F} = (NaN, NaN),
) where {G <: AbstractGlacier, F <: AbstractFloat, IF <: AbstractModel, I <: Integer}

Construct a Results object for a glacier simulation.

Arguments

• glacier::G: The glacier object, subtype of AbstractGlacier.
• ifm::IF: The model object, subtype of AbstractModel.
• rgi_id::String: The RGI identifier for the glacier. Defaults to glacier.rgi_id.
• H::Vector{Matrix{F}}: Ice thickness matrices. Defaults to an empty vector.
• H_glathida::Matrix{F}: Ice thickness from GlaThiDa. Defaults to glacier.H_glathida.
• H_ref::Vector{Matrix{F}}: Reference ice thickness. Defaults to an empty vector.
• S::Matrix{F}: Surface elevation matrix. Defaults to a zero matrix of the same size as ifm.S.
• B::Matrix{F}: Bed elevation matrix. Defaults to a zero matrix of the same size as glacier.B.
• V::Vector{Matrix{F}}: Velocity magnitude matrix. Defaults to an empty vector.
• Vx::Vector{Matrix{F}}: Velocity in the x-direction matrix. Defaults to an empty vector.
• Vy::Vector{Matrix{F}}: Velocity in the y-direction matrix. Defaults to an empty vector.
• V_ref::Vector{Matrix{F}}: Reference velocity magnitude matrix. Defaults to an empty vector.
• Vx_ref::Vector{Matrix{F}}: Reference velocity in the x-direction matrix. Defaults to an empty vector.
• Vy_ref::Vector{Matrix{F}}: Reference velocity in the y-direction matrix. Defaults to an empty vector.
• date_Vref::Vector{F}: Date of velocity observation (mean of date1 and date2). Defaults to an empty vector.
• date1_Vref::Vector{F}: First date of velocity acquisition. Defaults to an empty vector.
• date2_Vref::Vector{F}: Second date of velocity acquisition. Defaults to an empty vector.
• t_dhdt::Union{Tuple{F, F}, Nothing}: Time window of the mean surface elevation change. Defaults to nothing in which case if glacier.dhdtData exists, glacier.dhdtData.t is used instead.
• dhdt_ref::Union{F, Nothing}: Mean surface elevation change. Defaults to nothing in which case if glacier.dhdtData exists, glacier.dhdtData.dhdt is used instead.
• Δx::F: Grid spacing in the x-direction. Defaults to glacier.Δx.
• Δy::F: Grid spacing in the y-direction. Defaults to glacier.Δy.
• lon::F: Longitude of the glacier grid center. Defaults to glacier.cenlon.
• lat::F: Latitude of the glacier grid center. Defaults to glacier.cenlat.
• nx::I: Number of grid points in the x-direction. Defaults to glacier.nx.
• ny::I: Number of grid points in the y-direction. Defaults to glacier.ny.
• tspan::Tuple(F, F): Timespan of the simulation.
• θ::Union{Nothing, ComponentArray{F}}: Model parameters. Defaults to nothing.
• loss::Union{Nothing, Vector{F}}: Loss values. Defaults to nothing.

Returns

• results::Results: A Results object containing the simulation results.

plot_glacier(results, plot_type, variables; kwargs...) -> Figure

High-level entry point that dispatches to specific glacier plotting functions based on plot_type:

• "heatmaps" → plot_glacier_heatmaps
• "quivers" → plot_glacier_quivers
• "evolution difference" → plot_glacier_difference_evolution
• "evolution statistics" → plot_glacier_statistics_evolution
• "integrated volume" → plot_glacier_integrated_volume
• "bias" → plot_bias
• "dem" → plot_glacier_dem

plot_glacier_vid(
    plot_type::String,
    results::Results,
    glacier::Glacier2D,
    tspan,
    step,
    pathVideo::String;
    framerate::Int=24,
    baseTitle::String=""
)

Generate various types of videos for glacier data. For now only the evolution of the glacier ice thickness is supported. More types of visualizations will be added in the future.

Arguments

• plot_type: Type of plot to generate. Options are:

  • "thickness": Heatmap of the glacier thickness.

• results: A result object containing the simulation results including ice thickness over time.

• glacier: A glacier instance.

• tspan: The simulation time span.

• step: Time step to use to retrieve the results and generate the video.

• pathVideo: Path of the output animation. The format is inferred from the file extension — e.g. .mp4 for a video or .gif for an animated GIF.

Optional Keyword Arguments

• framerate: The framerate to use for the video generation.
• baseTitle: The prefix to use in the title of the frames. In each frame it is concatenated with the value of the year in the form " (t=XXXX)".

plot_gridded_data(
    gridded_data::Union{Vector{Matrix{F}}, Matrix{F}},
    results::Results;
    scale_text_size::Union{Nothing,Float64}=nothing,
    timeIdx::Union{Nothing,Int64}=nothing,
    figsize::Union{Nothing, Tuple{Int64, Int64}} = nothing,
    plotContour::Bool=false,
    colormap = :cool,
    logPlot = false,
) where {F <: AbstractFloat}

Plot a gridded matrix (or a time series of matrices) as a heatmap using metadata from results.

Arguments

• gridded_data::Union{Vector{Matrix{F}}, Matrix{F}}: Single snapshot or time series (defaults to last timestep).
• results::Results: Supplies lon, lat, x, y, rgi_id, Δx and H (mask).
• scale_text_size, figsize, colormap: Optional plotting params.
• timeIdx::Union{Nothing,Int64}: Select timestep when gridded_data is a vector.
• plotContour::Bool: overlay glacier-mask contour from results.H.
• logPlot::Bool: Use log10 colorscale (positive non-NaN values determine range).

Behavior

• Masks out cells where results.H[begin] .<= 0 (set to NaN).
• Adds colorbar, central lon/lat tick, and a Δx-based scale bar in km.
• If plotContour, draws mask boundary lines.
• Returns a CairoMakie.Figure.

Errors

• Asserts gridded_data is non-empty and timeIdx (if provided) is in range.

accumulate_gridded_data(
    gridded_data::Vector{Matrix{F}};
    weights::Union{Nothing,AbstractVector{<:Real}}=nothing,
) where {F <: AbstractFloat}

Accumulate a time series of gridded matrices into a single matrix.

Arguments

• gridded_data::Vector{Matrix{F}}: Sequence of gridded fields to accumulate.
• weights::Union{Nothing,AbstractVector{<:Real}}: Optional per-step weights. If provided, weighted accumulation is performed as sum(weights[i] * gridded_data[i]).

Returns

• Matrix{F}: The accumulated matrix.

plot_cumulative_gridded_data(
    gridded_data::Vector{Matrix{F}},
    results::Results;
    weights::Union{Nothing,AbstractVector{<:Real}}=nothing,
    kwargs...
) where {F <: AbstractFloat}

Plot the cumulative field of a time series of gridded matrices using plot_gridded_data. This is a thin utility wrapper to avoid duplicating plotting code.

Arguments

• gridded_data::Vector{Matrix{F}}: Sequence of gridded fields to accumulate.
• results::Results: Results object with glacier metadata for plotting.
• weights::Union{Nothing,AbstractVector{<:Real}}: Optional per-step weights.
• kwargs...: Additional keyword arguments forwarded to plot_gridded_data.

Returns

• Figure: Cumulative field figure.

plot_cumulative_mb(results::Results; kwargs...)

Plot a spatial map of the cumulative surface mass balance accumulated over the simulation period from the per-callback MB fields stored in results.MB.

Each entry of results.MB is the gridded mass-balance increment produced at one MB callback (one per MB time step). The function sums these increments cell-by-cell (via accumulate_gridded_data) to obtain the total mass balance over the period results.tspan = (t0, t1).

Modes (annual_MB)

• annual_MB = false (default): plots the raw cumulative MB over the whole period, i.e. Σᵢ MBᵢ, in m w.e..
• annual_MB = true: divides every increment by the period length T = t1 - t0 (in years) before summing, i.e. Σᵢ (MBᵢ / T) = (Σᵢ MBᵢ) / T. Since Σᵢ MBᵢ is the total over T years, this is the mean annual mass-balance rate (the "annually-averaged equivalent"), in m w.e. yr⁻¹.

Returns nothing (with a warning) when results.MB is empty — e.g. when the simulation was run without use_MB = true.

Arguments

• results::Results: results carrying the per-callback MB maps in results.MB.

Keyword arguments

• title::String: figure title prefix (the period (t0–t1) is appended automatically).
• colorbar_label::Union{Nothing,String}: colorbar label; defaults to m w.e. (or m w.e. yr⁻¹ when annual_MB = true).
• annual_MB::Bool = false: switch between cumulative total and mean annual rate.
• colormap: diverging colormap (red→white→blue by default).
• kwargs...: forwarded to plot_gridded_data.

Returns

• Figure, or nothing if there is no MB history.

plot_glacier_dem(glacier_or_results; kwargs...)

Plot the glacier DEM (surface elevation field S) with a terrain colormap, geographic coordinate labels, colorbar, and glacier contour overlay.

Arguments

- `glacier_or_results`: Either `Results` or `Glacier2D`.

Keyword Arguments

- `title::String`: Figure title prefix.
- `colorbar_label::String`: Label for the colorbar.
- `plotContour::Bool`: Whether to overlay glacier contour (default `true`).
- `colormap`: Makie colormap symbol (default `:terrain`).
- `kwargs...`: Additional keyword arguments forwarded to `plot_gridded_data`.

Returns

- `Figure`: DEM figure.

save_figure(fig, path)

Save fig to path, creating any missing parent directories automatically. Returns path.