Expose exact pyGVEC energy gradient

[krystophny]

Closes #16.

Expose the optimizer-facing pyGVEC surface:

• State.set_q(q) updates the shared flat state with boundary validation.
• State.energy(q) evaluates MHD energy at a supplied flat vector.
• State.raw_residual(q) returns raw projected force without changing the loaded state.
• State.energy_gradient(q) uses the production Enzyme gradient when available.
• State.raw_gradient(q) remains as a compatibility delegate.
• Enzyme-off and unsupported-map builds raise UnsupportedFeatureError for exact requests; the explicit raw-force fallback remains available.
• A separate Fortran adapter caches the fixed-map context for repeated optimizer calls.

Verification

Failing before

$ python -m pytest test-CI/unit-pygvec/test_ad_public_api.py -q
F.FFFFF
AttributeError: 'State' object has no attribute 'energy'
AttributeError: 'State' object has no attribute 'raw_gradient'
AttributeError: 'State' object has no attribute 'raw_residual'
AttributeError: 'State' object has no attribute 'set_q'
6 failed, 1 passed

Passing after

Enzyme off:

$ python -m pytest -q test-CI/unit-pygvec/test_ad_public_api.py
........                                                                 [100%]
8 passed in 5.49s

exact_ad_available False
UnsupportedFeatureError Exact energy gradients require USE_ENZYME=ON and a fixed RZ or cylindrical h-map build.

Fixed-RZ Enzyme build with LLVM/Flang 22.1.6:

$ python -m pytest -q test-CI/unit-pygvec/test_ad_public_api.py
........                                                                 [100%]
8 passed in 0.96s

exact_ad_available True
gradient_shape (20,)
gradient_norm 26.115398458256784

$ fo
Static: OK (100 modules, 100 changed, 100 affected)
Build: OK
Tests: skipped, no affected tests
Lint: OK
All stages passed (.5s)

The isolated Flang Python build used a source-built f90wrap so its derived-type pointer metadata matched the selected Fortran compiler.

[krystophny]

Fixed AD-15 by adding the public pyGVEC flat-q optimizer API, including set_q, energy(q), raw_residual(q), and an explicit raw_gradient fallback mode. Also fixed typed conversion for empty-region Fortran UnsupportedFeatureError messages so unsupported fixed-RZ wrappers skip cleanly in non-RZ builds. Verified with the focused public API test and adjacent AD pyGVEC tests.