itpplasma/libneo

Integrate, document and test VMEC interfaces

Opened this issue · 0 comments

krystophny commented

Created a feature branch, see https://github.com/itpplasma/libneo/tree/vmec and master...vmec . This feature depends on NetCDF, which I suggest to make a required dependency together with HDF5, since we use the latter for data storage anyway, and both are standard in most environments.

@micheder in case you change or document something in the VMEC interface code, please commit it here, so we will finally have a central place where the interface resides.

Up to now, four files have been added:

src/canonical_coordinates_mod.f90
src/nctools_module.f90
src/spline_vmec_data.f90
src/vmecinm_m.f90

The canonical_coordinates_mod.f90 comes from SIMPLE and additionally contains transformation to canonical flux coordinates but also "usual" magnetic field routines for VMEC fields.

Unification

Goal: Maintain a single up-to-date version of VMEC field routines in libneo for all codes
Non-Goal: Do changes that break compatibility with legacy codes or risk new bugs

At least the following codes use VMEC input routines:

There has been two important changes in the SIMPLE variant that should be included everywhere:

  1. itpplasma/SIMPLE@2e8a410 corrects the interpolation of lambda that is added to the poloidal VMEC angle to get the one for symmetry flux coordinates (aka PEST1, see Callen/d'haeseleer p.122). It is given on half-mesh radial points in the VMEC output. This affects comparisons to old results from codes that used the wrong interpolation
  2. itpplasma/SIMPLE@ac7bcb6 from Matt Landreman supports non-stellarator symmetric equilibria. This is crucial for perturbed tokamak equilibria.

Testing

Goal: Have automated unit tests for consistency and against official STELLOPT/libstell routines
Non-Goal: Replace our routines by libstell routines. Ours are better :P

  • An example how to test magnetic field components and their derivatives can be found here. The idea is to compare computed field derivatives against finite differences with some "meaningful" step size. This is however for other (canonical flux coordinate) field routines so needs to be completely rewritten.
  • A draft how to compare our fields against libstell ones is here
  • An example how to do unit tests in pfunit and GitHub actions for automation is in Daniel's Bachelor thesis and implemented in https://github.com/itpplasma/GORILLA .

Documentation

Goal: Write API (function headers, doxygen) and user docs (latex? doxygen?) for VMEC routines
Non-Goal: Long and detailed docs. Those should rather be referred to VMECwiki

Comments

  • magfie.f90 contains magnetic field routines (high-level in group standard)
  • spline_vmec_data.f90 contains code to generate and evaluate splines for VMEC R, Z, lambda and field routine vmec_field (low-level)
  • splint_vmec_data evaluates splines in given point. (even lower level)

TODO

  • Stop writing empty NetCDF file if not existant

  • Test magfie_vmec derivatives against finite differences da/dx ~= (a(x+dx)-a(x-dx))/(2*dx))

  • Test vmec_field derivatives against finite differences

  • Test fields against libstell fields. Extend test_vmec.f90 towards automated testing. Use sum of absolute value differences and set threshold parameter.

  • Test splint_vmec_data derivatives as lowest level function

  • Automate with pfUnit (see Daniel's bachelor work)

  • Generate coverage (see Daniel's bachelor work)

  • Create GitHub actions (see Daniel's bachelor work)

  • Think about relative error in case the reference becomes zero. -> function relerr

  • Rico: Check how to diff against reformatted code -> man diff -> diff -bB or else diff -w

  • Add intent(in) or intent(out) wherever possible to arguments

  • Find out from Patrick Lainer how to treat intent of array arguments to be filled with data

  • Add Doxygen documentation wherever possible