Add soft-plused second adiabatic invariant derivative and SoftConnectivity objectives

[a957924278]

This PR introduces differentiable optimization objectives for stellarator omnigenity based on the second adiabatic invariant (bounce action) $J^*$ along Boozer magnetic field lines, as derived in Chen et al. (2026).

Key Contributions:

1. Analytical $dJ^*/d\alpha$ Objective (SecondAdiabaticInvariantAlphaDerivative):
   • Implements a smooth softplus-regularized cutoff at bounce points to resolve the square-root endpoint singularity $\sqrt{E - \mu B}$, enabling exact, stable reverse-mode AD gradients.
   • Evaluates the analytical derivative integrand directly without finite-difference approximations.
2. Soft Connectivity Penalty (SoftConnectivity):
   • Enforces clean, single-well magnetic field structure along Boozer field lines without spurious secondary wells or trapped-branch bifurcations.
   • Accommodates periodic cubic spline parameterizations for dynamic well minimum and maximum tracking.
3. Toroidal Extrema Spline (SplineZeta):
   • An Optimizable parameterization class managing control points for the low-field valley ($\zeta_{\rm min}(\alpha)$) and high-field seam ($\zeta_{\rm max}(\alpha)$) with optional stellarator symmetry mirroring.
4. Comprehensive Unit Tests (tests/test_second_adiabatic_invariant.py):
   • Covers analytical derivative accuracy, smooth log-sum-exp approximations, JVP/VJP consistency, spline knot serialization, and single-step joint equilibrium optimization.

---

References

• [1] Chen, H., Lu, Z., Xu, G., et al. (2026). "Direct Optimization of Stellarator Omnigenity from the Second Adiabatic Invariant." arXiv:2608.02418.

---

Checklist

• Code conforms to repository conventions and docstrings follow NumPy/Sphinx format.
• All new functions and classes have LaTeX formulas and literature references.
• Full unit and regression test suite added and passing locally (8/8 passed).
• Rebased on the latest upstream/master.

[github-actions]

Memory benchmark result

|               Test Name                |      %Δ      |    Master (MB)     |      PR (MB)       |    Δ (MB)    |    Time PR (s)     |  Time Master (s)   |
| -------------------------------------- | ------------ | ------------------ | ------------------ | ------------ | ------------------ | ------------------ |
  test_objective_jac_w7x                 |    0.10 %    |     4.252e+03      |     4.256e+03      |     4.04     |       32.37        |       29.04        |
  test_proximal_jac_w7x_with_eq_update   |   -0.55 %    |     6.850e+03      |     6.812e+03      |    -37.61    |       159.30       |       153.80       |
  test_proximal_freeb_jac                |   -0.12 %    |     1.356e+04      |     1.354e+04      |    -15.95    |       80.48        |       79.60        |
  test_proximal_freeb_jac_blocked        |   -0.30 %    |     7.888e+03      |     7.864e+03      |    -23.92    |       71.24        |       69.59        |
  test_proximal_freeb_jac_batched        |   -0.03 %    |     7.874e+03      |     7.872e+03      |    -2.30     |       69.80        |       69.70        |
  test_proximal_jac_ripple               |   -1.29 %    |     3.794e+03      |     3.745e+03      |    -49.01    |       55.98        |       55.86        |
  test_proximal_jac_ripple_bounce1d      |    0.09 %    |     3.755e+02      |     3.758e+02      |     0.34     |        3.70        |        3.70        |
  test_eq_solve                          |    0.46 %    |     1.826e+03      |     1.834e+03      |     8.42     |       53.58        |       53.04        |
  test_objective_quadratic_flux_jac      |   -0.42 %    |     1.896e+03      |     1.888e+03      |    -7.94     |       34.92        |       35.04        |

For the memory plots, go to the summary of Memory Benchmarks workflow and download the artifact.

[codecov]

Codecov Report

❌ Patch coverage is 98.63014% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.38%. Comparing base (fe84bd1) to head (c94a43e).

Files with missing lines	Patch %	Lines
desc/objectives/_omnigenity.py	95.78%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2309      +/-   ##
==========================================
+ Coverage   94.33%   94.38%   +0.04%     
==========================================
  Files         101      101              
  Lines       29055    29344     +289     
==========================================
+ Hits        27410    27695     +285     
- Misses       1645     1649       +4     

Files with missing lines	Coverage Δ
desc/compute/_omnigenity.py	99.73% <100.00%> (+0.13%)	⬆️
desc/magnetic_fields/__init__.py	100.00% <ø> (ø)
desc/magnetic_fields/_core.py	96.08% <100.00%> (+0.31%)	⬆️
desc/objectives/__init__.py	100.00% <ø> (ø)
desc/objectives/_omnigenity.py	96.72% <95.78%> (-0.33%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.