Validate Enzyme gradient for cyl hmap

[krystophny]

Summary

• add a fixed-cyl flat MHD energy kernel beside the existing fixed-RZ kernel
• expose generic flat-kernel context and hmap metadata wrappers for RZ/cyl
• extend the Enzyme AD fixture gradient test to select the matching RZ or cyl fixture and compare against finite differences
• register the AD fixture only for flat hmaps currently supported by the exported context

Closes #13.

Hmap Scope

This PR covers GVEC_FIX_HMAP=RZ and GVEC_FIX_HMAP=cyl.

The remaining fixed hmaps need separate flat contexts before the same Enzyme fixture can cover them:

• axisNB: the metric depends on zeta-dependent axis and frame data such as X0, T, N, B, frame derivatives, and cross products held in the axisNB auxvar, including data loaded from the hmap NetCDF input.
• frenet: the metric depends on the Frenet auxiliary arrays lp, kappa, tau, sigma, their derivatives, and the zeta-dependent X0/T/N/B frame, including frame-switch handling.
• knot: the metric is not the RZ/cyl scalar specialization; it needs the knot parameters and zeta-dependent trigonometric metric terms exported to a separate flat kernel.

Verification

Test fails before fix

Command, run at the parent commit:

rm -rf /tmp/gvec-ad12-before /tmp/gvec-ad12-before-cyl
git worktree add --detach /tmp/gvec-ad12-before HEAD^
cd /tmp/gvec-ad12-before
. "$HOME/code/activate.sh"
cmake -S . -B /tmp/gvec-ad12-before-cyl -G Ninja \
  -DCMAKE_Fortran_COMPILER=flang-new \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=cyl \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF \
  -DUSE_ENZYME=ON
cmake --build /tmp/gvec-ad12-before-cyl --target gvec_enzyme_ad_fixture_gradient -j$(nproc)
ctest --test-dir /tmp/gvec-ad12-before-cyl -R '^gvec_enzyme_ad_fixture_gradient$' --output-on-failure

Output excerpt:

Reading from file "test-CI/examples/ad_elliptok_lowres/parameter.ini"
which_hmap | 1 | *CUSTOM |
Message: initialize.init-MHD3D.hmap | RuntimeError | FIXED HMAP TO PP_WHICH_HMAP AT COMPILE TIME, hmap choice is therefore not compatible!
0% tests passed, 1 tests failed out of 1

Test passes after fix

Command:

rm -rf /tmp/gvec-ad12-cyl
. "$HOME/code/activate.sh"
cmake -S . -B /tmp/gvec-ad12-cyl -G Ninja \
  -DCMAKE_Fortran_COMPILER=flang-new \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=cyl \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF \
  -DUSE_ENZYME=ON
cmake --build /tmp/gvec-ad12-cyl --target gvec_enzyme_ad_fixture_gradient -j$(nproc)
ctest --test-dir /tmp/gvec-ad12-cyl -R '^gvec_enzyme_ad_fixture_gradient$' --output-on-failure

Output:

1/1 Test #5: gvec_enzyme_ad_fixture_gradient ...   Passed    0.01 sec
100% tests passed, 0 tests failed out of 1

Command:

rm -rf /tmp/gvec-ad12-rz
. "$HOME/code/activate.sh"
cmake -S . -B /tmp/gvec-ad12-rz -G Ninja \
  -DCMAKE_Fortran_COMPILER=flang-new \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=RZ \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF \
  -DUSE_ENZYME=ON
cmake --build /tmp/gvec-ad12-rz --target \
  gvec_enzyme_smoke \
  gvec_enzyme_array_gradient \
  gvec_enzyme_rz_flat_gradient \
  gvec_enzyme_gvec_module_smoke \
  gvec_enzyme_ad_fixture_gradient \
  -j$(nproc)
ctest --test-dir /tmp/gvec-ad12-rz -R 'gvec_enzyme_(smoke|array_gradient|rz_flat_gradient|gvec_module_smoke|ad_fixture_gradient)' --output-on-failure

Output:

1/5 Test #1: gvec_enzyme_smoke .................   Passed    0.00 sec
2/5 Test #2: gvec_enzyme_array_gradient ........   Passed    0.00 sec
3/5 Test #3: gvec_enzyme_rz_flat_gradient ......   Passed    0.00 sec
4/5 Test #4: gvec_enzyme_gvec_module_smoke .....   Passed    0.00 sec
5/5 Test #5: gvec_enzyme_ad_fixture_gradient ...   Passed    0.01 sec
100% tests passed, 0 tests failed out of 5

Command:

rm -rf /tmp/gvec-ad12-gfortran-rz /tmp/gvec-ad12-gfortran-cyl
cmake -S . -B /tmp/gvec-ad12-gfortran-rz -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=RZ \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF
cmake --build /tmp/gvec-ad12-gfortran-rz -j$(nproc)
cmake -S . -B /tmp/gvec-ad12-gfortran-cyl -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=cyl \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF
cmake --build /tmp/gvec-ad12-gfortran-cyl -j$(nproc)

Output excerpts:

SUCCESS: GVEC BUILD COMPLETE!
SUCCESS: GVEC_POST BUILD COMPLETE!
SUCCESS: GVEC_POST BUILD COMPLETE!
SUCCESS: GVEC BUILD COMPLETE!

Command:

rm -rf /tmp/gvec-ad12-axisnb-reg
. "$HOME/code/activate.sh"
cmake -S . -B /tmp/gvec-ad12-axisnb-reg -G Ninja \
  -DCMAKE_Fortran_COMPILER=flang-new \
  -DCMAKE_BUILD_TYPE=Release \
  -DGVEC_FIX_HMAP=axisNB \
  -DUSE_OPENMP=OFF \
  -DLINK_GVEC_TO_NETCDF=OFF \
  -DUSE_ENZYME=ON
ctest --test-dir /tmp/gvec-ad12-axisnb-reg -N | rg 'gvec_enzyme_ad_fixture_gradient|Total Tests'

Output:

Total Tests: 11

Command:

git diff --check
fo

Output:

git diff --check: no output
fo: no Fortran project detected

[krystophny]

Fixed the cyl AD fixture failure here: the Enzyme fixture now compiles with the selected fixed hmap, uses a cyl parameter file for GVEC_FIX_HMAP=cyl, and differentiates the cyl flat energy kernel against finite differences.

The non-flat hmaps stay out of this fixture until their zeta-dependent hmap context is exported. The blockers are listed in the PR body for axisNB, frenet, and knot.