Part I of force_and_torque_overhaul breakup: Update of permanent magnet helpers, moving coil optimization functionality to its own helper file

[akaptano]

I have separated out a substantial piece of PR #509 that relates to adding useful coil optimization functionality to its own util file, as well as reducing the time spent in running the permanent magnet examples, and otherwise reorganizing some functions between the permanent magnet and coil helper functions in utils/.

I would like to get this merged in main before continuing onwards to Part II. Note that code coverage is not perfect only because I have some functionality waiting to be tested once the force and torque terms are back in there.

[codecov]

Codecov Report

❌ Patch coverage is 96.04651% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.84%. Comparing base (8bd454c) to head (a7dc869).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
...simsopt/util/coil_optimization_helper_functions.py	95.96%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #558      +/-   ##
==========================================
+ Coverage   92.56%   92.84%   +0.27%     
==========================================
  Files          83       84       +1     
  Lines       16229    16509     +280     
==========================================
+ Hits        15023    15327     +304     
+ Misses       1206     1182      -24     

Flag	Coverage Δ
unittests	92.84% <96.04%> (+0.27%)	⬆️

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

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[akaptano]

@mishapadidar Friendly reminder!

[mishapadidar]

Thanks for the review reminder!

I am a still a bit confused on the use case of coil_optimization_helper_functions. The module holds mostly convenience functions for building QFMs or running stage 2 optimization. Currently, some of the functions seem to be built with a particular use case or run paradigm in mind. If these features are intended to be user facing, it would be beneficial to make the functions general enough, so users can get the most out of them. Part of my confusion with these functions is that they seem very specific how they are intended to be used or run. For example, there are a few functions to perform optimizations of various types i.e. initial_optimizations_QH, initial_optimizations. It would be best to consolidate these as much as possible.

A general concern I have with the convenience functions is that some of them are designed for a particular workflow rather than being designed for expanding functionality. We want to build our library to expose building blocks, rather than particular workflows. Typically, we relegate workflows to example scripts or tutorials, since adding them to the code breaks consistency: why should some workflows get “special” shortcuts while others don’t. On the other hand, some routines are highly used and might deserve a special convenience function. For example, vacuum stage two optimization solves a common problem. In that sense, maybe it makes sense to package it up. However, when doing so, the method should be built in the same style as a modular "building block" (BoozerSurface is a good example of this).

Another point is that some of the functions write files out, without explicitly stating that they will do so in the documentation. See principle of least astonishment. In general, we should have two functions: one to do the computation, and another to write the files. Having both in one may be confusing to users, and makes testing/maintainability more difficult.

My final comment is that some of these functions may belong in other modules. For example, make_qfm could be in field or geo. Why not just move them now.

For concrete to-dos:

• Lets try to consolidate the various functions that run stage two as much as possible, and remove any that are too "use-case specific".
• Try to avoid writing files unless.
• Move files from the helpers to a better home when possible.

[mishapadidar]

Why so much saving/loading?

[akaptano]

Allows one to continue from previous optimization results

[akaptano]

@mishapadidar Just made the recommended changes. Didn't move anything to geo/field yet since I'm not sure of the best choice for this. Consolidated and generalized the functions as you mentioned. I think the benefit of functions like "vacuum_stage_II_optimization" is that in principle we can stop having everyone rewrite their own bespoke coil optimization code and just reuse these helper functions. It would be nice in SIMSOPT if run scripts were more like 20 lines of python code instead of 200, much of which is duplicated (often without thinking about it) from previous scripts.

[akaptano]

As far as I can tell, failing tests seem to be a SPEC installation problem