Refine debug

[kellertuer]

Yesterday I was a bit annoyed, when trying to help @flgoyens on a debug issue. Especially, besides the :Stop to debug the stopping criterion, everything was added to :All which still meant it was only reset on start and called in the iteration.

This aims to resolve this.

• [x] introduces a new hook at the beginning of the iteration
• [x] refine when debugs are reset on start
• [x] remove the :All entry, that was used (exclusively) until now
• [x] introduce a new entry in debug= with Pairs to allow more control where to put Debug.

Since all this is internal and none of the other tests broke, I would consider this still non-breaking (since I assume besides me no one explicitly used :All). All old arrays of debug= still work

I started a few examples in the docs. The new possibilities are now

• debug = [:Iteration, " | ", :Cost, :Stop] works as before but
• debug = [ :BeforeIteration => :Iteration, " | ", :Cost] is the new notation that specifically adds :Iteration printing to before calling a step.
• debug = [:BeforeIteration => :Iteration, :Iteration => [" | ", :Cost], :Stop => :Stop] is now also new but equivalent to the previous one , since :Stop is always added to the end of the algorithm (stored in :Stop) and by default all other things are added to the iteration step (now) at :Iteration.

The last point also shows that this is basically debugception. We can have sequences of debug in single sub-spaces. So this is more precise, but we keep the simplicity from before (all old debug specifications work as before), but also more flexible.

ToDo

• [x] refine the documentation
• [x] extend the tutorial to cover this as well, e.g. printing the iteration number before the subsolver starts

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.73%. Comparing base (8124786) to head (f5ddd78).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #370 +/- ## ======================================= Coverage 99.73% 99.73% ======================================= Files 73 73 Lines 6839 6876 +37 ======================================= + Hits 6821 6858 +37 Misses 18 18 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[kellertuer]

Oh I just noticed the mechanism with DebugEvery does no longer work in this setting.

Until now it “activated” the sub solvers output “for the next iteration” since it was called in the iteration debug after the iteration. Currently it is called (in the example) before the iteration already, hence I had to fix the number (because now it activated one too early basically). this has to be adapted and I am not yet 100% sure how, maybe with a double check

The two things that have to work is

1. At the current iteration :BeforeIteration might set the subsolver active (if present)
2. At an iteration :Iteration might set active for the next iteration

The problem is that the DebugEvery does not “know” which of these two states it is in, so maybe this has to become a variable somehow.

[kellertuer]

I found a solution, the DebugEvery now has an activation_offset to distinguish between this and next iteration to activate, :BeforeIteration sets the default 1 (next) to 0 (this). 1 stays the default since when doing all this by hand (the debug dictionary) the current default will stay the one most used (after iteration debug -> next iterations activation).

[kellertuer]

Here is the new feature summarised https://manoptjl.org/previews/PR370/tutorials/HowToDebug/#Specifying-when-to-print-something – the next section can now also show an even nicer print for sub-solvers, since the iteration number can now first be printed, before the subsolver starts printing.