[TokaMaker] Add magnetic-diagnostic reconstruction and EFIT cross-validation

## Summary

Extend the existing VAFT TokaMaker integration from forward free-boundary equilibrium solving to **experimental magnetic-diagnostic equilibrium reconstruction**, then use that path as an independent benchmark against EFIT on matched VEST states.

The target workflow is:

```text
canonical VEST ODS
    |
    +-- machine geometry
    +-- PF active state
    +-- fixed passive-current state
    +-- plasma current
    +-- flux loops
    +-- B-pol / Mirnov probes
    +-- diamagnetic flux
    |
    v
TokaMaker reconstruction
    |
    v
canonical equilibrium ODS
    |
    +--> reconstructed diagnostic signals
    +--> normalized residuals
    +--> convergence information
    +--> EFIT comparison
```

The goal is **not** to replace production EFIT immediately. The scientific question is:

> **Given the same VEST diagnostic state, how consistently do EFIT and TokaMaker recover the physical equilibrium using different reconstruction formulations?**

---

## Implementation-plan status: re-audit before coding

The class names, API layout, implementation stages, and pseudocode below are a **design direction**, not a frozen implementation specification.

Before implementation, the agent should re-audit the current state of:

```text
VAFT develop
current vaft.code.tokamaker adapter
OpenFUSIONToolkit / TokaMaker reconstruction API
related VAFT issues / PRs
existing reconstruction / validation infrastructure
```

If the current repository or upstream TokaMaker API provides a simpler or more idiomatic path, the agent may revise:

- exact class/function names;
- forward/reconstruction API boundaries;
- reusable abstractions;
- result-object structure;
- implementation-stage ordering;
- synthetic vs experimental validation ordering;
- diagnostic mapping details required by upstream API changes.

Such changes should be documented in the PR or implementation notes.

The following scientific contract should remain invariant:

```text
canonical VEST diagnostics
        ↓
independently generated TokaMaker reconstruction input
        ↓
scientifically qualified reconstruction
        ↓
canonical equilibrium representation
        ↓
matched EFIT comparison
```

In other words, this issue prioritizes the **scientific and solver-comparison contract** over a prescriptive implementation recipe.

---

# Relationship to existing VAFT issues

## #218 — TokaMaker forward free-boundary adapter

#218 is the foundation of the current TokaMaker integration:

```text
ODS machine state
    ↓
TokaMaker forward solver
    ↓
equilibrium
```

Reuse its geometry conversion, mesh/cache path, OpenFUSIONToolkit runtime, equilibrium output, gEQDSK/ODS conversion, and solver provenance where practical.

Do not create an unrelated second TokaMaker backend.

Conceptually:

```text
vaft.code.tokamaker
├── forward solve          # #218
└── reconstruction        # this issue
```

The exact package/API structure may be reconsidered during implementation.

## #232 — vessel / eddy-current / time-dependent TokaMaker

#232 owns vessel conductors, wall eigenmodes, quasi-static evolution, and vertical stability.

The first reconstruction benchmark should keep **passive-current physics separate from plasma reconstruction as far as practical**. Use a matched/fixed VEST passive-current state for the initial EFIT/TokaMaker comparison so that

```text
reconstruction-solver difference
```

is not immediately mixed with

```text
eddy-current model difference.
```

TokaMaker-native passive-current fitting or wall-mode reconstruction can be considered later in connection with #232 and the wall-mode work.

## #665 — TokaMaker forward-equilibrium robustness

#665 explicitly studies the forward problem:

```text
prescribed input
    ↓
forward GS solve
    ↓
local sensitivity / convergence
```

This issue studies the inverse reconstruction problem:

```text
measured diagnostics
    ↓
reconstructed equilibrium
```

Results from #665 may help interpret nonlinear failures, but the scopes and acceptance criteria remain independent.

## #663 / #664 — EFIT diagnostic information / identifiability

#663/#664 study how EFIT responds to diagnostic-family and weight changes.

This issue should first establish baseline reconstruction parity:

