1: #include <../src/ksp/ksp/impls/rich/richardsonimpl.h>

  3: /*@
  4:   KSPRichardsonSetScale - Set the damping factor; if this routine is not called, the factor defaults to 1.0.

  6:   Logically Collective

  8:   Input Parameters:
  9: + ksp   - the iterative context
 10: - scale - the damping factor

 12:   Options Database Key:
 13: . -ksp_richardson_scale scale - Set the scale factor

 15:   Level: intermediate

 17: .seealso: [](ch_ksp), `KSPRICHARDSON`, `KSPRichardsonSetSelfScale()`
 18: @*/
 19: PetscErrorCode KSPRichardsonSetScale(KSP ksp, PetscReal scale)
 20: {
 21:   PetscFunctionBegin;
 24:   PetscTryMethod(ksp, "KSPRichardsonSetScale_C", (KSP, PetscReal), (ksp, scale));
 25:   PetscFunctionReturn(PETSC_SUCCESS);
 26: }

 28: /*@
 29:   KSPRichardsonSetSelfScale - Sets Richardson to automatically determine optimal scaling at each iteration to minimize the 2-norm of the
 30:   preconditioned residual

 32:   Logically Collective

 34:   Input Parameters:
 35: + ksp   - the iterative context
 36: - scale - `PETSC_TRUE` or the default of `PETSC_FALSE`

 38:   Options Database Key:
 39: . -ksp_richardson_self_scale - Use self-scaling

 41:   Level: intermediate

 43:   Notes:
 44:   Requires two extra work vectors. Uses an extra `VecAXPY()` and `VecDotNorm2()` per iteration.

 46:   Changing this flag runs `KSPSetUp()` again, since the number of work vectors depends on it. The self-scaled variant has no block analog, so turning it on makes
 47:   `KSPMatSolve()` solve the right-hand sides one at a time instead of iterating on the whole block at once, and releases the work space that block iteration cached

 49:   Developer Note:
 50:   Could also minimize the 2-norm of the true residual with one less work vector

 52: .seealso: [](ch_ksp), `KSPRICHARDSON`, `KSPRichardsonSetScale()`, `KSPMatSolve()`
 53: @*/
 54: PetscErrorCode KSPRichardsonSetSelfScale(KSP ksp, PetscBool scale)
 55: {
 56:   PetscFunctionBegin;
 59:   PetscTryMethod(ksp, "KSPRichardsonSetSelfScale_C", (KSP, PetscBool), (ksp, scale));
 60:   PetscFunctionReturn(PETSC_SUCCESS);
 61: }