extra diagnostics - unification of approach

[kslong]

Right now, we have a bunch of extra diagnostics that can be turned on, and when this is done extra results are printed to a diagnostic file. This is a part of the code of course that we don't use once a problem has been solved, and so we don't have a uniform philosophy about how to do this. The result is that for some of the diagnostics write things out "in line". An example of this modes.track_resonant_scatters
where in trans_phot we open a file with a pointer to the file, and then we write to that file. On the other hand, for modes.save_extract_photons
the relevant code is in diag.c (the same is true of ispy with code in ispy.c).

I think we ought to systematize this a bit. My suggestion is that we write to one extra file in diag_whatever, and that all of the write statements to this begin with a keyword that identifies which of the various types of extra diagnostic is being printed out.

And I would put all of this into diag.c, so that we would see how it works together. The advantage I see from this is that it would make life easier if we want to add to write everything about a current photons position and frequency (which is what I need to do now for the import problem I am trying to solve with @jhmatthews ).

Does anyone have thoughts/objections to this @Higginbottom @smangham ?

Also, does any one use ispy? or should I simply remove this.

[kslong]

I've consolidates some of code into diag.c as I said I would on the dev branch, and put a new extra diagnostic in on the import branch in conjunction with #309

[jhmatthews]

Hi Knox. I agree with the suggestion, I think it makes things a bit more "modular" so that's good.

I noted in the parameter docs that ispy is very similar to cell_photon_stats but I believe the latter is slightly more complete. One can certainly be deprecated I think, probably ispy.

[kslong]

So currently this is set up this way on the import branch, and as such will be merged into dev at some point. The underlying idea is that we will try to have in hand some of the obvious things one would want to print out which we can use as circumstances arise and create new ones if necessary.

My felling is that we would repurpose some of these, and that we should clean out the calls to them once we are sure a problem is solved.

Here are the some of the details:

There is one file to which all of the diagnostics are written.

Which diagnostics are written depends on how various of the modes variables are set.

All of the various diagnostic routines should be line oriented and begin with a unique identifier to allow easy parsing of the outputs.

To add a new diagnostic one should
(0) check that one of the existing diagnostics is insufficient for your needs
(1) add a routine here that writes to the diagnostic file.
(2) add a rdpar statement in get_extra_the diagnostics
(3) Assure that your new routine has the appropriate doxygen description,
(4) Add a yaml file for the new rdpar statement), and
(5) call the routine with the appropriate conditionals from wherever you wish.

To partially enforce this approach , the ptr that is opened for the file, is actually in diag.c and not in python.h

Additionally, per @jhmatthews suggestion ispy has been deprecated (in this case removed.)

[kslong]

At present (180702), the code in python largely adheres to the philosophy described above so I am closing this issue. There is very brief documentation about this on the github wiki.