```text
same experimental state
        ↓
    EFIT
     vs
 TokaMaker
```

Only after that baseline is qualified should a minimal diagnostic-family comparison be performed.

A key scientific target is to distinguish:

```text
EFIT-specific weak direction
vs
VEST diagnostic-system weak direction
```

This is especially relevant for diamagnetic flux, which appears locally weak near nominal EFIT weighting but can become influential under strong nonlinear reweighting in #663/#664.

## #666 — NICE reconstruction cross-validation

#666 addresses the same broad question with NICE, an algorithmically different PDE-constrained reconstruction solver.

This issue does not replace #666. Instead, it creates a second independent reconstruction path:

```text
                       EFIT
                 reconstruction baseline
                         |
             +-----------+-----------+
             |                       |
             v                       v
        TokaMaker                   NICE
 Picard GS + reconstruction   Newton/SQP PDE-constrained
```

Longer term, VAFT should support matched comparisons among:

```text
EFIT
vs
TokaMaker
vs
NICE
```

The experience from #666 should also be retained explicitly:

```text
adapter executes
!=
diagnostic operator is correct
!=
scientific reconstruction converges
```

Forward/synthetic diagnostic correctness should therefore be checked before interpreting experimental reconstruction differences as solver physics.

## #683 — EFIT convergence-recovery workflow

#683 asks:

```text
How robustly can EFIT itself be executed
using warm starts / continuation / retry?
```

This issue asks:

```text
Can an independent reconstruction formulation
recover the same experimental state?
```

If TokaMaker succeeds where EFIT fails, that does not automatically justify EFIT replacement. If both fail, investigate common input-state, diagnostic-consistency, and inverse-problem limitations first.

## #525 — generic reconstruction-source comparison

#525 proposes solver-independent comparison of equilibrium sources.

Where practical, TokaMaker reconstruction outputs from this issue should be consumable by that contract:

```text
EFIT ODS --------┐
TokaMaker ODS ---+--> generic reconstruction comparison
NICE ODS --------┘
```

Avoid building a parallel TokaMaker-only equilibrium-comparison framework.

## #541 — canonical VEST reference lineage

#541 already places TokaMaker as one equilibrium-model comparison branch in the canonical VEST reference lineage.

This issue extends that role from

```text
forward equilibrium comparison
```

to

```text
experimental reconstruction comparison.
```

Completion of the full #541 reference bundle should not be a prerequisite for this initial implementation.

---

# 1. Reconstruction API

Add a reconstruction-specific interface under the existing TokaMaker integration.

A possible API is:

```python
TokaMakerReconstructionConfig
TokaMakerReconstructionInputs
TokaMakerReconstructionResult

prepare_tokamaker_reconstruction(...)
run_tokamaker_reconstruction(...)
collect_tokamaker_reconstruction(...)
```

These names are illustrative only. If the current adapter architecture supports a cleaner extension of existing types/functions, prefer that design.

Forward solving and reconstruction should share geometry/runtime infrastructure while retaining distinct scientific semantics.

---

# 2. Diagnostic mapping

Initial supported reconstruction constraints should include:

```text
plasma current
flux loops
B-pol / Mirnov probes
diamagnetic flux
```

TokaMaker-native coil-current constraints may also be included in the benchmark configuration where scientifically useful.

For every mapped diagnostic/constraint, preserve as much of the following as available:

```text
ODS source path/index
channel name
geometry / orientation
measured value
measurement error / uncertainty
enabled state
normalization
native weighting semantics
```

Do **not** translate the EFIT k-file into TokaMaker input.

The intended source relationship is:

```text
canonical ODS
   ├──> EFIT input
   └──> TokaMaker input
```

so both solvers consume the same physical state through independent solver-specific adapters.

---

# 3. Diamagnetic-flux mapping

Diamagnetic flux is explicitly **in scope** for this reconstruction work.

However, unlike local magnetic probes, cross-code equivalence is not guaranteed by geometry mapping alone. Before using it as an experimental reconstruction constraint, verify the semantic mapping between VEST and TokaMaker.

