Documenting SPEC

[amwrightau]

Following some discussions it seems it would be useful to document the normalisations and coordinates which are employed in SPEC. Among other things, this would aid useability.

The suggestion is to discuss here, making sure everyone is in agreement. Thanks.

@zhucaoxiang @jloizu

[zhisong]

Good idea. I would suggest we open an Overleaf Latex document that shared among everyone. The document can then be integrated into manual.h permanently.

[amwrightau]

I've started an Overleaf document here: https://www.overleaf.com/5928642235nrwpnmgksfrc

Please edit and add, as required. Thanks.

[zhisong]

I added a section talking about SPEC/VMEC sign conversion. Please see if you agree or not before we forget...

[jonathanschilling]

After the merge of the Zernike branch, we agreed to work on the documentation for SPEC.
The branch related to this is try_doxygen.
I merged in the latest master state.

Points to discuss:

• in-place debugging code --> separable into stand-alone unit tests?
  Currently, the (optional) recursive subroutine definitions in dforce.f90 and rzaxis.f90 confuse doxygen.
  However, these routines are quite central and the documentation should be available.
  @abaillod @zhisong Would it be ok to revise the structure of these subroutines to something simpler than recursive calls?
• removal of macros?
• revise Makefile: generation of documentation; sort out dependencies among modules properly (e.g. sphdf5), separate build folder to keep object files out of source tree

[zhisong]

• in-place debugging code --> separable into stand-alone unit tests?

This should be the way to go. A neater code will be preferable. We can move the testing codes with the DEBUG flag to a new file called testsp.f90 or something like that, will all tests properly documented (currently they are not).

[jonathanschilling]

In #136 , the try_doxygen branch was merged into master, so now we all can start working on the actual content of the documentation in the master branch and have the website at https://princetonuniversity.github.io/SPEC/index.html and PDF manual at https://princetonuniversity.github.io/SPEC/SPEC_manual.pdf automagically updated.

[jonathanschilling]

If you would like to take on documenting one of the source code files below,
feel free to put yourself in the list.

• basefn.f90
• bfield.f90
• bnorml.f90
• brcast.f90
• casing.f90
• coords.f90
• curent.f90
• df00ab.f90
• dforce.f90 Antoine
• dfp100.f90 Antoine
• dfp200.f90 Antoine
• global.f90
• hesian.f90 Arunav
• intghs.f90 Zhisong
• jo00aa.f90
• lbpol.f90
• lforce.f90
• ma00aa.f90
• ma02aa.f90
• manual.f90
• matrix.f90
• memory.f90
• metrix.f90
• mp00ac.f90
• mtrxhs.f90 Zhisong
• newton.f90 Joaquim
• numrec.f90 Stuart
• packab.f90
• packxi.f90
• pc00aa.f90
• pc00ab.f90
• pp00aa.f90 Jonathan
• pp00ab.f90 Jonathan
• preset.f90
• ra00aa.f90
• rzaxis.f90
• sphdf5.f90
• spsint.f90
• spsmat.f90
• stzxyz.f90
• tr00ab.f90
• volume.f90
• wa00aa.f90
• xspech.f90