Propose shipping Enzyme-enabled kernels in pip wheels (follow-up to #710)

[Copilot]

#710 wires an Enzyme-derived exact JVP/VJP of the force kernel into vmecpp_core behind -DVMECPP_ENABLE_ENZYME=ON, but that flag is never set in the cibuildwheel-built pip wheels — it's only exercised by a dedicated CI job with its own from-scratch Clang/LLVM + Enzyme toolchain. This adds a design proposal for closing that gap.

Changes

• docs/enzyme_wheel_packaging.md: proposal doc covering
  • Reusing the existing CMake "prebuilt Enzyme object" mode (VMECPP_ENZYME_JVP_OBJECT/VMECPP_ENZYME_VJP_OBJECT) instead of installing Clang/LLVM/Enzyme inside manylinux/macOS cibuildwheel containers
  • Compiling the two Enzyme translation units in a small, separate, cacheable CI job per wheel target, then feeding the resulting .o files into the normal wheel build via CMAKE_ARGS
  • Why this keeps every other translation unit compiled exactly as today, so non-adjoint users see no change to the code they exercise, and why Enzyme introduces no new runtime dependency (it only runs at build time)
  • Concrete checks for no performance regression: symbol/disassembly diffing of unaffected translation units, and extending the existing exact-HVP benchmark with a forward-solve timing comparison run against an actual built wheel
  • Open questions: which wheel targets to prioritize, prebuilt-object staleness/versioning, Windows being out of scope for now
• docs/index.md: links the new doc from the toctree

Scope

This is a design proposal only, not an implementation. The actual toolchain and CI wiring is substantial, cross-platform work intended to be done and validated incrementally in follow-up PRs, building on this proposal.

[jurasic-pf]

@copilot Follow the implementation proposal added in this PR

[Copilot]

@copilot Follow the implementation proposal added in this PR

Implemented in .github/workflows/build_enzyme_wheels.yaml (commits 4f7c3da / follow-up): a new job builds the prebuilt Enzyme JVP/VJP objects (Linux via apt.llvm.org, macOS via Homebrew LLVM, since AppleClang can't load an upstream ClangEnzyme plugin) and feeds them into cibuildwheel via CMAKE_ARGS's prebuilt-object mode, producing smoke-tested Enzyme-enabled wheels for linux-x86_64/macos-arm64/macos-x86_64 without changing the compiler or flags for any other translation unit. It's kept as a separate, workflow_dispatch-triggered workflow rather than wired into pypi_publish.yml's release trigger yet, since I couldn't fully validate manylinux-container/macOS-runner behavior in this session — remaining gaps (aarch64, in-container glibc-floor matching, automated perf-regression checks, merging into the release pipeline) are tracked in the updated docs/enzyme_wheel_packaging.md.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: b08a0db	Previous: 72d0c76	Ratio
benchmarks/test_benchmarks.py::test_bench_simsopt_adjoint_gradient	5.741460991999986 seconds (stddev: 0)	3.6532505499999957 seconds (stddev: 0)	1.57

This comment was automatically generated by workflow using github-action-benchmark.