New inverse stream map to accelerate convergence

[unalmis]

Inverse stream maps

• Significantly improves convergence of inverse stream maps. Resolves Choose stream s.t. the map to the moving mesh of field lines is trivial #1922 to my satisfaction.
• Truncation rule to remove aliasing error at the shortest wavelengths where the signal to noise ratio is lowest.
• Resolves Increase Y parameter for Heliotron (NFP=19) in effective ripple tutorial #1928 and increases default objective resolution for Y_B.
• Method to plot frequency spectrum of inverse stream map.

Improvements

• Check-pointing to increase speed and reduce memory consumption of reverse mode differentiation Checkpointing to reduce reverse mode AD memory usage #1347.
• Adds low_ram mode which is same speed and less memory for objective.compute, but slower for objective.grad since JAX is poor at iterative algorithms.
• Fully resolves Memory regression in bounce integrals #1864 by avoiding materialization of a large tensor in memory. Previously, we had closed the issue by adding nuffts as a workaround. The improvement here actually solves the JAX regression.
• Reuses some computations in identifying bounce points to make more efficient.
• Increase cache hits, fusing, and reduce floating point error in computing bounce points (very important for accurate integrals).
• Transforms an improper field line integral to one on a compact domain where the integrand is periodic to achieve faster convergence.
• Improves performance complexity of interp_to_argmin for Bounce2D from fourth order to spectral as required for Alpert quadrature.
• Resolves Use OOP for surface integrals with faster methods for tensor product grids #1389.

Usability

• Updates plotting utilities to accept kwargs as was needed for my article.
• Method to compute integrals over plasma volume and velocity space in batches is now added to the public API. People kept asking how to use this private function and also used it for their work, so better to make it public.
• Method to make adding new bounce integral objectives simpler. Private for developers only.
• Unifies default parameter setup to resolve Add comments about recommeded resolutions to docstrings #1898 for bounce integrals.
• Resolves Move some general interpolation functions into interpax #1388.

Bugs

• Fixes bug in test_compute_everything.
• Fixes inverse stream map convergence.
• spectral_reverse_bounce_supplement.pdf

Benchmarks

Just go to #2026 and run effective_ripple_profile.py. You will see the large performance improvement from master. The CI benchmarks do not reveal this because those benchmarks are essentially just noise. Note that, using the same parameter inputs, the resolution of this branch is also higher than master due to the faster convergence.

• If you set use_bounce1d=True on that script, you will run out of memory as expected since it is an inferior approach (as expected, you get the OOM in the jacobian before you compute a single bounce integral).
• If you set nufft_eps=0, you need 175 GB to run that script on master (you'll get an OOM and JAX will tell you it needs 175GB), but only 35 GB on this branch.
• Using nuffts, the script requires only 6.7 GB on this branch.

Examples

HELIOTRON

Master branch

This branch

W7-X

Master branch

This branch

NCSX

Master branch

This branch

Removal of spectral aliasing

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[github-actions]

Memory benchmark result

|               Test Name                |      %Δ      |    Master (MB)     |      PR (MB)       |    Δ (MB)    |    Time PR (s)     |  Time Master (s)   |
| -------------------------------------- | ------------ | ------------------ | ------------------ | ------------ | ------------------ | ------------------ |
  test_objective_jac_w7x                 |   -2.85 %    |     3.960e+03      |     3.847e+03      |   -113.00    |       39.03        |       36.42        |
  test_proximal_jac_w7x_with_eq_update   |   -0.16 %    |     6.489e+03      |     6.479e+03      |    -10.11    |       156.32       |       158.97       |
  test_proximal_freeb_jac                |    0.21 %    |     1.318e+04      |     1.321e+04      |    27.09     |       82.97        |       83.59        |
  test_proximal_freeb_jac_blocked        |    0.91 %    |     7.475e+03      |     7.543e+03      |    67.92     |       71.84        |       73.66        |
  test_proximal_freeb_jac_batched        |    0.32 %    |     7.491e+03      |     7.516e+03      |    24.09     |       70.23        |       72.14        |
  test_proximal_jac_ripple               |   -5.86 %    |     3.607e+03      |     3.395e+03      |   -211.50    |       60.24        |       65.15        |
  test_proximal_jac_ripple_bounce1d      |   -3.28 %    |     3.605e+03      |     3.487e+03      |   -118.13    |       73.08        |       76.09        |
  test_eq_solve                          |    1.05 %    |     2.006e+03      |     2.027e+03      |    21.12     |       92.28        |       94.30        |

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

addressed request

[YigitElma]

I assume there is no math error, I couldn't check it very well because it is really hard to follow the code with all the different angle calls and some of function names are ambigious.

Are you planning to maintain the interpax_fft package?

[unalmis]

I assume there is no math error...

Yes, and I have resolved your other comments concerning cosmetics in the code comments.

[unalmis]

Someone else who is still working on desc will need to maintain this PR from now on.