[ad-17] add finite-difference residual HVP fallback

[krystophny]

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

• python/gvec/core/state.py, public derivative API
• test-CI/unit-pygvec/ad_checks.py, finite-difference helpers
• test-CI/unit-pygvec/test_ad_public_api.py, residual tests
  Depends on: [ad-15] expose public pyGVEC energy and residual API #16

Goal

Add a finite-difference Hessian-vector product fallback over the public raw residual so Newton and adjoint plumbing can be built before exact Enzyme HVPs land.

Files to edit

• python/gvec/core/state.py: add hessian_vector_product(v, method="fd").
• test-CI/unit-pygvec/test_ad_hvp.py: NEW, HVP finite-difference behavior tests.

Syntax or behavior to implement

• REQ-AD17-001: Given a state and vector v, hessian_vector_product(v, method="fd") returns (F(q+eps v)-F(q-eps v))/(2 eps).
• REQ-AD17-002: Given a zero vector, the HVP returns a near-zero vector.
• REQ-AD17-003: When v has the wrong length, Python raises ValueError before changing state.

Scaffold

def hessian_vector_product(self, v, eps=1e-6, method="fd"):
    q0 = self.get_q()
    vp = np.asarray(v, dtype=float)
    return (self.raw_residual(q0 + eps * vp) - self.raw_residual(q0 - eps * vp)) / (2 * eps)

Positive fixtures to add

• test_fd_hvp_matches_residual_difference: checks the exact formula on the AD fixture.

Negative fixtures to add

• Do not use this finite-difference HVP as the final exact AD implementation.

Makefile target

No Makefile target. Use pytest.

Success criteria

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

Non-goals

• Do not add Enzyme HVPs.
• Do not solve Newton systems.

Verification

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

Reference

VMEC++ staged its second-order path with a finite-difference HVP in proximafusion/vmecpp#580.