At minimum document and test:

```text
TokaMaker DFlux physical definition
VEST diamagnetic-loop processed quantity
sign convention
units
toroidal-field / vacuum reference
offset / baseline treatment
uncertainty definition
time alignment
```

Where practical, first check forward consistency:

```text
known equilibrium
    ↓
TokaMaker predicted DFlux
    ↓
VAFT / EFIT-side corresponding quantity
```

Then enable the experimental DFlux constraint.

A reasonable staged path is:

```text
Ip + flux loops + B-pol
        ↓
baseline magnetic reconstruction
        ↓
validate DFlux semantics
        ↓
add diamagnetic flux
        ↓
full supported magnetic reconstruction
```

This staging does **not** imply that diamagnetic flux is secondary. It isolates the convention-sensitive global pressure constraint before attributing cross-solver discrepancies to reconstruction physics.

---

# 4. Weight / uncertainty semantics

Do not equate raw EFIT `FWT` values numerically with TokaMaker-native weights.

Use a common physical comparison based, where possible, on normalized residuals:

$$
r_i =
\frac{y_i^{\mathrm{calc}}-y_i^{\mathrm{meas}}}{\sigma_i}.
$$

Preserve where possible:

```text
measured
reconstructed
error / sigma
native weight
normalized residual
chi-square contribution
```

This separates:

```text
solver-native weighting
```

from

```text
physical diagnostic agreement.
```

Apply the same principle to diamagnetic flux.

---

# 5. Passive-current treatment

For the first matched EFIT/TokaMaker comparison, keep passive-current treatment explicit and as closely matched as practical.

The intent is approximately:

$$
I_{\mathrm{passive}}^{\mathrm{TokaMaker}}
\approx
I_{\mathrm{passive}}^{\mathrm{EFIT}}.
$$

Do not simultaneously introduce both

```text
plasma-profile reconstruction
+
unknown passive-current modes
```

in the baseline study.

TokaMaker-native wall-current fitting may be considered after baseline reconstruction parity is established.

---

# 6. Profile reconstruction

Use the current native TokaMaker reconstruction capabilities to constrain, where supported:

```text
pressure-related profile parameters
FF' / current-related profile parameters
```

The implementing agent should re-audit the current upstream reconstruction parameterization and document the actual supported degrees of freedom.

Do not compare native EFIT and TokaMaker basis coefficients directly when their parameterizations differ.

Prefer physical comparisons on normalized flux:

```text
p(psi_N)
p'(psi_N)
FF'(psi_N)
j_phi
q
```

---

# 7. Baseline reference reconstruction

First establish an end-to-end reconstruction on **one well-behaved VEST reference slice**.

Do not make the difficult #666 case at 41672/331 ms the mandatory first baseline.

Recommended ordering:

```text
well-behaved baseline
        ↓
diagnostic forward validation
        ↓
baseline TokaMaker reconstruction
        ↓
EFIT parity
        ↓
DFlux-enabled reconstruction
        ↓
difficult cases
```

The implementing agent may select a better stable reference slice based on the current repository and available reference data.

---

# 8. EFIT parity comparison

For the same experimental state, compare EFIT and TokaMaker at minimum in the following categories.

## Diagnostic fit

- plasma-current residual;
- flux-loop residuals;
- B-pol residuals;
- diamagnetic-flux residual when enabled;
- total normalized diagnostic cost;
- family-resolved cost.

## Geometry

- magnetic axis;
- LCFS RMS displacement;
- maximum boundary displacement;
- area;
- volume;
- elongation / triangularity.

## Global quantities

- `beta_p`;
- `li`;
- `q95`;
- stored energy where definitions are compatible.

## Profiles

- pressure;
- `p'`;
- `FF'`;
- `j_phi`;
- `q`.

## Numerical behavior

- converged / failed;
- nonlinear iteration count;
- reconstruction iteration count;
- final residual;
- runtime;
- initialization provenance.

