Analysis Module

Analysis

Post-processing and visualization utilities for GPEC simulation outputs.

Submodules

• ForceFreeStates: Plotting functions for ForceFreeStates (DCON-style ideal MHD stability) results
• Equilibrium: Plotting functions for equilibrium profiles and flux surfaces
• PerturbedEquilibrium: Plotting functions for perturbed equilibrium and singular coupling results

ForceFreeStates

Post-processing and visualization functions for ForceFreeStates (DCON-style ideal MHD stability) results stored in GPEC HDF5 output files.

plot_delta_prime(h5path; save_path=nothing)

Scatter plot of Re(Δ') per singular surface vs ψN, computed from the stored asymptotic coefficients `caleftandca_right`. Points are colored red (tearing unstable, Re(Δ') > 0) or blue (tearing stable). Integer-valued q rational surfaces are annotated.

Δ' is computed as (ca_right[resnum,resnum,2,s] - ca_left[resnum,resnum,2,s]) / (4π² ψ₀), where resnum is the linear mode index of the (m,n) resonant pair at surface s.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_edge_stability_scan(h5path; save_path=nothing, ylims=(-2, 3), kwargs...)

Plot the edge stability scan energy components (et, ep, ev, evonly) vs ψ_N.

The edge scan evaluates δW_total = δW_plasma + δW_vacuum at each stored integration step in the region [psiedge, psilim], with the plasma boundary swept from psiedge to psilim. A positive et indicates stability; the truncation point is chosen at the peak et.

Four subplots are shown:

• Total energy et = ep + ev: total free-boundary energy eigenvalue
• Plasma energy ep: plasma contribution to δW
• Vacuum energy ev: vacuum (wv) contribution with singfac scaling
• Vacuum-only eigenvalue evonly: smallest eigenvalue of wv alone (no plasma response)

A horizontal dashed line at zero marks the stability boundary. A vertical dashed line marks psilim (the final truncation psi, where the peak et was found).

Arguments

• h5path: Path to a GPEC HDF5 output file produced with psiedge < psilim

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)
• ylims: y-axis limits applied to all panels (default: (-2, 3))
• kwargs...: Additional Plots.jl keyword arguments applied to all line plots (e.g. lw=2)

Returns

A Plots.jl plot object, or nothing if no edge_scan/ group is present in the file.

plot_eigenvalues(h5path; matrix_type=:total, save_path=nothing)

Scatter plot of energy eigenvalues vs mode index. Points are colored red (unstable, Re > 0) or green (stable, Re < 0), with a dashed reference line at zero.

Arguments

• h5path: Path to a GPEC HDF5 output file with vacuum data (vac_flag = true)

Keyword arguments

• matrix_type: Which eigenvalues to plot: :total (et), :plasma (ep), or :vacuum (ev)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_energy_eigenvectors(h5path; matrix_type=:total, save_path=nothing)

Heatmap of energy eigenvector magnitudes vs (m, mode index).

Only matrix_type=:total is supported (the total energy eigenvector matrix Wₜ is stored in vacuum/wt). Plasma and vacuum eigenvectors are not stored separately in the HDF5 output.

Eigenvectors are scaled by χ₁ = 2π ψ₀ × 10⁻³ to match GPEC conventions.

Arguments

• h5path: Path to a GPEC HDF5 output file with vacuum data (vac_flag = true)

Keyword arguments

• matrix_type: Energy matrix to plot; only :total is currently supported
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_ffs_summary(h5path; save_path=nothing)

Four-panel summary of ForceFreeStates (DCON-style) stability results, combining:

• Energy eigenvector heatmap (plot_energy_eigenvectors)
• Fixed-boundary stability criterion |Dc| vs ψN (plot_stability_criterion)
• Eigenvalue spectrum (plot_eigenvalues)
• Tearing stability Δ' at each rational surface (plot_delta_prime)

If no vacuum data is present (vac_flag = false), only the stability criterion and Δ' panels are shown.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_fixed_boundary_stability_criterion(h5path; save_path=nothing)

Plot the stability criterion (smallest eigenvalue of W⁻¹, crit) vs ψ_N. A sign change in crit during integration indicates an ideal fixed-boundary instability.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_mode_displacement(h5path; modes=1:5, save_path=nothing)

Plot |ξψ| vs ψN for the least stable eigenmode, showing one curve per requested poloidal mode number m. The title includes the first eigenvalue dW = et[1].

Arguments

• h5path: Path to a GPEC HDF5 output file (e.g. "gpec.h5")

Keyword arguments

• modes: Iterable of m values to plot (default: 1:5)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

Equilibrium

Post-processing and visualization functions for GPEC equilibrium objects and HDF5 outputs.

plot_equilibrium_summary(h5path; save_path=nothing)

Summary of equilibrium profiles and geometry. The (R, Z) flux surface plot occupies the full left column. Profile plots are stacked in the right column:

• q(ψ) safety factor with rational surface markers (plot_qprofile)
• μ₀p(ψ) pressure profile (plot_pressure_profile)
• 2πF(ψ) toroidal field function (plot_f_profile)

If gse.h5 is present (requires diagnose_src = true), a combined Grad-Shafranov error panel (θ slices + integrated, log scale) is appended at the bottom of the right column.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_f_profile(h5path; save_path=nothing)

Plot the toroidal field function 2πF(ψ) profile (F = RBφ/(2π)).

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_flux_surfaces(h5path; n_psi=11, n_theta=18, save_path=nothing)

