[ad-11] validate Enzyme gradient against finite differences and raw force

[krystophny]

Stage: Derivative validation
Source language: Fortran, Python
Difficulty: hard
Runner tier: hard
Labels: difficulty:hard, stack:enzyme-ad, enhancement
Manuals to read first:

• test-CI/unit-pygvec/ad_checks.py, finite-difference checker
• src/functionals/mhd3d/mhd3d_evalfunc.F90, raw force sign
• docs/user/theory.md, first variation of the MHD energy
  Depends on: [ad-06] test raw force transforms back to the solver force #7, [ad-08] add finite-difference gradient checker for EvalEnergyFromQ #9, [ad-10] add Enzyme dW/dq wrapper #11

Goal

Lock the first useful AD result: Enzyme dW/dq agrees with finite differences and with -EvalForceRawProjected on free DOFs for the small fixed-RZ case.

Files to edit

• test-CI/unit-pygvec/test_ad_enzyme_gradient.py: NEW, Python-facing validation if the wrapper is exposed.
• test-CI/enzyme/test_energy_gradient_driver.F90: NEW or extended, direct Fortran validation if Python exposure is not ready.
• src/pygvec/state.F90: expose the Enzyme gradient only if needed for the test.

Syntax or behavior to implement

• REQ-AD11-001: Given selected free X1, X2, and LA indices, Enzyme components match centered finite differences within a stated tolerance.
• REQ-AD11-002: Given the raw force path, dW/dq matches -raw_force on the same free indices.
• REQ-AD11-003: When boundary-constrained indices are sampled, the test either projects them or records why they are excluded.

Scaffold

grad = state.energy_gradient_enzyme()
raw = state.raw_projected_force()
for i in sample_free_indices(layout):
    fd = centered_component(state.energy_from_q, q, i, h=1e-6)
    assert_allclose(grad[i], fd, rtol=1e-5, atol=1e-7)
    assert_allclose(grad[i], -raw[i], rtol=1e-5, atol=1e-7)

Positive fixtures to add

• test_enzyme_gradient_matches_fd: samples all three variables.
• test_enzyme_gradient_matches_raw_force: locks the sign convention.

Negative fixtures to add

• Do not skip LA; it is part of the equilibrium state.

Makefile target

No Makefile target. Use CTest or pytest depending on exposure.

Success criteria

ctest --test-dir build-ad10 -R gvec_enzyme_energy_gradient --output-on-failure

Non-goals

• Do not test all hmaps in this PR.
• Do not add HVPs.

Verification

ctest --test-dir build-ad10 -R gvec_enzyme_energy_gradient --output-on-failure

Reference

VMEC++ validates exact derivatives against finite differences before using them in solvers in proximafusion/vmecpp#573.