Add reusable coil optimization geometry interfaces

[rogeriojorge]

Summary

• expose coil-shape/current names in the exact order of Curves.dofs and Coils.dofs, with functional differentiable with_dofs(...) updates
• add reusable differentiable coil-coil and coil-surface clearance objectives, VMEC-boundary conversion, SIMSOPT import, and VTK export
• add BiotSavart.b_cyl(R, phi, Z) so VMEX/NESTOR can evaluate moving-boundary coil fields and retain coil derivatives without an mgrid file
• add trace_field_lines(...) with explicit toroidal-angle or physical-arclength coverage, progress reporting, bounded stopping events, and robust multi-device placement
• replace the older 2.5%-beta demonstration fixture with an independently optimized 0.5%-beta QA/bootstrap equilibrium and matched coil set

The additions reuse ESSOS's existing coil, field, surface, and Tracing representations. They remove repeated indexing and tracing setup from coupled VMEX/ESSOS examples without introducing a parallel abstraction.

Low-beta finite-pressure coil example

examples/coil_optimization/optimize_coils_finite_beta_vmex.py belongs in ESSOS because ESSOS owns the coil degrees of freedom and engineering objectives. VMEX supplies a prescribed fixed-boundary 0.5%-beta QA/bootstrap equilibrium; virtual casing supplies the plasma-current field and total-pressure interface condition. The script shows the scalar, exact JAX gradient, and SciPy adapter explicitly.

The coil-current orientation is selected by alignment with the VMEX total field, avoiding the globally reversed near-solution admitted by squared residuals. In the representative 120-iteration CPU run, cost fell from 58.32 to 0.01772 and the interface reached mean/RMS/max B.n/B of 0.094%/0.118%/0.548%, normalized total-pressure-jump RMS 1.14e-3, approximately 5.02 m coils, and maximum curvature 5.18 1/m. A normalized [-1,1] box stalled near 1.7% maximum B.n/B; the documented [-3,3] bound is deliberate for this independent vacuum seed.

Validation

• complete ESSOS suite: 107 passed, 1 expected failure in 48 s
• changed-line coverage: 95% against origin/main; unreachable field-line energy/velocity branches were removed rather than tested as fictitious physics
• b_cyl is checked against Cartesian Biot--Savart values and differentiated with JAX
• tracing tests cover parameterization selection, arclength invariance, exact toroidal coverage, stopping/fill behavior, branch-safe Poincare extraction, and input validation
• the generated low-beta coil JSON is byte-identical to the fixture consumed by VMEX
• the finite-beta optimization was run end to end with independent interface and engineering diagnostics
• git diff --check passes

The repository-wide style backlog is intentionally outside this PR; existing source conventions are retained rather than applying an unrelated bulk reformat.

[codecov]

Codecov Report

❌ Patch coverage is 94.02390% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
essos/dynamics.py	90.50%	9 Missing and 6 partials ⚠️

Files with missing lines	Coverage Δ
essos/coils.py	50.58% <100.00%> (+4.68%)	⬆️
essos/fields.py	42.22% <100.00%> (+4.11%)	⬆️
essos/surfaces.py	58.98% <100.00%> (+31.78%)	⬆️
essos/dynamics.py	56.19% <90.50%> (+12.49%)	⬆️