Skip to content

Draft: Add ``PetscClippyBegin``, ``PetscClippyEnd``, and ``PetscClippyMessage`` to...

Barry Smith requested to merge barry/2022-07-08/add-clippy into main

Obviously "Clippy" would be replaced with Tutorial, TutorialMode or something before implementation. This is a request for comment on the idea of a tutorial mode to ease the learning curve. Is the entire idea just bad? What else can we do to ease the learning curve; improving kindergarten around the world to have everyone prepared to use PETSc is obviously the best answer but unlikely to happen. Our docs are definitely better, though not perfect, but who reads docs?

The clippy mode is for beginning users, it introduces CONTEXT dependent important basic concepts and usage clearly and exactly once for each run of a code. It will not suggest things that are currently being used. Many/most users discover these usages hit or miss or by email with the PETSc community, the information is available in the mass of documentation but most beginners will not read it all and certainly remember it.

Sample output.

mpiexec -n 2 ./ex19
Clippy: Welcome to PETSc's beginner mode, it displays helpful usage messages and hints
Clippy: To turn off clippy add the line -clippy 0 in the file ~/.petscrc or at the command line
Clippy: Suggest -ksp_monitor to see how the linear iterative solver is converging
Clippy: Suggest -ksp_converged_reason to see why the linear iterative solver has converged or diverged
Clippy:    By default the solver does not generate an error if it does not converge,
Clippy:    your code should call KSPGetConvergedReason() after each solve.
Clippy:    When debugging solver suggest-ksp_error_if_not_converged
Clippy: Suggest -ksp_view to see exactly what solver and options are being used
Clippy: The default preconditioner block Jacobi plus ILU is being used. This is generally a slow preconditioner
Clippy:    See .. _sec_pc: for how to select more appropriate preconditioners for your problem
Clippy: The default Krylov method of GMRES is being used, often this is the best choice
Clippy:    See .. _sec_ksp: for information on when efficient Krylov methods may be used

Clippy: Your matrix memory has not been preallocated, your code will be slow
Clippy:    See .. _sec_preallocation: for how to preallocate matrix memory

This is all straight forward to implement, the tricky part is knowing when to turn it on (Jed won't want it turned on just because he built PETSc on a new machine) and how to know when to stop printing certain messages (after the message has been printed in in different runs 10 times?). Where would the counts be stored, in ~/.petsc_clippy? Some people don't like applications trodding around in such locations but Unix offers nothing better.

Context, for example
  the -ksp_converged_reason might be displayed only if the linear system did not converge?
  the default preconditioner message might only appear if a "large number of iterations" is used?

Commit-type: documentation, feature
Thanks-to: Melinda Gates
Edited by Barry Smith

Merge request reports