Feature to stop run early but do so cleanly is not documented

[Stephen Biggs-Fox]

BOUT++ has a feature where one can set an input parameter stopCheck=true, in which case "At every output time, the monitor checks for the existence of a file, by default called BOUT.stop, in the same directory as the output data. If the file exists then the monitor signals the time integration solver to quit. This should result in a clean shutdown." (https://bout-dev.readthedocs.io/en/latest/user_docs/running_bout.html#stopping-simulations)

GS2 does not have this feature. It would be nice if GS2 did have this feature, e.g. a big job is checked part of the way through and it makes sense to stop the run but the data is useful and should be kept. Presently, the only options are to: (a) leave the job running until it stops naturally (which may or may not be clean but hopefully will be clean if avail_cpu_time and margin_cpu_time have been set correctly); or (b) kill the job, which is unlikely to result in a clean finish.

Can we add this feature to GS2 please?

[Joseph Parker]

GS2 does have this feature - if you touch a file <job_name>.stop then GS2 should exit cleanly.

I suspect the bug you're actually reporting is that this isn't documented...

[David Dickinson]

Indeed I implemented the BOUT++ feature because of the experience with the GS2 feature!

[Stephen Biggs-Fox]

Ah ha, OK. So in that case, Joe is right - the bug is that it's not documented. Where's the best place to document this?

Possibly this opens a wider discussion of how best to document GS2 in general? I mean, the in-code documentation is useful but it's more for developers. We could probably do with a short, simple user-manual to describe the basics of how to work GS2 and maybe that would be the place for this sort of information. A lot of the information for the user manual exists already in various places on the wiki, etc.

[David Dickinson]

The wiki is one place we could provide a quick-start guide. I'd quite like us to include this along side the auto generated source-code documentation so we have a quick start guided and top tips easily accessible.

[Stephen Biggs-Fox]

"I'd quite like us to include [a quick-start guide] along side the auto generated source-code documentation"

Do you mean we should configure FORD to generate some overview pages that don't relate to a specific bit of code but rather cover the program as a whole? If so, where does the source for that go?

[David Dickinson]

Yes exactly (see the "notes" part menu on the website) -- details are at https://github.com/Fortran-FOSS-Programmers/ford/wiki/Writing-Pages

[Stephen Biggs-Fox]

OK. So what's the plan then? Are we going to port the wiki to FORD format?

[David Dickinson]

No I don't think porting the full wiki to FORD is a good idea -- I think it makes more sense for us to curate a simple set of documents (at least to start with) that describe the key things we want to say. This should be more like a structured manual (perhaps also with a few standalone quick summary documents). The wiki still exists and can be used for more "wiki" like things. The ford docs ship with the code so are always available.

Designing and writing a manual is obviously time consuming work.

[Stephen Biggs-Fox]

Indeed. Do any of the current GS2 grants cover this sort of work?

The BOUT++ docs and the Dedalus docs both provide pretty good introductory user guides / tutorials. Maybe we could use one of these or a combination of the two as a template (or at least for ideas / inspiration)?

[David Dickinson]

Unfortunately I'm not sure if current GS2 grants do cover this or not. I agree that using something like BOUT's manual as an outline of the sorts of things we want is a good idea. In particular the separation of the manual into user and developer parts may be quite helpful in keeping the documentation focused.

[Stephen Biggs-Fox]

Discussion has broadened so title changed to reflect that

[David Dickinson]

Probably worth making a new issue for this and can reference this one as an example for why it's a good idea (or change the issue description, but then the comments don't make much sense).

[Stephen Biggs-Fox]

What about input parameters?

It seems that in-code documentation of the variable that appears in the namelist is a good way because it is more likely (although not guaranteed) to result in all current input parameters having documentation and removed input parameters also having their documentation removed.

Also, I'm fairly sure that namelists are only used in relation to input parameters. Therefore, it should, in theory, be safe to assume that all variables that are in a namelist are input parameters. This fact could be used to generate a master list of all input parameters and which namelist they're in with the in-code documentation alongside. Can we auto-generate a FORD page with this information on? Maybe the old wiki input parameters page could have its information ported to in-code documentation?

I'm asking because I'm adding a new input parameter in relation to issue #66 (Run fails if restart_dir does not exist) and I'm wondering where to put the documentation of the new input parameter. The above may be all well and good but is not set up yet and, while not too bad to implement, is not trivial either. What should I do about documentation of this new input parameter for now?

And an even broader question... how should we let other GS2 users / developers know about changes? I mean, most improvements, whether optimisations or new features, usually come with an input parameter to activate them. How can we make it easy for users / developers to keep up with such changes? (As opposed to bugfixes that can quietly fix things in the background.)

[Stephen Biggs-Fox]

Separate issue to be created for wider discussion as suggested

[David Dickinson]

Yes input parameter documentation is probably the most important thing we need to provide to start with. FORD currently doesn't seem to be able to identify namelists -- one route forward is to contribute to ford to enable it to recognise namelists. We can then document these, but there may still be some things this can't achieve (e.g. getting the defaults).

For now I would use in source documentation, e.g. logical :: new_input=.true. !< Does the thing, default is .true.. We could think about documenting the namelist + defaults as part of the documentation of the routine responsible for reading that namelist (usually called read_parameters). It might require a bit of digging through the source documentation in order to find this, but at least it would be consistent.

I've been considering another approach that might better isolated the input parameters from the rest of the code, making it easier to document (and parse for auto-documentation). This approach may have several benefits but is a code change and could take a while to iron out (I've done this on other projects and it worked well, but it would be trickier for GS2).

We try to provide a change log with each release -- this is a good way to alert users to changes. Developers can use the change log but will hopefully also see the PRs that bring in these new features. It's therefore quite important to make sure PRs are as simple as possible (one feature per PR etc.) with a sensible title and good description (these are used to auto-generate the change log, at least partially).

[David Dickinson]

Discussion now moved to issue #71