SPEC icon indicating copy to clipboard operation
SPEC copied to clipboard
verified publisher icon PrincetonUniversity

Documenting SPEC

Open amwrightau opened this issue 6 years ago • 7 comments

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

amwrightau avatar Aug 05 '19 14:08 amwrightau

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.

zhisong avatar Aug 06 '19 02:08 zhisong

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

Please edit and add, as required. Thanks.

amwrightau avatar Aug 06 '19 15:08 amwrightau

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

zhisong avatar Aug 06 '19 23:08 zhisong

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

jonathanschilling avatar Oct 02 '20 08:10 jonathanschilling

  • 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).

zhisong avatar Oct 02 '20 11:10 zhisong

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 avatar Apr 13 '21 15:04 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
  • [x] sphdf5.f90
  • [ ] spsint.f90
  • [ ] spsmat.f90
  • [ ] stzxyz.f90
  • [ ] tr00ab.f90
  • [ ] volume.f90
  • [ ] wa00aa.f90
  • [x] xspech.f90

jonathanschilling avatar Mar 10 '22 12:03 jonathanschilling