[ad-15] expose public pyGVEC energy and residual API

[krystophny]

Stage: Python derivative API
Source language: Fortran, Python
Difficulty: medium
Runner tier: medium
Labels: difficulty:medium, stack:enzyme-ad, enhancement
Manuals to read first:

• src/pygvec/state.F90, f90wrap state API
• python/gvec/core/state.py, public State methods
• test-CI/unit-pygvec/test_state.py, Python API style
  Depends on: [ad-04] expose fixed-boundary and free-DOF masks #5, [ad-11] validate Enzyme gradient against finite differences and raw force #12

Goal

Expose stable Python methods for flat state access, scalar energy, raw gradient or residual, and documented sign convention.

Files to edit

• src/pygvec/state.F90: add get/set q, energy-from-q, and raw residual wrappers.
• python/gvec/core/state.py: add public methods with NumPy arrays and shape checks.
• test-CI/unit-pygvec/test_ad_public_api.py: NEW, API behavior tests.

Syntax or behavior to implement

• REQ-AD15-001: Given a State, get_q() returns a copy in the shared flat layout.
• REQ-AD15-002: Given a valid flat vector, set_q(q) updates the current solution and rejects wrong lengths.
• REQ-AD15-003: Given q, energy(q) and raw_residual(q) use the same sign convention documented in the method docstring.
• REQ-AD15-004: When Enzyme is unavailable, raw_gradient(q) raises a clear unsupported-mode error unless a manual raw-force fallback is requested.

Scaffold

q = state.get_q()
energy = state.energy(q)
residual = state.raw_residual(q)
assert residual.shape == q.shape

Positive fixtures to add

• test_public_api_roundtrip_q: set/get preserves the state vector.
• test_public_api_residual_shape: residual length equals q length.

Negative fixtures to add

• Wrong-length q inputs must raise ValueError before entering Fortran.

Makefile target

No Makefile target. Use pytest.

Success criteria

uv run pytest test-CI/unit-pygvec/test_ad_public_api.py -q

Non-goals

• Do not add optimizer algorithms.
• Do not expose private module globals directly.

Verification

uv run pytest test-CI/unit-pygvec/test_ad_public_api.py -q

Reference

VMEC++ exposes state and raw forces to Python in proximafusion/vmecpp#577.