DIAG: improve user docs

[Dave Offiler]

Kjartan recommends improving our User Guide documentation for the PP/1DVAR diagnostics structures:

Dear Ian and Dave

Both the ROPP 1DVAR module and the ROPP preprocessor module have
the possibility of adding extra diagnostic data to the output. 
This is accomplished through the DIAG data structure which gets
written to the output by setting the flag output_diag = .true. in
the configuration file. I assume something similar exists in the
other ROPP modules.

It is a very useful feature that I have used a lot.

I have found the documentation of the DIAG structure and the
available output in the User Guide to be very limited. Both for 
the 1DVAR and the PP module. Here and there there are discussions
of elements in the  diag structure but there's no central listing
and I am fairly sure that there are a number of DIAG elements that
the code will output but that are  nowhere mentioned in the
documentation.

The I/O module user guide has a very, very useful listing of all
elements in the ROPROF structure. Something like that for the DIAG
structure would also be very helpful. Possibly located separately
in each module user guide. Also for some elements in the diag
structure a few lines of description might come in handy.

I don't know if something like that is envisioned or if there's a
good reason to not have it (e.g. diag is more intended as a tool
for developers, or ?)

Anyway, I've been plowing through documentation several times
looking for this without finding it and I thought I'd mention that
it is something I've missed as a user of ROPP.

Sincerely, Kjartan

[Ian Culverwell]

After some investigation, it appears that there is no overarching "DIAG" structure, which is common to all of ROPP (unlike ROprof). Instead, most of the modules have their own way of generating "data-for-developers":

ROPP_IO

The "-d" option in ropp2ropp etc sets msg_MODE = VerboseMode. This results in slightly more expansive written output from the message routines of ropp_utils.

ROPP also allows the user to add extra variables to the ROprof structure by means of the ropp_io_addvar routine. This is described in (currently) Sec 2.4.10 of ropp_io User Guide. A table showing the structure of the extra data in ROprof has been added to ROPP UG I at ROPP6.0.

ROPP_PP

As Kjartan says, extra output from ropp_pp can be made available by setting config%output_diag to TRUE in the configuration file. This results in the diag structure being appended to the ROprof structure. The diag structure is described in (currently) Table 4.2 of the ROPP UG III. This has been extended and updated for ROPP6.0.

ROPP_FM

As for ropp_io, the "-d" option in ropp_fm_bg2ro_1d and ropp_fm_bg2ro_2d results in msg_MODE being set to VerboseMode. The only "additional" data that can be produced are the gradients (wrt x) of refrac and bangle, if ropp_fm_bg2ro_1d is called without the -f option. (Strictly I suppose this makes it the default, not an extra, but I suspect that most users will call ropp_fm_bg2ro_1d with the "-f" option - not least because of the large size of the gradient matrices.) A note to this effect has been added to (currently) Sec 4.9.5 of ROPP UG II at ROPP6.0.

ROPP_1DVAR

Extra diagnostics for ropp_1dvar are produced by setting config%extended_1dvar_diag to TRUE in the configuration file. These variables (in the VarDiag structure) are enumerated in (currently) Tables 6.2 and 7.2 of ROPP User Guide II. These tables have been extended and updated at ROPP6.0.

[Ian Culverwell]

In addition, Appendix B of all the ROPP UG's now lists all the extra diagnostics available from all the ROPP modules, under the Troubleshooting header.

[Ian Culverwell]

Documentation changes approved by Kjartan Kinch as part of his ROPP6.0 beta review. Closing ticket.