Plot flux surface contours (constant ψ, blue) and field-line angle spokes (constant θ, red) in physical (R, Z) space, reading nodal grid data directly from HDF5.

Psi contours are drawn at n_psi evenly spaced values between psilow and psihigh. Theta spokes are drawn at n_theta evenly spaced values.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• n_psi: Number of constant-ψ contours to draw (default: 11)
• n_theta: Number of constant-θ/θ spokes to draw (default: 18)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_gse_by_theta(h5path; n_theta_lines=8, save_path=nothing)

Plot Grad-Shafranov error vs ψN (log scale) for several θ slices, with the flux-surface-integrated error overplotted as a thick black line. Reads gse.h5 (and optionally gsei.h5) from the same directory as h5path. Returns nothing if gse.h5 is not found (requires `diagnosesrc = true` in the equilibrium configuration).

Arguments

• h5path: Path to a GPEC HDF5 output file (used to locate gse.h5)

Keyword arguments

• n_theta_lines: Number of evenly-spaced θ slices to overlay (default: 8)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object, or nothing if gse.h5 is absent.

plot_gse_integrated(h5path; save_path=nothing)

Plot the flux-surface-integrated Grad-Shafranov error (log scale) vs ψN, reading from gsei.h5 in the same directory as h5path. Returns nothing if gsei.h5 is not found (requires `diagnosesrc = true` in the equilibrium configuration).

Arguments

• h5path: Path to a GPEC HDF5 output file (used to locate gsei.h5)

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object, or nothing if gsei.h5 is absent.

plot_pressure_profile(h5path; save_path=nothing)

Plot the μ₀p(ψ) pressure profile. Vertical dashed lines mark rational surfaces if present.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_qprofile(h5path; show_singular=true, save_path=nothing)

Plot the safety factor q(ψ) profile, with optional vertical markers at each rational surface and horizontal reference lines at q0 and q95.

Arguments

• h5path: Path to a GPEC HDF5 output file

Keyword arguments

• show_singular: If true, overlay rational surface locations (default: true)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

PerturbedEquilibrium

Post-processing and visualization functions for GPEC perturbed equilibrium results stored in the perturbed_equilibrium/ group of a GPEC HDF5 output file.

plot_chirikov_parameter(h5path; save_path=nothing)

Scatter plot of the Chirikov overlap parameter per singular surface vs ψ_N, with a horizontal reference line at K = 1 (island overlap threshold). Points are colored red when K > 1. Integer-valued q rational surfaces are annotated.

Requires singular_coupling/chirikov_parameter in the HDF5 file.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_driven_delta_prime(h5path; save_path=nothing)

Scatter plot of Re(Δ') per singular surface vs ψN, computed by the perturbed equilibrium module (from `singularcoupling/delta_prime`). One marker series per toroidal mode n. Integer-valued q rational surfaces are annotated.

This is complementary to Analysis.ForceFreeStates.plot_delta_prime, which uses the FFS asymptotic coefficients. The PE result includes the vacuum Green's function contribution.

Requires singular_coupling/delta_prime in the HDF5 file.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_island_widths(h5path; save_path=nothing)

Scatter plot of island half-width w/2 per singular surface vs ψ_N. Integer-valued q rational surfaces are annotated.

Requires singular_coupling/island_half_width in the HDF5 file.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_mode_spectrogram(h5path; component=:xi_psi, save_path=nothing)

Two-panel spectrogram of a perturbed equilibrium response field component:

• Top: |component| vs ψ_N, one curve per poloidal mode m. Only resonant modes (m ∈ [0, nhigh·q95)) are labeled to keep the legend readable.
• Bottom: Heatmap of |component| in (m, ψ_N) space (psi on vertical axis), with white dashed lines at rational surface locations.

Inspired by plot_spectrograms.py from OMFIT GPEC.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium response output

Keyword arguments

• component: Response field component to plot; one of :xi_psi, :b_psi, :b_theta, :b_zeta (default: :xi_psi)
• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_perturbed_equilibrium_summary(h5path; save_path=nothing)

Three-panel composite summary of perturbed equilibrium results:

• Top-left: Island half-widths (plot_island_widths)
• Top-right: Energy breakdown — plasma, vacuum, and total energies
• Bottom: ξψ mode spectrogram (`plotmode_spectrogram`)

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_resonant_field(h5path; save_path=nothing)

Five-panel summary of resonant coupling quantities at each singular surface vs ψ_N:

• |Φ_res|: resonant flux (plot_resonant_flux)
• Re(Δ'): tearing stability parameter (plot_driven_delta_prime)
• |I_res|: resonant current
• w/2: island half-width (plot_island_widths)
• K: Chirikov overlap parameter (plot_chirikov_parameter)

Inspired by plot_resonant_field.py from OMFIT GPEC.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.

plot_resonant_flux(h5path; save_path=nothing)

Scatter plot of |Φ_res| (normalized resonant flux) per singular surface vs ψ_N. One marker series per toroidal mode n. Integer-valued q rational surfaces are annotated.

Requires the perturbed equilibrium module to have been run and singular_coupling/resonant_flux to be present in the HDF5 file.

Arguments

• h5path: Path to a GPEC HDF5 output file with perturbed equilibrium output

Keyword arguments

• save_path: If provided, save the figure to this path (default: nothing)

Returns

A Plots.jl plot object.