mini tutorial for docs

[orbeckst]

The docs should start with a small tutorial that shows how to use GromacsWrapper.

This is also important for the paper #147 because they will review docs together with installability etc.

tutorial

• installation with Gromacs (can use conda) so that it is completely self contained
• detection and configuration (or rather, how little need there is to configure anything)
• can use the AdK tutorial as a starting point: condense and show
  1. how to use GW explicitly,
  2. how to use gromacs.setup to streamline the process.

[richardjgowers]

one of the places tests are weakest currently is cookbook, any many of those "recipes" I don't understand because they're domain specific. So if someone could also expand the recipes into regression tests they would win the favour of the coverage gods.

[orbeckst]

Some of the recipes are arcane... and it might be better to just throw them out and just keep the whole thing reasonably clean. I'll have a look at it. Perhaps just make it a separate thing (except for the stuff that is used in gromacs/setup.py). Can you open an issue and assign to me, please?

[pslacerda]

Do you have some newbie tutorial for molecular simulation topics?

An approach is to create an executable documentation and verify if the final output is the expected. Some sort of executable markdown would be really nice. It is an tutorial, documentation and also certify code correctness.

If you have some I can convert it in this sort of executable tutorial/documentation/test. Probably to append some bit of of very introductory MDAnalysis (like center of mass or whatever) is a good idea to fully exemplify the GromacsWrapper usefulness.

But first I'm worried about the acceptance criteria of JOSS for binding libraries.

[orbeckst]

But first I'm worried about the acceptance criteria of JOSS for binding libraries.

I don't think that is a worry. The library enabled us to create other packages such as https://github.com/Becksteinlab/MDPOW that has been used in three papers at least. It also contains new code (e.g., in gromacs/setup.py). It is useful for constructing workflows (e.g. in https://github.com/Becksteinlab/mdworks). Only recently has there been made a serious attempt at a Gromacs Python API https://github.com/kassonlab/gmxapi , which looks great but still requires changes in the Gromacs sources. We will certainly cite gmxapi but also point out that the GromacsWrapper approach works with different versions of Gromacs, which allows (version-independent scripts.

[orbeckst]

Do you have some newbie tutorial for molecular simulation topics?

1. Justin Lemkul's (@jalemkul) Gromacs Tutorials, especially the Tutorial 1: Lysozyme in water. Justin is working on a manuscript describing the tutorials in depth, which is available pre-publication as gmx_tutorials.pdf. We could certainly "GromacsWrapper-ify" the Lysozyme Tutorial and then reference Justin's paper and site.
2. Our draft of the AdK tutorial (data at Becksteinlab/AdKGromacsTutorial)) could also be used as a starting point but it has not been fully updated to work correctly with Gromacs 2018 (see the issues).

I recommend (1) to learn how to run a simple simulation with Gromacs 2018.

I should point out that the problems with (2) show potential pitfalls with the claim that GromacsWrapper can write "Gromacs version-independent" scripts because input files and options can still change between Gromacs releases. It would be very interesting to write a mini-tutorial that demonstrates how to take care of these differences with minimal impact. (I think we need a function in GromacsWrapper that identifies the Gromacs release... something such gromacs.gmx_release so that code can make decisions based on the release).

[pslacerda]

Then for sure it pass the criteria!

I'm looking towards (2), a good decision is to warn about using version dependent options, but better to really adapt such options if we could. I also prefer (2) instead of (1) because we can adjust it to our needs.

I'll try to work on the executable (and testable) documentation this weekend.

[orbeckst]

@pslacerda I am tentatively assigning you to this issue. If you can get started with a PR I am happy to chime in. Also feel free to raise issues in https://github.com/Becksteinlab/AdKGromacsTutorial

[pslacerda]

I'm very happy to adapt the tutorial to GW.

The idea is to execute the code blocks in the tutorial, any instructions needed to setup the environment or to test after all the code was executed goes into comments containing such special code.

So we can just run the tutorial and compare the results with the expected. The code excerpts will be moved from the .rst to individual .py/.sh files that will be included in the final .rst files during the build.

Both python and shell version can be choosen like a multilanguage documentation, but for programming instead of natural languages.

Seems a good approach to ensure that the tutorial is running fine, maybe even for other software.

[richardjgowers]

@pslacerda It might be easier to use something like doctesting, which does the .py -> .rst transformation you describe but in reverse. Ie it reads the rst docs and tries to run any code blocks

[pslacerda]

I agree @richardjgowers, would be easier to almost everything. What I'm worried about is to have both tutorials always in sync, would be a bit harder to write a text that cover both languages but is also possible. It also enable to test the original AdKGromacsTutorial.

If you are sure that the tutorials text would diverge too much in order to explain details of GromacsWrapper, than for sure I'd go for doctesting.