---

# 9. Difficult-case comparison

After baseline reconstruction is validated, reuse a small number of difficult cases already identified in #663/#664/#666.

Explicitly distinguish:

```text
EFIT fails / TokaMaker succeeds
EFIT succeeds / TokaMaker fails
both succeed on similar branch
both succeed on different branches
both fail
```

Interpret conservatively.

### EFIT fails / TokaMaker succeeds

Raises the possibility of EFIT-specific iteration, parameterization, or weighting limitations.

### Both fail

Prioritize common input-state, diagnostic inconsistency, or inverse-problem difficulty.

### Different branches

Compare initialization, profile basis, objective construction, regularization, and diagnostic normalization before making physical claims.

Do not treat this as a simple solver ranking exercise.

---

# 10. Minimal diagnostic-family comparison

Only after baseline parity is established, test a minimal family progression such as:

```text
Core / Ip baseline

Core + flux loops

Core + B-pol

Core + flux loops + B-pol

Core + diamagnetic flux

Full supported magnetics
    = Ip
    + flux loops
    + B-pol
    + diamagnetic flux
```

The exact family definitions should be aligned with the current EFIT constraint contract and #663/#664 during implementation.

This is **not** a production weight-optimization study.

The scientific question is:

> Do diagnostic families that appear weakly identified in EFIT show a similar information pattern in TokaMaker?

In particular, test whether the EFIT behavior of diamagnetic flux—locally weak near nominal weighting but nonlinear under strong reweighting—has an analogue in TokaMaker.

A full shared Jacobian/SVD/Fisher-information abstraction is not required for completion.

---

# 11. Result and provenance

Preserve, where practical:

```text
solver / OpenFUSIONToolkit revision
VAFT revision

input ODS identity
geometry identity

diagnostic channel set
diagnostic values
errors / uncertainties
native weights

DFlux definition / mapping provenance

passive-current state

profile parameterization
initialization
solver tolerances

process success
scientific convergence
iteration count
final cost / residual

measured vs reconstructed diagnostic table
family-resolved residuals

equilibrium output
logs / warnings
```

Do not classify a generated equilibrium object or g-file as a scientifically accepted reconstruction solely because the process completed.

---

# 12. Validation hierarchy

Recommended sequence:

```text
current upstream TokaMaker reconstruction example
        ↓
re-audit current VAFT / upstream API
        ↓
VAFT diagnostic mapping
        ↓
synthetic known-equilibrium reconstruction
        ↓
fixed-equilibrium forward diagnostic validation
        ↓
one stable VEST magnetic reconstruction
        ↓
DFlux semantic validation
        ↓
DFlux-enabled VEST reconstruction
        ↓
matched EFIT comparison
        ↓
difficult VEST cases
        ↓
minimal family sensitivity
```

The exact ordering may be changed if the current code/upstream API justifies it.

Do not interpret experimental reconstruction discrepancies as solver-physics differences before forward diagnostic correctness is established.

---

# Out of scope

This issue does not require:

- reimplementing the TokaMaker forward solver;
- modifying the TokaMaker Picard solver itself;
- adding Newton / Newton-Krylov GS iteration;
- time-dependent reconstruction;
- self-consistent eddy-current evolution;
- simultaneous passive-current eigenmode fitting in the baseline study;
- MSE / polarimetry reconstruction;
- full kinetic equilibrium reconstruction;
- broad EFIT weight scans;
- a shared Fisher-information / full-Jacobian framework;
- automatic replacement of production EFIT;
- Snakemake/FileDB production-stage promotion;
- database-wide reconstruction campaigns.

**Diamagnetic flux is not out of scope.** Its mapping and constraint use should be qualified after the initial magnetic baseline.

---

# Acceptance criteria

