EQUIL - CLEANUP - Tighten the psihigh-clamp seam after the EquilibriumConfig freeze

Review follow-ups on the previous commit; no behavior change.

- Drop the unused 1-arg clamp_psihigh_to_separatrix(::DirectRunInput). It had no callers left
  and took psihigh from raw_profile.config, which is exactly what the config no longer owns.
- Replace it with a 2-arg forwarder taking anything that carries the EFIT flux map, so the
  NamedTuple-or-DirectRunInput duck typing lives next to the clamp instead of being spelled
  out at the call site.
- Map the read_efit_arrays NamedTuple onto DirectRunInput by field name in one place rather
  than splatting it positionally at two call sites, where adding a struct field would break
  silently.
- Say where the authoritative psihigh comes from at the three places a reader cannot infer it:
  equil.config in the two-pass block, why the clamp merges instead of mutating the caller's
  dict (it is re-serialized into gpec.h5), and that the rerun config is a placeholder.
- Trim the setup_equilibrium docstring to what a caller needs, replace a comment that described
  the previous implementation, and unwind a ||-return into an if.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jhalpern30

src/Equilibrium/DirectEquilibriumByInversion.jl

@@ -72,7 +72,7 @@ end
 
 """
     clamp_psihigh_to_separatrix(psi_in, psi_in_xs, psi_in_ys, psio, psihigh) -> (clamped_psihigh, was_adjusted)
-    clamp_psihigh_to_separatrix(raw_profile::DirectRunInput) -> (clamped_psihigh, was_adjusted)
+    clamp_psihigh_to_separatrix(flux_map, psihigh) -> (clamped_psihigh, was_adjusted)
 
 Binary-searches for the highest psihigh ≤ the requested one at which the ψ level set is still a
 closed curve in the EFIT grid. Returns the safe value and a Bool indicating whether any clamping
@@ -98,9 +98,9 @@ function clamp_psihigh_to_separatrix(psi_in, psi_in_xs, psi_in_ys, psio, psihigh
     return (lo, true)
 end
 
-clamp_psihigh_to_separatrix(raw_profile::DirectRunInput) =
-    clamp_psihigh_to_separatrix(raw_profile.psi_in, raw_profile.psi_in_xs, raw_profile.psi_in_ys,
-        raw_profile.psio, raw_profile.config.psihigh)
+# `flux_map` is anything carrying the EFIT flux map: a `read_efit_arrays` NamedTuple or a `DirectRunInput`.
+clamp_psihigh_to_separatrix(flux_map, psihigh) =
+    clamp_psihigh_to_separatrix(flux_map.psi_in, flux_map.psi_in_xs, flux_map.psi_in_ys, flux_map.psio, psihigh)
 
 """
     resample_contour_to_theta_grid!(R_out, Z_out, curve, ro, zo, theta_grid)

src/Equilibrium/Equilibrium.jl

@@ -77,10 +77,8 @@ Read an equilibrium file, run the appropriate solver, and return the processed
 `PlasmaEquilibrium` with global parameters, q-profile, and GSE diagnostics.
 
 The efit-family kinds must use the `equil_dict` method: their `psihigh` is clamped to the
-outermost closed flux surface, and that clamp is resolved from the g-file *before* the
-(immutable) `EquilibriumConfig` is built, so the run has exactly one config and never
-rewrites it. The `EquilibriumConfig` method serves the kinds with no such clamp and rejects
-efit kinds rather than silently skipping it.
+outermost closed flux surface before the immutable `EquilibriumConfig` is built. The
+`EquilibriumConfig` method serves every other kind and errors on efit.
 
 `override_psi_nodes` bypasses the config-driven radial grid (`grid_type`/`mpsi`) and forms
 the equilibrium on the given strictly increasing ψ_N node vector, whose endpoints must match
@@ -95,8 +93,10 @@ end
 function setup_equilibrium(equil_dict::Dict{String,Any}, base_path::AbstractString="./", additional_input=nothing;
     override_psi_nodes::Union{Nothing,Vector{Float64}}=nothing)
     haskey(equil_dict, "eq_type") || error("Missing required key in [Equilibrium]: eq_type")
-    equil_dict["eq_type"] in EFIT_KINDS || return setup_equilibrium(
-        EquilibriumConfig(equil_dict, base_path), additional_input; override_psi_nodes)
+    if !(equil_dict["eq_type"] in EFIT_KINDS)
+        # Only efit kinds need the separatrix clamp; every other kind builds its config directly.
+        return setup_equilibrium(EquilibriumConfig(equil_dict, base_path), additional_input; override_psi_nodes)
+    end
 
     eq_input = build_efit_input(equil_dict, base_path, additional_input)
     return run_equilibrium_solver(eq_input; override_psi_nodes)
@@ -112,22 +112,22 @@ rerun TOML is re-validated); otherwise the g-file is read here.
 """
 function build_efit_input(equil_dict::Dict{String,Any}, base_path::AbstractString, additional_input)
     prebuilt = additional_input isa DirectRunInput
-    # The requested psihigh carries the constructor's own 1.0 ceiling, so the separatrix search
-    # starts where it did when the clamp still wrote back onto the config.
+    # Mirrors the config constructor's psihigh ≤ 1.0 ceiling — the search must start from the
+    # same validated request the config would hold.
     psihigh_req = min(Float64(get(equil_dict, "psihigh", DEFAULT_PSIHIGH)), 1.0)
-    arrays = if prebuilt
+    flux_map = if prebuilt
         additional_input
     else
         eq_filename = resolve_eq_filename(equil_dict, base_path)
         eq_filename === nothing && error("Missing required key in [Equilibrium]: eq_filename (eq_type=$(equil_dict["eq_type"]))")
         read_efit_arrays(eq_filename)
     end
 
-    psihigh_safe, adjusted = clamp_psihigh_to_separatrix(
-        arrays.psi_in, arrays.psi_in_xs, arrays.psi_in_ys, arrays.psio, psihigh_req)
+    psihigh_safe, adjusted = clamp_psihigh_to_separatrix(flux_map, psihigh_req)
     if adjusted
         @warn "psihigh=$(psihigh_req) has no closed flux surface in EFIT grid; " *
               "clamped to $(round(psihigh_safe; sigdigits=7))"
+        # Merge, not mutate: the caller's dict is re-serialized into gpec.h5 and must keep the request.
         equil_dict = merge(equil_dict, Dict{String,Any}("psihigh" => psihigh_safe))
     end
     eq_config = EquilibriumConfig(equil_dict, base_path)
@@ -136,7 +136,7 @@ function build_efit_input(equil_dict::Dict{String,Any}, base_path::AbstractStrin
         additional_input.config = eq_config
         return additional_input
     end
-    return DirectRunInput(eq_config, arrays...)
+    return DirectRunInput(eq_config, flux_map)
 end
 
 function setup_equilibrium(eq_config::EquilibriumConfig, additional_input=nothing; override_psi_nodes::Union{Nothing,Vector{Float64}}=nothing)

src/Equilibrium/ReadEquilibrium.jl

@@ -118,13 +118,23 @@ function read_efit_arrays(eq_filename::AbstractString)
     return (; sq_in, psi_in, psi_in_xs, psi_in_ys, rmin, rmax, zmin, zmax, psio, bt_sign=fpol_sign, ingest)
 end
 
+"""
+    DirectRunInput(config, arrays::NamedTuple) -> DirectRunInput
+
+Bundle a [`read_efit_arrays`](@ref) NamedTuple with the config it was read for. The one place
+the reader's field names are mapped onto the struct's, so adding a field is a single edit.
+"""
+DirectRunInput(config::EquilibriumConfig, arrays::NamedTuple) =
+    DirectRunInput(config, arrays.sq_in, arrays.psi_in, arrays.psi_in_xs, arrays.psi_in_ys,
+        arrays.rmin, arrays.rmax, arrays.zmin, arrays.zmax, arrays.psio, arrays.bt_sign, arrays.ingest)
+
 """
     read_efit(config::EquilibriumConfig) -> DirectRunInput
 
 Parse the EFIT g-file named by `config` and bundle it with `config` into a `DirectRunInput`
 ready for the direct solver.
 """
-read_efit(config::EquilibriumConfig) = DirectRunInput(config, read_efit_arrays(config.eq_filename)...)
+read_efit(config::EquilibriumConfig) = DirectRunInput(config, read_efit_arrays(config.eq_filename))
 
 
 """

src/GeneralizedPerturbedEquilibrium.jl

@@ -239,6 +239,8 @@ function main_from_inputs(
     # Two-pass auto grid: measure the pass-1 equilibrium's curvature (profiles, geometry,
     # kinetic profiles), pin knots on rational surfaces, and re-form on the refined grid
     # from the in-memory input — no file re-read.
+    # equil.config is authoritative: for efit kinds its psihigh is the separatrix-clamped value,
+    # not the request still sitting in equil_dict.
     if Equilibrium.wants_two_pass(equil.config)
         mandatory = ForceFreeStates.rational_psi_nodes(equil; nlow=intr.nlow, nhigh=intr.nhigh)
         psi_nodes = Equilibrium.refined_psi_grid(equil;

src/Rerun.jl

@@ -271,6 +271,7 @@ function build_inputs_from_h5(args::Vector{String})
     # code, and `inputs` itself is re-serialized into the rerun's own input/gpec_toml_raw.
     equil_dict = merge(inputs["Equilibrium"], Dict{String,Any}("eq_filename" => ""))
     eq_type = get(equil_dict, "eq_type", nothing)
+    # Placeholder config for the ingest rebuild; setup_equilibrium replaces it with the clamped one.
     eq_config = Equilibrium.EquilibriumConfig(equil_dict, output_dir)
 
     # Analytic kinds regenerate from their TOML section; file-based kinds rebuild splines from