Implement from_input_file for Equilibrium, update docs with this info

[dpanici]

resolves #1298

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[github-actions]

|             benchmark_name             |         dt(%)          |         dt(s)          |        t_new(s)        |        t_old(s)        | 
| -------------------------------------- | ---------------------- | ---------------------- | ---------------------- | ---------------------- |
 test_build_transform_fft_midres         |     +0.60 +/- 6.92     | +3.76e-03 +/- 4.31e-02 |  6.27e-01 +/- 2.7e-02  |  6.24e-01 +/- 3.4e-02  |
 test_build_transform_fft_highres        |     -0.41 +/- 2.89     | -4.17e-03 +/- 2.97e-02 |  1.02e+00 +/- 1.9e-02  |  1.03e+00 +/- 2.3e-02  |
 test_equilibrium_init_lowres            |     +0.60 +/- 2.23     | +2.45e-02 +/- 9.07e-02 |  4.10e+00 +/- 7.3e-02  |  4.07e+00 +/- 5.4e-02  |
 test_objective_compile_atf              |     -0.48 +/- 3.89     | -3.88e-02 +/- 3.13e-01 |  8.00e+00 +/- 1.7e-01  |  8.04e+00 +/- 2.6e-01  |
 test_objective_compute_atf              |     +1.03 +/- 3.73     | +1.10e-04 +/- 4.00e-04 |  1.08e-02 +/- 2.3e-04  |  1.07e-02 +/- 3.3e-04  |
 test_objective_jac_atf                  |     +1.80 +/- 2.88     | +3.43e-02 +/- 5.50e-02 |  1.94e+00 +/- 2.9e-02  |  1.91e+00 +/- 4.7e-02  |
 test_perturb_1                          |     -0.98 +/- 1.93     | -1.30e-01 +/- 2.55e-01 |  1.31e+01 +/- 2.0e-01  |  1.32e+01 +/- 1.6e-01  |
 test_proximal_jac_atf                   |     -0.21 +/- 0.75     | -1.74e-02 +/- 6.10e-02 |  8.15e+00 +/- 2.7e-02  |  8.17e+00 +/- 5.5e-02  |
 test_proximal_freeb_compute             |     +0.02 +/- 1.10     | +3.59e-05 +/- 2.01e-03 |  1.84e-01 +/- 1.3e-03  |  1.84e-01 +/- 1.6e-03  |
 test_build_transform_fft_lowres         |     +1.91 +/- 5.49     | +9.86e-03 +/- 2.84e-02 |  5.27e-01 +/- 2.6e-02  |  5.18e-01 +/- 1.2e-02  |
 test_equilibrium_init_medres            |     +0.55 +/- 1.07     | +2.28e-02 +/- 4.40e-02 |  4.13e+00 +/- 3.0e-02  |  4.11e+00 +/- 3.2e-02  |
 test_equilibrium_init_highres           |     -0.51 +/- 0.99     | -2.80e-02 +/- 5.40e-02 |  5.44e+00 +/- 2.5e-02  |  5.47e+00 +/- 4.8e-02  |
 test_objective_compile_dshape_current   |     +0.22 +/- 6.99     | +8.44e-03 +/- 2.67e-01 |  3.84e+00 +/- 1.9e-01  |  3.83e+00 +/- 1.9e-01  |
 test_objective_compute_dshape_current   |     +0.91 +/- 2.10     | +3.29e-05 +/- 7.59e-05 |  3.64e-03 +/- 7.1e-05  |  3.61e-03 +/- 2.8e-05  |
 test_objective_jac_dshape_current       |     +3.04 +/- 5.20     | +1.20e-03 +/- 2.04e-03 |  4.05e-02 +/- 1.4e-03  |  3.93e-02 +/- 1.5e-03  |
 test_perturb_2                          |     +0.53 +/- 1.08     | +9.32e-02 +/- 1.90e-01 |  1.76e+01 +/- 1.4e-01  |  1.75e+01 +/- 1.3e-01  |
 test_proximal_freeb_jac                 |     +0.46 +/- 1.03     | +3.39e-02 +/- 7.65e-02 |  7.46e+00 +/- 3.6e-02  |  7.42e+00 +/- 6.7e-02  |
 test_solve_fixed_iter                   |     -1.41 +/- 58.99    | -7.06e-02 +/- 2.96e+00 |  4.94e+00 +/- 2.1e+00  |  5.01e+00 +/- 2.1e+00  |

[YigitElma]

This is probably handled somewhere in the InputReader (and thus not related to this PR) but I couldn't find it at the first glance, do we ever check if the given l modes are all 0s? Even if the user gives nonzero values, they will probably be ignored but still, a warning or something could be good.

[dpanici]

They are not, I checked and inputs["surface"] has floats for the mode number parts of it. Probably we should handle in input reader, you're right

[f0uriest]

equilibrium.utils.parse_surface ensures that the surface array either has all l==0 or all n==0:

DESC/desc/equilibrium/utils.py

Line 62 in f5abd60

def parse_surface(surface, NFP=1, sym=True, spectral_indexing="ansi"):

[codecov]

Codecov Report

Attention: Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.

Project coverage is 95.52%. Comparing base (d29ba60) to head (586af7d).

Files with missing lines	Patch %	Lines
desc/equilibrium/equilibrium.py	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1327      +/-   ##
==========================================
- Coverage   95.53%   95.52%   -0.01%     
==========================================
  Files          96       96              
  Lines       24010    24024      +14     
==========================================
+ Hits        22937    22949      +12     
- Misses       1073     1075       +2     

Files with missing lines	Coverage Δ
desc/geometry/surface.py	96.85% <ø> (ø)
desc/input_reader.py	92.00% <100.00%> (ø)
desc/equilibrium/equilibrium.py	96.08% <92.85%> (-0.07%)	⬇️

... and 1 file with indirect coverage changes

[dpanici]

Should make it no threshold by default

[YigitElma]

The non-zero l modes in the input file warning can be added in some other PR. Seems fine to me