- [ ] Re-audit the current VAFT/TokaMaker/upstream reconstruction API before implementation and revise implementation details where justified.
- [ ] Any implementation redesign preserves the scientific comparison contract described above.
- [ ] Add reconstruction capability without duplicating the existing #218 forward adapter.
- [ ] Generate plasma-current, flux-loop, and B-pol/Mirnov constraints independently from the canonical ODS.
- [ ] Validate VEST ↔ TokaMaker diamagnetic-flux semantics, including definition, sign, units, baseline/reference treatment, time alignment, and uncertainty.
- [ ] Support qualified diamagnetic flux as a TokaMaker reconstruction constraint.
- [ ] Preserve diagnostic value, uncertainty, native-weight, and normalized-residual semantics separately.
- [ ] Keep passive-current treatment explicit and provenance-bearing in the initial EFIT comparison.
- [ ] Reconstruct at least one well-behaved VEST slice reproducibly.
- [ ] Convert the TokaMaker reconstruction result to the canonical equilibrium representation used by VAFT.
- [ ] Distinguish process success from scientific convergence.
- [ ] Perform a matched EFIT/TokaMaker comparison using the same physical diagnostic state.
- [ ] Compare diagnostic residuals, axis, LCFS, global quantities, and physical profiles.
- [ ] Compare physical normalized-flux profiles rather than solver-native coefficients where parameterizations differ.
- [ ] Test at least one existing difficult EFIT case in TokaMaker after baseline validation.
- [ ] Do not classify a different-branch result as ordinary reconstruction success.
- [ ] After baseline parity, perform at least one flux-loop, B-pol, and diamagnetic-flux family-addition comparison.
- [ ] Define explicitly what `Full` means and whether diamagnetic flux is included.
- [ ] Produce outputs compatible with the #525-style generic reconstruction comparison where practical.
- [ ] Leave existing EFIT and TokaMaker production defaults unchanged.

---

# Completion condition

After this issue, VAFT should clearly distinguish:

```text
TokaMaker forward
    prescribed state -> equilibrium

TokaMaker reconstruction
    measured diagnostics -> equilibrium

EFIT reconstruction
    measured diagnostics -> equilibrium
```

For at least one VEST state, the following comparison should be possible:

```text
same machine state
same passive-current treatment
same physical diagnostic state
    |
    +-- Ip
    +-- flux loops
    +-- B-pol
    +-- diamagnetic flux where qualified
    |
    v
 EFIT              TokaMaker
    \                /
     \              /
      v            v
solver-independent equilibrium comparison
```

Longer term, NICE should form a third branch:

```text
                 VEST diagnostic state
                         |
          +--------------+--------------+
          |              |              |
          v              v              v
        EFIT         TokaMaker         NICE
          |              |              |
          +--------------+--------------+
                         |
                         v
           solver-independent comparison
```

The long-term scientific role is therefore to move VAFT beyond validating one equilibrium code and instead test:

> **How consistently do different reconstruction formulations select a physical equilibrium from the same experimental information?**

Uh oh!

[TokaMaker] Add magnetic-diagnostic reconstruction and EFIT cross-validation #685

Description

Summary

Implementation-plan status: re-audit before coding

Relationship to existing VAFT issues

#218 — TokaMaker forward free-boundary adapter

#232 — vessel / eddy-current / time-dependent TokaMaker

#665 — TokaMaker forward-equilibrium robustness

#663 / #664 — EFIT diagnostic information / identifiability

#666 — NICE reconstruction cross-validation

#683 — EFIT convergence-recovery workflow

#525 — generic reconstruction-source comparison

#541 — canonical VEST reference lineage

1. Reconstruction API

2. Diagnostic mapping

3. Diamagnetic-flux mapping

4. Weight / uncertainty semantics

5. Passive-current treatment

6. Profile reconstruction

7. Baseline reference reconstruction

8. EFIT parity comparison

Diagnostic fit

Geometry

Global quantities

Profiles

Numerical behavior

9. Difficult-case comparison

EFIT fails / TokaMaker succeeds

Both fail

Different branches

10. Minimal diagnostic-family comparison

11. Result and provenance

12. Validation hierarchy

Out of scope

Acceptance criteria

Completion condition

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions