Single-stage optimization with spec: CoilSet, ReducedCoilSet and CoilNormalField (PR 2 of 2)

[smiet]

This PR adds new features, and enables the optimizations presented at the Simons' retreat and meeting, and available in preprint (https://arxiv.org/abs/2407.02097).

The main additions are:

class CoilSet

A helper class to handle a set of coil objects as a single object:

• convenience class
• provides helper methods for all the coil-related optimization targets
• serves as the base class for ReducedCoilSet
• allows the ReducedCoilSet and CoilNormalField to be implemented with minimal code duplication.

class ReducedCoilSet

Identical in use to CoilSet, but it's degrees-of-freedom are linear combinations of the coil degrees-of-freedom.

• Calculates its degrees-of-freedom by performing a singular-value-decomposition on an arbitrary user-provided mapping.
• Ability to re-calculate the reduced basis when changing the function or other relevant properties of the CoilSet.
• Removes some overdetermination inherent in direct-from-coil optimization.
• Reduces the dimensionality of the optimization problem, speeds up optimization.

class CoilNormalField

Identical in use to a NormalField and interfaces with SPEC, but has degrees-of-freedom specified by a CoilSet or ReducedCoilSet.

• Provides the normal field on a boundary in the SPEC conventions.
• Uses a cache to avoid redundant Fourier transformations.
• Handles both CoilSet and ReducedCoilSet, provides method to reduce the CoilSet using the mapping to SPEC input parameters (normal field Fourier components).

With these changes the functionality I describe in my preprint will be added to the simsopt master branch. I look forward to your suggestions to improve my code.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 90.15152% with 52 lines in your changes missing coverage. Please review.

Project coverage is 92.34%. Comparing base (c469350) to head (98b8661). Report is 23 commits behind head on master.

Files with missing lines	Patch %	Lines
src/simsopt/field/coilset.py	85.25%	50 Missing :warning:
src/simsopt/field/normal_field.py	99.30%	1 Missing :warning:
src/simsopt/geo/surfacerzfourier.py	97.29%	1 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #438      +/-   ##
==========================================
- Coverage   92.68%   92.34%   -0.34%     
==========================================
  Files          77       78       +1     
  Lines       13982    14503     +521     
==========================================
+ Hits        12959    13393     +434     
- Misses       1023     1110      +87     

Flag	Coverage Δ
unittests	92.34% <90.15%> (-0.34%)	:arrow_down:

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[smiet]

Sorry to push this, but could we move forward with this PR? All tests are now pasing (after the numpy2.0 speedbump), and the tests now cover all new code.

The only exception is a plotting utility function that I am not testing because not all runners have visualization capabilities, but I do think it's inclusion is valuable as a demonstration.

@landreman, @rogeriojorge @abaillod

[rogeriojorge]

Looks good to me. However, I'll let a day or two go by before accepting in case @landreman or @abaillod wants to add something here.

[rogeriojorge]

There's a conflict with the recent merge. Could you fix it @smiet? I'll merge in afterwords.

[rogeriojorge]

Merged