Update VMECIO to specify Nyquist spectrum and fix issues with asymmetric wouts

[dpanici]

• plot_vmec_comparison sneakily only worked for sym=True wout files, this changes it to work correctly
• allow M_nyq and N_nyq to be passed as keywords to VMECIO.save
• fix typo in axis loading from an asymmetric VMEC equilibrium
• fix sneaky bug in asymmetric wout saving where some of the derived quantities were being fit with the transform directly instead of using the fullfit function which did the fit AND negated the correct modes to account for poloidal angle reversal... this will help in Add Ability to Write Boozmn.nc style output files #680 and also resolve Saving asymmetric eq as a wout has some errors #1062 I believe, as the magnetic field coeffs being saved before were wrt the wrong poloidal angle (and the opposite one as the jacobian fourier coefficients saved).
• make test with an asymmetric stellarator

hopefully resolves #1062

Notes

For an NFP=4 stellarator, VMEC with NZETA=200 yields a max nyquist N of 400 while NZETA=100 yields a max nyquist N of 200, which leads me to believe the max nyquist toroidal modenumber is set as NFP * NZETA/2 or something along those lines (I support with a line from educational VMEC : https://github.com/jonathanschilling/educational_VMEC/blob/ad4db0a56b23c3324df3d6101781b69b2e3b7e13/src/fixaray.f90#L28)

default values of ntheta, nzeta are here

defaults:
NTHETA = 2M+6
NZETA = 2N+4

then nyquist freq determined by
mnyq = MAX(0, NTHETA, 2*(M-1))
nnyq = MAX(0, NZETA, 2*ntor)

translates to default of M+3 (in practice it seems to be M+4... don't understand completely but this is what the wout has)) and N+2 for the nyquist max spectrum defaults

When VMEC is given a right-handed bdry (such that sqrt(g)>0 ), it seems to change the modes such that the new bdry is left-handed (but the way of changing the bdry handedness changes where the theta=0 point is on the bdry, and is NOT how we enforce the change in handedness in DESC) (this is bc they change [theta -> pi - theta] (https://github.com/jonathanschilling/educational_VMEC/blob/ad4db0a56b23c3324df3d6101781b69b2e3b7e13/src/flip_theta.f90#L29).)
For example, the asymmetric rotating ellipse bdry given by

will be, in the resulting wout file, replaced by

This is a pitfall if trying to compare the wout from a VMEC run to a DESC equilibrium saved as a wout, as the output bdry modes in VMEC are not what you used as the input modes, AND the theta definition is changed not only in its direction but also with a pi shift.

[github-actions]

|             benchmark_name             |         dt(%)          |         dt(s)          |        t_new(s)        |        t_old(s)        | 
| -------------------------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- |
 test_build_transform_fft_lowres         |     +1.18 +/- 6.76     | +6.19e-03 +/- 3.55e-02 |  5.31e-01 +/- 3.4e-02  |  5.25e-01 +/- 1.1e-02  |
 test_equilibrium_init_medres            |     -6.58 +/- 4.76     | -2.86e-01 +/- 2.07e-01 |  4.06e+00 +/- 2.8e-02  |  4.34e+00 +/- 2.0e-01  |
 test_equilibrium_init_highres           |     +1.53 +/- 4.30     | +8.30e-02 +/- 2.34e-01 |  5.52e+00 +/- 2.1e-01  |  5.44e+00 +/- 1.1e-01  |
 test_objective_compile_dshape_current   |     +0.47 +/- 3.07     | +1.79e-02 +/- 1.17e-01 |  3.82e+00 +/- 6.6e-02  |  3.80e+00 +/- 9.6e-02  |
 test_objective_compute_dshape_current   |     -0.64 +/- 2.65     | -2.23e-05 +/- 9.15e-05 |  3.43e-03 +/- 4.6e-05  |  3.46e-03 +/- 7.9e-05  |
 test_objective_jac_dshape_current       |     -2.09 +/- 7.59     | -8.72e-04 +/- 3.17e-03 |  4.08e-02 +/- 2.2e-03  |  4.17e-02 +/- 2.3e-03  |
 test_perturb_2                          |     -0.91 +/- 4.06     | -1.63e-01 +/- 7.25e-01 |  1.77e+01 +/- 4.5e-01  |  1.79e+01 +/- 5.7e-01  |
 test_proximal_freeb_jac                 |     +0.87 +/- 1.86     | +6.54e-02 +/- 1.40e-01 |  7.60e+00 +/- 1.2e-01  |  7.54e+00 +/- 7.3e-02  |
 test_solve_fixed_iter                   |     +0.44 +/- 60.99    | +2.23e-02 +/- 3.08e+00 |  5.07e+00 +/- 2.2e+00  |  5.05e+00 +/- 2.1e+00  |
 test_build_transform_fft_midres         |    +10.72 +/- 3.71     | +6.40e-02 +/- 2.21e-02 |  6.61e-01 +/- 2.0e-02  |  5.97e-01 +/- 8.8e-03  |
 test_build_transform_fft_highres        |     +5.70 +/- 3.86     | +5.70e-02 +/- 3.86e-02 |  1.06e+00 +/- 3.1e-02  |  1.00e+00 +/- 2.4e-02  |
 test_equilibrium_init_lowres            |     +1.12 +/- 3.66     | +4.23e-02 +/- 1.38e-01 |  3.81e+00 +/- 1.1e-01  |  3.77e+00 +/- 8.3e-02  |
 test_objective_compile_atf              |     -1.09 +/- 4.04     | -8.57e-02 +/- 3.17e-01 |  7.75e+00 +/- 2.2e-01  |  7.83e+00 +/- 2.3e-01  |
 test_objective_compute_atf              |     -2.48 +/- 2.62     | -2.58e-04 +/- 2.72e-04 |  1.01e-02 +/- 1.1e-04  |  1.04e-02 +/- 2.5e-04  |
 test_objective_jac_atf                  |     -2.46 +/- 2.43     | -4.76e-02 +/- 4.71e-02 |  1.89e+00 +/- 4.3e-02  |  1.94e+00 +/- 2.0e-02  |
 test_perturb_1                          |     +1.36 +/- 5.05     | +1.69e-01 +/- 6.28e-01 |  1.26e+01 +/- 2.0e-01  |  1.24e+01 +/- 5.9e-01  |
 test_proximal_jac_atf                   |     +1.15 +/- 0.90     | +9.17e-02 +/- 7.20e-02 |  8.08e+00 +/- 5.0e-02  |  7.98e+00 +/- 5.2e-02  |
 test_proximal_freeb_compute             |     -1.24 +/- 0.90     | -2.27e-03 +/- 1.65e-03 |  1.81e-01 +/- 8.6e-04  |  1.84e-01 +/- 1.4e-03  |

[dpanici]

check NZETA does what I expect

[codecov]

Codecov Report

Attention: Patch coverage is 75.00000% with 6 lines in your changes missing coverage. Please review.

Project coverage is 95.31%. Comparing base (2ebdf6a) to head (95a3292).
Report is 25 commits behind head on master.

Files with missing lines	Patch %	Lines
desc/vmec.py	75.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1211      +/-   ##
==========================================
- Coverage   95.33%   95.31%   -0.03%     
==========================================
  Files          90       90              
  Lines       22702    22713      +11     
==========================================
+ Hits        21644    21649       +5     
- Misses       1058     1064       +6     

Files with missing lines	Coverage Δ
desc/vmec.py	91.91% <75.00%> (-0.41%)	⬇️

... and 1 file with indirect coverage changes

[rahulgaur104]

Is cubic spline the best way to interpolate fourier coefficients in the radial direction?
A fourier coefficient may not always be smooth.

[dpanici]

It might not be, esp. at edge, but I don't feel the need to change as this is not really used anywhere important in the code

[f0uriest]

I think vmec itself implicitly assumes the fourier coeffs at at least c1 smooth

[rahulgaur104]

Why exclude points close to the axis? Because of strong variations?

[dpanici]

b/c VMEC is notorious for being inaccurate near-axis. But in this case the two solutions (the DESC and VMEC) one are not exactly similar (even visually) near-axis, so we also want to exclude it for that reason.

I dont need this test to be a validation of DESC v VMEC, I just want it to tell me if I am way off in the asymmetric quantities basically

[f0uriest]

are these still the correct defaults? It sounded like N_nyq = NZETA*2?

[f0uriest]

also you can use setdefault for a cleaner version of this

[dpanici]

These are still correct, I think. At least VMEC by default gives M nyq of Mpol-1+4, and Mpol-1 = our Mpol

[ddudt]

I won't force you to change this, but I would prefer to consistently have verbose always be the last kwarg

[dpanici]

I won't just because changing it means changing positional args that others might be using and that would break code. I know we have not committed to an API but for this I will keep as is

[unalmis]

maybe relevant: https://docs.python.org/3.8/whatsnew/3.8.html#positional-only-parameters

[ddudt]

This is cool! In a future PR I would be in favor of requiring stuff like verbose to be keyword arguments. That would help with backward-compatibility of the code