Geometry upgrade

[mrhardman]

Generalisation of the treatment of the magnetic geometry to permit the later addition of non-trivial options.

To do:

• magnetic mirror terms
• magnetic drift terms
• vperp advection (d B / dt /= 0)
• anything else related

[mrhardman]

@slnewton @johnomotani 80cca93 my intention is to investigate the toy geometry introduced in the option in the linked commit.

[johnomotani]

Oh, one other thing - it would be nice to have a docs page (.md file in docs/src/) at least briefly describing the available geometry options.

[mrhardman]

Oh, one other thing - it would be nice to have a docs page (.md file in docs/src/) at least briefly describing the available geometry options.

Should this file be a new file or should the content go in the zz_geo.md file? Are you happy with the description of the geometry given in the corresponding ExCALIBUR report?

[johnomotani]

Should this file be a new file or should the content go in the zz_geo.md file?

A new file. The files without the zz_ prefix are hand-written documentation (e.g. https://mabarnes.github.io/moment_kinetics/dev/post_processing_notes/#Post-processing). To add a new one, create the file, and then put the filename in the Pages list in index.md.

The files with zz_ prefix are the auto-generated module documentation (from the docstrings in the Julia code). The zz_ prefix is so that they get listed (in the left-hand sidebar of the docs site) together in a group that comes after all the hand-written pages. For whatever reason that sidebar sorts things by filename, but that turns out to work pretty well for what we want.

Are you happy with the description of the geometry given in the corresponding ExCALIBUR report?

That'd be great.

[mrhardman]

Are you happy with the description of the geometry given in the corresponding ExCALIBUR report?

That'd be great.

Is there a preference for putting the documentation in the geo.jl module next to the source? This seems like a more sustainable option, but perhaps a link in the source to the docs page is enough to ensure it is read and modified when the source is updated?

[johnomotani]

Is there a preference for putting the documentation in the geo.jl module next to the source? This seems like a more sustainable option, but perhaps a link in the source to the docs page is enough to ensure it is read and modified when the source is updated?

That is an option, and I agree that it's nice to keep the source code and docs together. The downside is that it's a little bit more annoying to write documentation in docstrings in .jl files than in a .md file (e.g. when writing maths, the $ characters all need to be escaped, and I think some other similar things). So whichever you like. If you decide to put all the docs into the source code file, it would still be nice to have a geo.md page that can be linked in the index that just links to the module docs (the link would be created by [`moment_kinetics.geo`](@ref)).

[mrhardman]

OK. I am happy with linking to external libraries. For now the main problem is that I cannot work out how to make or view the documentation locally without working on git. Is it really necessary to have webviewer? That may be a problem, as I do all my development on remote servers.

[johnomotani]

For now the main problem is that I cannot work out how to make or view the documentation locally without working on git. Is it really necessary to have webviewer? That may be a problem, as I do all my development on remote servers.

It should be possible to build a pdf version by doing julia --project make-pdf.jl in the docs/ directory, instead of julia --project make.jl, but that option doesn't get tested much so it might be broken. If you build the html documentation, you can just download the build subdirectory that it will create, and open build/index.html with a web browser.

[johnomotani]

PS the README.md for the docs might need to be updated. I think you need some setup before the docs will build along the lines of

$ cd docs/
$ julia --project
julia>]
pkg> dev ../moment_kinetics
pkg> dev ../makie_post_processing/makie_post_processing
pkg> dev ../plots_post_processing/plots_post_processing

After that (I hope!)

julia> include("make.jl")

or

$ julia --project make.jl

should work. As usual, I prefer the REPL version because when you need to edit the .md files and rebuild the docs, the second (and later) docs builds are fast because the code is already compiled.

[johnomotani]

Ah, no. When you run make.jl you don't need to do any other setup first - that script takes care of installing the packages for moment_kinetics, etc. already. I forgot I'd done that! make-pdf.jl doesn't (yet) have that feature though.

[mrhardman]

I have just added a new file https://github.com/mabarnes/moment_kinetics/blob/geometry-upgrade/docs/src/geometry.md. Please comment!

Whilst writing this I considered that an input namelist for the geometry option (like numerical dissipation) would be appropriate. @johnomotani do you agree and should this happen in this PR?

[johnomotani]

Whilst writing this I considered that an input namelist for the geometry option (like numerical dissipation) would be appropriate. @johnomotani do you agree and should this happen in this PR?

I think that should happen in general. This seems like a good time to do it for the geometry. Including the change in this PR would be good as we are already breaking the input options (removing Bzed, etc.) so better to finish breaking them before people start writing new input files.

Once you create the new section, it would be good to add the 'old' top-level options to removed_options_list (see b52f943) so people don't get surprised if old input files don't behave as expected.

[johnomotani]

I have just added a new file https://github.com/mabarnes/moment_kinetics/blob/geometry upgrade/docs/src/geometry.md. Please comment!

Nice, thank you!

[mrhardman]

Whilst writing this I considered that an input namelist for the geometry option (like numerical dissipation) would be appropriate. @johnomotani do you agree and should this happen in this PR?

I think that should happen in general. This seems like a good time to do it for the geometry. Including the change in this PR would be good as we are already breaking the input options (removing Bzed, etc.) so better to finish breaking them before people start writing new input files.

Once you create the new section, it would be good to add the 'old' top-level options to removed_options_list (see b52f943) so people don't get surprised if old input files don't behave as expected.

This is now done, please review my latest changes!

[johnomotani]

Looks good to me. We can merge when the CI tests pass.