Perturbed Equilibrium

PerturbedEquilibriumControl

User-facing control parameters from TOML [PerturbedEquilibrium] section.

Fields

Note: Forcing data file settings are now in [ForcingTerms] section.

High Priority (MWE):

• fixed_boundary::Bool - Fixed boundary flag (default: false)
• output_eigenmodes::Bool - Output mode fields as b-fields (default: true)
• compute_response::Bool - Compute plasma response (default: true)
• compute_singular_coupling::Bool - Compute singular coupling metrics (default: true)
• verbose::Bool - Enable verbose logging (default: true)

Output Settings:

• output_filename::String - Combined output file with ForceFreeStates results (default: uses ForceFreeStates HDF5_filename)
• write_outputs_to_HDF5::Bool - Write perturbed equilibrium outputs to HDF5 (default: true)

Medium Priority (defer for MWE):

• filter_modes::Bool - Enable mode filtering (default: false)
• singular_point_method::String - Method for singular point treatment (default: "standard")

PerturbedEquilibriumInternal

Internal state variables for perturbed equilibrium calculations.

Fields

• dir_path::String - Working directory path
• forcing_modes::Vector{ForcingMode} - Loaded forcing mode data
• plasma_response::Matrix{ComplexF64} - Plasma response matrix
• singular_coupling_metrics::Dict{String,Float64} - Coupling metrics at singular surfaces
• m_modes::Vector{Int} - Poloidal mode numbers for each index i in 1:numpert_total
• n_modes::Vector{Int} - Toroidal mode numbers for each index i in 1:numpert_total

PerturbedEquilibriumState

Results from perturbed equilibrium calculations.

Fields

Response fields (mode space):

• xi_modes::Union{Nothing, NamedTuple} - Displacement (psi, theta, zeta) [npsi, mpert]
• b_modes::Union{Nothing, NamedTuple} - Magnetic field (psi, theta, zeta) [npsi, mpert]

Singular coupling matrices [msing, numpert_total]:

• resonant_flux::Matrix{ComplexF64} - Resonant flux Φ_r/A (singcoup(1,:,:))
• resonant_current::Matrix{ComplexF64} - Resonant current (singcoup(2,:,:))
• island_width_sq::Matrix{ComplexF64} - (w/2)² in ψ_n (singcoup(3,:,:))
• penetrated_field::Matrix{ComplexF64} - Resonant field (singcoup(4,:,:))
• delta_prime::Matrix{ComplexF64} - Tearing stability Δ' (singcoup(5,:,:))

Diagnostic quantities [msing]:

• island_half_width::Vector{Float64} - Actual w/2 (meters or ψ_n)
• chirikov_parameter::Vector{Float64} - Island overlap metric

Note: numpert_total = mpert × npert handles all (m,n) mode combinations

Legacy fields (deprecated):

• coupling_coefficient::ComplexF64 - Use singular coupling matrices instead
• resonant_amplitude::Float64 - Use island diagnostics instead

Energies:

• plasma_energy::Float64 - Plasma perturbation energy
• vacuum_energy::Float64 - Vacuum perturbation energy
• total_energy::Float64 - Total perturbation energy

compute_perturbed_equilibrium(
    equil::Equilibrium.PlasmaEquilibrium,
    ForceFreeStates_results::OdeState,
    vac_data::Union{VacuumData, Nothing},
    ffs_intr::ForceFreeStatesInternal,
    ft_ctrl::ForcingTerms.ForcingTermsControl,
    ctrl::PerturbedEquilibriumControl,
    intr::PerturbedEquilibriumInternal
)::PerturbedEquilibriumState

Main entry point for perturbed equilibrium calculations.

Computes plasma response to external forcing and calculates singular layer coupling metrics.

Arguments

• equil: Equilibrium solution from Equilibrium module
• ForceFreeStates_results: Stability calculation results from ForceFreeStates module
• vac_data: Vacuum response data from ForceFreeStates free boundary calculation
• ffs_intr: ForceFreeStates internal state with mode information
• ft_ctrl: Forcing terms control parameters from [ForcingTerms] section
• ctrl: Control parameters from [PerturbedEquilibrium] section
• intr: Internal state variables

Returns

• PerturbedEquilibriumState: Calculation results

Workflow

1. Load forcing data from file
2. Compute plasma response (if enabled)
3. Calculate singular coupling metrics (if enabled)
4. Output eigenmode fields (if enabled)

write_outputs_to_HDF5(
    state::PerturbedEquilibriumState,
    intr::PerturbedEquilibriumInternal,
    ctrl::PerturbedEquilibriumControl,
    filename::String
)

Write perturbed equilibrium results to HDF5 file (appends to existing ForceFreeStates output).

Output Structure

perturbed_equilibrium/
├── forcing_modes/
│   ├── n              # Toroidal mode numbers
│   ├── m              # Poloidal mode numbers
│   ├── amplitude_real # Real parts of forcing amplitudes
│   └── amplitude_imag # Imaginary parts of forcing amplitudes
├── response/
│   ├── xi_perturbed   # Displacement field
│   └── b_perturbed    # Magnetic field perturbation
├── singular_coupling/
│   ├── coupling_coefficient_real
│   ├── coupling_coefficient_imag
│   └── resonant_amplitude
└── energies/
    ├── plasma_energy
    ├── vacuum_energy
    └── total_energy