# petsc4py.PETSc.KSP

class petsc4py.PETSc.KSP

  Bases: `Object`

  Abstract PETSc object that manages all Krylov methods.

  This is the object that manages the linear solves in PETSc (even those such as direct solvers that do no use Krylov accelerators).

  Notes

  When a direct solver is used, but no Krylov solver is used, the KSP object is still used but with a `Type.PREONLY`, meaning that only application of the preconditioner is used as the linear solver.

  See also

  `create`, `setType`, `SNES`, `TS`, `PC`, `Type.CG`, `Type.GMRES`, `KSP`

  Enumerations

  `ConvergedReason` | KSP Converged Reason.
  `HPDDMType` | The HPDDM Krylov solver type.
  `NormType` | KSP norm type.
  `Type` | KSP Type.

  Methods Summary

  `addConvergenceTest`(converged[, args, kargs, ...]) | Add the function to be used to determine convergence.
  `appendOptionsPrefix`(prefix) | Append to prefix used for all `KSP` options in the database.
  `buildResidual`([r]) | Return the residual of the linear system.
  `buildSolution`([x]) | Return the solution vector.
  `callConvergenceTest`(its, rnorm) | Call the convergence test callback.
  `computeEigenvalues`() | Compute the extreme eigenvalues for the preconditioned operator.
  `computeExtremeSingularValues`() | Compute the extreme singular values for the preconditioned operator.
  `create`([comm]) | Create the KSP context.
  `createPython`([context, comm]) | Create a linear solver of Python type.
  `destroy`() | Destroy KSP context.
  `getAppCtx`() | Return the user-defined context for the linear solver.
  `getCGObjectiveValue`() | Return the CG objective function value.
  `getComputeEigenvalues`() | Return flag indicating whether eigenvalues will be calculated.
  `getComputeSingularValues`() | Return flag indicating whether singular values will be calculated.
  `getConvergedReason`() | Use `reason` property.
  `getConvergenceHistory`() | Return array containing the residual history.
  `getConvergenceTest`() | Return the function to be used to determine convergence.
  `getDM`() | Return the `DM` that may be used by some preconditioners.
  `getErrorIfNotConverged`() | Return the flag indicating the solver will error if divergent.
  `getHPDDMType`() | Return the Krylov solver type.
  `getInitialGuessKnoll`() | Determine whether the KSP solver is using the Knoll trick.
  `getInitialGuessNonzero`() | Determine whether the KSP solver uses a zero initial guess.
  `getIterationNumber`() | Use `its` property.
  `getMonitor`() | Return function used to monitor the residual.
  `getNormType`() | Return the norm that is used for convergence testing.
  `getOperators`() | Return the matrix associated with the linear system.
  `getOptionsPrefix`() | Return the prefix used for all `KSP` options in the database.
  `getPC`() | Return the preconditioner.
  `getPCSide`() | Return the preconditioning side.
  `getPythonContext`() | Return the instance of the class implementing Python methods.
  `getPythonType`() | Return the fully qualified Python name of the class used by the solver.
  `getResidualNorm`() | Use `norm` property.
  `getRhs`() | Return the right-hand side vector for the linear system.
  `getSolution`() | Return the solution for the linear system to be solved.
  `getTolerances`() | Return various tolerances used by the KSP convergence tests.
  `getType`() | Return the KSP type as a string from the `KSP` object.
  `getWorkVecs`([right, left]) | Create working vectors.
  `logConvergenceHistory`(rnorm) | Add residual to convergence history.
  `matSolve`(B, X) | Solve a linear system with multiple right-hand sides.
  `matSolveTranspose`(B, X) | Solve the transpose of a linear system with multiple RHS.
  `monitor`(its, rnorm) | Run the user provided monitor routines, if they exist.
  `monitorCancel`() | Clear all monitors for a `KSP` object.
  `reset`() | Resets a KSP context.
  `setAppCtx`(appctx) | Set the optional user-defined context for the linear solver.
  `setComputeEigenvalues`(flag) | Set a flag to compute eigenvalues.
  `setComputeOperators`(operators[, args, kargs]) | Set routine to compute the linear operators.
  `setComputeRHS`(rhs[, args, kargs]) | Set routine to compute the right-hand side of the linear system.
  `setComputeSingularValues`(flag) | Set flag to calculate singular values.
  `setConvergedReason`(reason) | Use `reason` property.
  `setConvergenceHistory`([length, reset]) | Set the array used to hold the residual history.
  `setConvergenceTest`(converged[, args, kargs]) | Set the function to be used to determine convergence.
  `setDM`(dm) | Set the `DM` that may be used by some preconditioners.
  `setDMActive`(flag) | `DM` should be used to generate system matrix & RHS vector.
  `setErrorIfNotConverged`(flag) | Cause `solve` to generate an error if not converged.
  `setFromOptions`() | Set `KSP` options from the options database.
  `setGMRESRestart`(restart) | Set number of iterations at which KSP restarts.
  `setHPDDMType`(hpddm_type) | Set the Krylov solver type.
  `setInitialGuessKnoll`(flag) | Tell solver to use `PC.apply` to compute the initial guess.
  `setInitialGuessNonzero`(flag) | Tell the iterative solver that the initial guess is nonzero.
  `setIterationNumber`(its) | Use `its` property.
  `setMonitor`(monitor[, args, kargs]) | Set additional function to monitor the residual.
  `setNormType`(normtype) | Set the norm that is used for convergence testing.
  `setOperators`([A, P]) | Set matrix associated with the linear system.
  `setOptionsPrefix`(prefix) | Set the prefix used for all `KSP` options in the database.
  `setPC`(pc) | Set the preconditioner.
  `setPCSide`(side) | Set the preconditioning side.
  `setPostSolve`(postsolve[, args, kargs]) | Set the function that is called at the end of each `KSP.solve`.
  `setPreSolve`(presolve[, args, kargs]) | Set the function that is called at the beginning of each `KSP.solve`.
  `setPythonContext`([context]) | Set the instance of the class implementing Python methods.
  `setPythonType`(py_type) | Set the fully qualified Python name of the class to be used.
  `setResidualNorm`(rnorm) | Use `norm` property.
  `setTolerances`([rtol, atol, divtol, max_it]) | Set various tolerances used by the KSP convergence testers.
  `setType`(ksp_type) | Build the `KSP` data structure for a particular `Type`.
  `setUp`() | Set up internal data structures for an iterative solver.
  `setUpOnBlocks`() | Set up the preconditioner for each block in a block method.
  `setUseFischerGuess`(model, size) | Use the Paul Fischer algorithm to compute initial guesses.
  `solve`(b, x) | Solve the linear system.
  `solveTranspose`(b, x) | Solve the transpose of a linear system.
  `view`([viewer]) | Print the KSP data structure.

  Attributes Summary

  `appctx` | The solver application context.
  `atol` | The absolute tolerance of the solver.
  `divtol` | The divergence tolerance of the solver.
  `dm` | The solver `DM`.
  `guess_knoll` | Whether solver uses Knoll trick.
  `guess_nonzero` | Whether guess is non-zero.
  `history` | The convergence history of the solver.
  `is_converged` | Boolean indicating if the solver has converged.
  `is_diverged` | Boolean indicating if the solver has failed.
  `is_iterating` | Boolean indicating if the solver has not converged yet.
  `its` | The current number of iterations the solver has taken.
  `mat_op` | The system matrix operator.
  `mat_pc` | The preconditioner operator.
  `max_it` | The maximum number of iteration the solver may take.
  `norm` | The norm of the residual at the current iteration.
  `norm_type` | The norm used by the solver.
  `pc` | The `PC` of the solver.
  `pc_side` | The side on which preconditioning is performed.
  `reason` | The converged reason.
  `rtol` | The relative tolerance of the solver.
  `vec_rhs` | The right-hand side vector.
  `vec_sol` | The solution vector.

  Methods Documentation

  addConvergenceTest(converged, args=None, kargs=None, prepend=False)

    Add the function to be used to determine convergence.

    Logically collective.

    Parameters:

      - converged (KSPConvergenceTestFunction) – Callback which computes the convergence.

      - args (tuple[Any, ...] | None) – Positional arguments for callback function.

      - kargs (dict[str, Any] | None) – Keyword arguments for callback function.

      - prepend (bool) – Whether to prepend this call before the default convergence test or call it after.

    Return type:

      None

    Notes

    Cannot be mixed with a call to `setConvergenceTest`. It can only be called once. If called multiple times, it will generate an error.

    See also

    `setTolerances`, `getConvergenceTest`, `setConvergenceTest`, `KSPSetConvergenceTest`, `KSPConvergedDefault`

    Source code at petsc4py/PETSc/KSP.pyx:1065

  appendOptionsPrefix(prefix)

    Append to prefix used for all `KSP` options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The options prefix to append.

    Return type:

      None

    Notes

    A hyphen (-) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen.

    See also

    `KSPAppendOptionsPrefix`

    Source code at petsc4py/PETSc/KSP.pyx:575

  buildResidual(r=None)

    Return the residual of the linear system.

    Collective.

    Parameters:

      r (Vec | None) – Optional vector to use for the result.

    Return type:

      Vec

    See also

    `buildSolution`, `KSPBuildResidual`

    Source code at petsc4py/PETSc/KSP.pyx:2063

  buildSolution(x=None)

    Return the solution vector.

    Collective.

    Parameters:

      x (Vec | None) – Optional vector to store the solution.

    Return type:

      Vec

    See also

    `buildResidual`, `KSPBuildSolution`

    Source code at petsc4py/PETSc/KSP.pyx:2041

  callConvergenceTest(its, rnorm)

    Call the convergence test callback.

    Collective.

    Parameters:

      - its (int) – Number of iterations.

      - rnorm (float) – The residual norm.

    Return type:

      None

    Notes

    This functionality is implemented in petsc4py.

    Source code at petsc4py/PETSc/KSP.pyx:1121

  computeEigenvalues()

    Compute the extreme eigenvalues for the preconditioned operator.

    Not collective.

    See also

    `KSPComputeEigenvalues`

    Source code at petsc4py/PETSc/KSP.pyx:2085

    Return type:

      ArrayComplex

  computeExtremeSingularValues()

    Compute the extreme singular values for the preconditioned operator.

    Collective.

    Returns:

      - smax (`float`) – The maximum singular value.

      - smin (`float`) – The minimum singular value.

    Return type:

      tuple[float, float]

    See also

    `KSPComputeExtremeSingularValues`

    Source code at petsc4py/PETSc/KSP.pyx:2108

  create(comm=None)

    Create the KSP context.

    Collective.

    See also

    `KSPCreate`

    Source code at petsc4py/PETSc/KSP.pyx:457

    Parameters:

      comm (Comm | None)

    Return type:

      Self

  createPython(context=None, comm=None)

    Create a linear solver of Python type.

    Collective.

    Parameters:

      - context (Any) – An instance of the Python class implementing the required methods.

      - comm (Comm | None) – MPI communicator, defaults to `Sys.getDefaultComm`.

    Return type:

      Self

    See also

    PETSc Python linear solver type, `setType`, `setPythonContext`, `Type.PYTHON`

    Source code at petsc4py/PETSc/KSP.pyx:2154

  destroy()

    Destroy KSP context.

    Collective.

    See also

    `KSPDestroy`

    Source code at petsc4py/PETSc/KSP.pyx:444

    Return type:

      Self

  getAppCtx()

    Return the user-defined context for the linear solver.

    Not collective.

    See also

    `setAppCtx`

    Source code at petsc4py/PETSc/KSP.pyx:640

    Return type:

      Any

  getCGObjectiveValue()

    Return the CG objective function value.

    Not collective.

    See also

    `KSPCGGetObjFcn`

    Source code at petsc4py/PETSc/KSP.pyx:1882

    Return type:

      float

  getComputeEigenvalues()

    Return flag indicating whether eigenvalues will be calculated.

    Not collective.

    Return the flag indicating that the extreme eigenvalues values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

    See also

    `setComputeEigenvalues`, `KSPSetComputeEigenvalues`

    Source code at petsc4py/PETSc/KSP.pyx:1430

    Return type:

      bool

  getComputeSingularValues()

    Return flag indicating whether singular values will be calculated.

    Not collective.

    Return the flag indicating whether the extreme singular values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

    See also

    `setComputeSingularValues`, `KSPGetComputeSingularValues`

    Source code at petsc4py/PETSc/KSP.pyx:1474

    Return type:

      bool

  getConvergedReason()

    Use `reason` property.

    Source code at petsc4py/PETSc/KSP.pyx:1876

    Return type:

      ConvergedReason

  getConvergenceHistory()

    Return array containing the residual history.

    Not collective.

    See also

    `setConvergenceHistory`, `KSPGetResidualHistory`

    Source code at petsc4py/PETSc/KSP.pyx:1188

    Return type:

      ArrayReal

  getConvergenceTest()

    Return the function to be used to determine convergence.

    Logically collective.

    See also

    `setTolerances`, `setConvergenceTest`, `KSPGetConvergenceTest`, `KSPConvergedDefault`

    Source code at petsc4py/PETSc/KSP.pyx:1108

    Return type:

      KSPConvergenceTestFunction

  getDM()

    Return the `DM` that may be used by some preconditioners.

    Not collective.

    See also

    `PETSc.KSP`, `DM`, `KSPGetDM`

    Source code at petsc4py/PETSc/KSP.pyx:654

    Return type:

      DM

  getErrorIfNotConverged()

    Return the flag indicating the solver will error if divergent.

    Not collective.

    See also

    `KSPGetErrorIfNotConverged`

    Source code at petsc4py/PETSc/KSP.pyx:1946

    Return type:

      bool

  getHPDDMType()

    Return the Krylov solver type.

    Not collective.

    See also

    `KSPHPDDMGetType`

    Source code at petsc4py/PETSc/KSP.pyx:1914

    Return type:

      HPDDMType

  getInitialGuessKnoll()

    Determine whether the KSP solver is using the Knoll trick.

    Not collective.

    This uses the Knoll trick; using `PC.apply` to compute the initial guess.

    See also

    `KSPGetInitialGuessKnoll`

    Source code at petsc4py/PETSc/KSP.pyx:1550

    Return type:

      bool

  getInitialGuessNonzero()

    Determine whether the KSP solver uses a zero initial guess.

    Not collective.

    See also

    `KSPGetInitialGuessNonzero`

    Source code at petsc4py/PETSc/KSP.pyx:1516

    Return type:

      bool

  getIterationNumber()

    Use `its` property.

    Source code at petsc4py/PETSc/KSP.pyx:1854

    Return type:

      int

  getMonitor()

    Return function used to monitor the residual.

    Not collective.

    See also

    Working with PETSc options, `setMonitor`, `monitor`, `monitorCancel`, `KSPGetMonitorContext`

    Source code at petsc4py/PETSc/KSP.pyx:1266

    Return type:

      KSPMonitorFunction

  getNormType()

    Return the norm that is used for convergence testing.

    Not collective.

    See also

    `NormType`, `setNormType`, `KSPGetNormType`, `KSPConvergedSkip`

    Source code at petsc4py/PETSc/KSP.pyx:1390

    Return type:

      NormType

  getOperators()

    Return the matrix associated with the linear system.

    Collective.

    Return the matrix associated with the linear system and a (possibly) different one used to construct the preconditioner.

    Returns:

      - A (`Mat`) – Matrix that defines the linear system.

      - P (`Mat`) – Matrix to be used in constructing the preconditioner, usually the same as `A`.

    Return type:

      tuple[Mat, Mat]

    See also

    `PETSc.KSP`, `solve`, `setOperators`, `KSPGetOperators`

    Source code at petsc4py/PETSc/KSP.pyx:850

  getOptionsPrefix()

    Return the prefix used for all `KSP` options in the database.

    Not collective.

    See also

    `KSPGetOptionsPrefix`

    Source code at petsc4py/PETSc/KSP.pyx:561

    Return type:

      str

  getPC()

    Return the preconditioner.

    Not collective.

    See also

    `PETSc.KSP`, `setPC`, `KSPGetPC`

    Source code at petsc4py/PETSc/KSP.pyx:897

    Return type:

      PC

  getPCSide()

    Return the preconditioning side.

    Not collective.

    See also

    Working with PETSc options, `setPCSide`, `setNormType`, `getNormType`, `KSPGetPCSide`

    Source code at petsc4py/PETSc/KSP.pyx:1349

    Return type:

      Side

  getPythonContext()

    Return the instance of the class implementing Python methods.

    Not collective.

    See also

    PETSc Python linear solver type, `setPythonContext`

    Source code at petsc4py/PETSc/KSP.pyx:2195

    Return type:

      Any

  getPythonType()

    Return the fully qualified Python name of the class used by the solver.

    Not collective.

    See also

    PETSc Python linear solver type, `setPythonContext`, `setPythonType`, `KSPPythonGetType`

    Source code at petsc4py/PETSc/KSP.pyx:2225

    Return type:

      str

  getResidualNorm()

    Use `norm` property.

    Source code at petsc4py/PETSc/KSP.pyx:1865

    Return type:

      float

  getRhs()

    Return the right-hand side vector for the linear system.

    Not collective.

    See also

    `KSPGetRhs`

    Source code at petsc4py/PETSc/KSP.pyx:1960

    Return type:

      Vec

  getSolution()

    Return the solution for the linear system to be solved.

    Not collective.

    Note that this may not be the solution that is stored during the iterative process.

    See also

    `KSPGetSolution`

    Source code at petsc4py/PETSc/KSP.pyx:1975

    Return type:

      Vec

  getTolerances()

    Return various tolerances used by the KSP convergence tests.

    Not collective.

    Return the relative, absolute, divergence, and maximum iteration tolerances used by the default KSP convergence tests.

    Returns:

      - rtol (`float`) – The relative convergence tolerance

      - atol (`float`) – The absolute convergence tolerance

      - dtol (`float`) – The divergence tolerance

      - maxits (`int`) – Maximum number of iterations

    Return type:

      tuple[float, float, float, int]

    See also

    `setTolerances`, `KSPGetTolerances`

    Source code at petsc4py/PETSc/KSP.pyx:971

  getType()

    Return the KSP type as a string from the `KSP` object.

    Not collective.

    See also

    `KSPGetType`

    Source code at petsc4py/PETSc/KSP.pyx:509

    Return type:

      str

  getWorkVecs(right=None, left=None)

    Create working vectors.

    Collective.

    Parameters:

      - right (int | None) – Number of right hand vectors to allocate.

      - left (int | None) – Number of left hand vectors to allocate.

    Returns:

      - R (`list` of `Vec`) – List of correctly allocated right hand vectors.

      - L (`list` of `Vec`) – List of correctly allocated left hand vectors.

    Return type:

      tuple[list[Vec], list[Vec]] | list[Vec] | None

    Source code at petsc4py/PETSc/KSP.pyx:1993

  logConvergenceHistory(rnorm)

    Add residual to convergence history.

    Logically collective.

    Parameters:

      rnorm (float) – Residual norm to be added to convergence history.

    Return type:

      None

    Source code at petsc4py/PETSc/KSP.pyx:1203

  matSolve(B, X)

    Solve a linear system with multiple right-hand sides.

    Collective.

    These are stored as a `Mat.Type.DENSE`. Unlike `solve`, `B` and `X` must be different matrices.

    Parameters:

      - B (Mat) – Block of right-hand sides.

      - X (Mat) – Block of solutions.

    Return type:

      None

    See also

    `solve`, `KSPMatSolve`

    Source code at petsc4py/PETSc/KSP.pyx:1808

  matSolveTranspose(B, X)

    Solve the transpose of a linear system with multiple RHS.

    Collective.

    Parameters:

      - B (Mat) – Block of right-hand sides.

      - X (Mat) – Block of solutions.

    Return type:

      None

    See also

    `solveTranspose`, `KSPMatSolve`

    Source code at petsc4py/PETSc/KSP.pyx:1830

  monitor(its, rnorm)

    Run the user provided monitor routines, if they exist.

    Collective.

    Notes

    This routine is called by the `KSP` implementations. It does not typically need to be called by the user.

    See also

    `setMonitor`, `KSPMonitor`

    Source code at petsc4py/PETSc/KSP.pyx:1294

    Parameters:

      - its (int)

      - rnorm (float)

    Return type:

      None

  monitorCancel()

    Clear all monitors for a `KSP` object.

    Logically collective.

    See also

    Working with PETSc options, `getMonitor`, `setMonitor`, `monitor`, `KSPMonitorCancel`

    Source code at petsc4py/PETSc/KSP.pyx:1279

    Return type:

      None

  reset()

    Resets a KSP context.

    Collective.

    Resets a KSP context to the `kspsetupcalled = 0` state and removes any allocated Vecs and Mats.

    See also

    `KSPReset`

    Source code at petsc4py/PETSc/KSP.pyx:1607

    Return type:

      None

  setAppCtx(appctx)

    Set the optional user-defined context for the linear solver.

    Not collective.

    Parameters:

      appctx (Any) – The user defined context

    Return type:

      None

    Notes

    The user context is a way for users to attach any information to the `KSP` that they may need later when interacting with the solver.

    See also

    `getAppCtx`

    Source code at petsc4py/PETSc/KSP.pyx:617

  setComputeEigenvalues(flag)

    Set a flag to compute eigenvalues.

    Logically collective.

    Set a flag so that the extreme eigenvalues values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

    Parameters:

      flag (bool) – Boolean whether to compute eigenvalues (or not).

    Return type:

      None

    Notes

    Currently this option is not valid for all iterative methods.

    See also

    `getComputeEigenvalues`, `KSPSetComputeEigenvalues`

    Source code at petsc4py/PETSc/KSP.pyx:1404

  setComputeOperators(operators, args=None, kargs=None)

    Set routine to compute the linear operators.

    Logically collective.

    Parameters:

      - operators (KSPOperatorsFunction) – Function which computes the operators.

      - args (tuple[Any, ...] | None) – Positional arguments for callback function `operators`.

      - kargs (dict[str, Any] | None) – Keyword arguments for callback function `operators`.

    Return type:

      None

    Notes

    The user provided function `Operators` will be called automatically at the very next call to `solve`. It will NOT be called at future `solve` calls unless either `setComputeOperators` or `setOperators` is called before that `solve` is called. This allows the same system to be solved several times with different right-hand side functions, but is a confusing API since one might expect it to be called for each `solve`.

    To reuse the same preconditioner for the next `solve` and not compute a new one based on the most recently computed matrix call `KSPSetReusePreconditioner`.

    See also

    `PETSc.KSP`, `solve`, `setOperators`, `KSPSetComputeOperators`, `KSPSetReusePreconditioner`

    Source code at petsc4py/PETSc/KSP.pyx:764

  setComputeRHS(rhs, args=None, kargs=None)

    Set routine to compute the right-hand side of the linear system.

    Logically collective.

    Parameters:

      - rhs (KSPRHSFunction) – Function which computes the right-hand side.

      - args (tuple[Any, ...] | None) – Positional arguments for callback function `rhs`.

      - kargs (dict[str, Any] | None) – Keyword arguments for callback function `rhs`.

    Return type:

      None

    Notes

    The routine you provide will be called each time you call `solve` to prepare the new right-hand side for that solve.

    See also

    `PETSc.KSP`, `solve`, `KSPSetComputeRHS`

    Source code at petsc4py/PETSc/KSP.pyx:730

  setComputeSingularValues(flag)

    Set flag to calculate singular values.

    Logically collective.

    Set a flag so that the extreme singular values will be calculated via a Lanczos or Arnoldi process as the linear system is solved.

    Parameters:

      flag (bool) – Boolean whether to compute singular values (or not).

    Return type:

      None

    Notes

    Currently this option is not valid for all iterative methods.

    See also

    `getComputeSingularValues`, `KSPSetComputeSingularValues`

    Source code at petsc4py/PETSc/KSP.pyx:1448

  setConvergedReason(reason)

    Use `reason` property.

    Source code at petsc4py/PETSc/KSP.pyx:1871

    Parameters:

      reason (ConvergedReason)

    Return type:

      None

  setConvergenceHistory(length=None, reset=False)

    Set the array used to hold the residual history.

    Not collective.

    If set, this array will contain the residual norms computed at each iteration of the solver.

    Parameters:

      - length (int | None) – Length of array to store history in.

      - reset (bool) – `True` indicates the history counter is reset to zero for each new linear solve.

    Return type:

      None

    Notes

    If `length` is not provided or `None` then a default array of length 10000 is allocated.

    If the array is not long enough then once the iterations is longer than the array length `solve` stops recording the history.

    See also

    `getConvergenceHistory`, `KSPSetResidualHistory`

    Source code at petsc4py/PETSc/KSP.pyx:1144

  setConvergenceTest(converged, args=None, kargs=None)

    Set the function to be used to determine convergence.

    Logically collective.

    Parameters:

      - converged (KSPConvergenceTestFunction) – Callback which computes the convergence.

      - args (tuple[Any, ...] | None) – Positional arguments for callback function.

      - kargs (dict[str, Any] | None) – Keyword arguments for callback function.

    Return type:

      None

    Notes

    Must be called after the KSP type has been set so put this after a call to `setType`, or `setFromOptions`.

    The default is a combination of relative and absolute tolerances. The residual value that is tested may be an approximation; routines that need exact values should compute them.

    See also

    `addConvergenceTest`, `ConvergedReason`, `setTolerances`, `getConvergenceTest`, `buildResidual`, `KSPSetConvergenceTest`, `KSPConvergedDefault`

    Source code at petsc4py/PETSc/KSP.pyx:1000

  setDM(dm)

    Set the `DM` that may be used by some preconditioners.

    Logically collective.

    Parameters:

      dm (DM) – The `DM` object, cannot be `None`.

    Return type:

      None

    Notes

    If this is used then the `KSP` will attempt to use the `DM` to create the matrix and use the routine set with `DM.setKSPComputeOperators`. Use `setDMActive(False)` to instead use the matrix you have provided with `setOperators`.

    A `DM` can only be used for solving one problem at a time because information about the problem is stored on the `DM`, even when not using interfaces like `DM.setKSPComputeOperators`. Use `DM.clone` to get a distinct `DM` when solving different problems using the same function space.

    See also

    `PETSc.KSP`, `DM`, `DM.setKSPComputeOperators`, `setOperators`, `DM.clone`, `KSPSetDM`

    Source code at petsc4py/PETSc/KSP.pyx:671

  setDMActive(flag)

    `DM` should be used to generate system matrix & RHS vector.

    Logically collective.

    Parameters:

      flag (bool) – Whether to use the `DM`.

    Return type:

      None

    Notes

    By default `setDM` sets the `DM` as active, call `setDMActive(False)` after `setDM(dm)` to not have the `KSP` object use the `DM` to generate the matrices.

    See also

    `PETSc.KSP`, `DM`, `setDM`, `KSPSetDMActive`

    Source code at petsc4py/PETSc/KSP.pyx:704

  setErrorIfNotConverged(flag)

    Cause `solve` to generate an error if not converged.

    Logically collective.

    Parameters:

      flag (bool) – `True` enables this behavior.

    Return type:

      None

    See also

    `KSPSetErrorIfNotConverged`

    Source code at petsc4py/PETSc/KSP.pyx:1928

  setFromOptions()

    Set `KSP` options from the options database.

    Collective.

    This routine must be called before `setUp` if the user is to be allowed to set the Krylov type.

    See also

    Working with PETSc options, `KSPSetFromOptions`

    Source code at petsc4py/PETSc/KSP.pyx:600

    Return type:

      None

  setGMRESRestart(restart)

    Set number of iterations at which KSP restarts.

    Logically collective.

    Suitable KSPs are: KSPGMRES, KSPFGMRES and KSPLGMRES.

    Parameters:

      restart (int) – Integer restart value.

    Return type:

      None

    See also

    `KSPGMRESSetRestart`

    Source code at petsc4py/PETSc/KSP.pyx:2132

  setHPDDMType(hpddm_type)

    Set the Krylov solver type.

    Collective.

    Parameters:

      hpddm_type (HPDDMType) – The type of Krylov solver to use.

    Return type:

      None

    See also

    `KSPHPDDMSetType`

    Source code at petsc4py/PETSc/KSP.pyx:1896

  setInitialGuessKnoll(flag)

    Tell solver to use `PC.apply` to compute the initial guess.

    Logically collective.

    This is the Knoll trick.

    Parameters:

      flag (bool) – `True` uses Knoll trick.

    Return type:

      None

    See also

    `KSPSetInitialGuessKnoll`

    Source code at petsc4py/PETSc/KSP.pyx:1530

  setInitialGuessNonzero(flag)

    Tell the iterative solver that the initial guess is nonzero.

    Logically collective.

    Otherwise KSP assumes the initial guess is to be zero (and thus zeros it out before solving).

    Parameters:

      flag (bool) – `True` indicates the guess is non-zero, `False` indicates the guess is zero.

    Return type:

      None

    See also

    `KSPSetInitialGuessNonzero`

    Source code at petsc4py/PETSc/KSP.pyx:1494

  setIterationNumber(its)

    Use `its` property.

    Source code at petsc4py/PETSc/KSP.pyx:1849

    Parameters:

      its (int)

    Return type:

      None

  setMonitor(monitor, args=None, kargs=None)

    Set additional function to monitor the residual.

    Logically collective.

    Set an ADDITIONAL function to be called at every iteration to monitor the residual/error etc.

    Parameters:

      - monitor (KSPMonitorFunction) – Callback which monitors the convergence.

      - args (tuple[Any, ...] | None) – Positional arguments for callback function.

      - kargs (dict[str, Any] | None) – Keyword arguments for callback function.

    Return type:

      None

    Notes

    The default is to do nothing. To print the residual, or preconditioned residual if `setNormType(NORM_PRECONDITIONED)` was called, use `monitor` as the monitoring routine, with a `PETSc.Viewer.ASCII` as the context.

    Several different monitoring routines may be set by calling `setMonitor` multiple times; all will be called in the order in which they were set.

    See also

    Working with PETSc options, `getMonitor`, `monitor`, `monitorCancel`, `KSPMonitorSet`

    Source code at petsc4py/PETSc/KSP.pyx:1219

  setNormType(normtype)

    Set the norm that is used for convergence testing.

    Logically collective.

    Parameters:

      normtype (NormType) – The norm type to use (see `NormType`).

    Return type:

      None

    Notes

    Not all combinations of preconditioner side (see `setPCSide`) and norm type are supported by all Krylov methods. If only one is set, PETSc tries to automatically change the other to find a compatible pair. If no such combination is supported, PETSc will generate an error.

    See also

    `NormType`, Working with PETSc options, `setUp`, `solve`, `destroy`, `setPCSide`, `getPCSide`, `NormType`, `KSPSetNormType`, `KSPConvergedSkip`, `KSPSetCheckNormIteration`

    Source code at petsc4py/PETSc/KSP.pyx:1363

  setOperators(A=None, P=None)

    Set matrix associated with the linear system.

    Collective.

    Set the matrix associated with the linear system and a (possibly) different one from which the preconditioner will be built.

    Parameters:

      - A (Mat | None) – Matrix that defines the linear system.

      - P (Mat | None) – Matrix to be used in constructing the preconditioner, usually the same as `A`.

    Return type:

      None

    Notes

    If you know the operator `A` has a null space you can use `Mat.setNullSpace` and `Mat.setTransposeNullSpace` to supply the null space to `A` and the `KSP` solvers will automatically use that null space as needed during the solution process.

    All future calls to `setOperators` must use the same size matrices!

    Passing `None` for `A` or `P` removes the matrix that is currently used.

    See also

    `PETSc.KSP`, `solve`, `setComputeOperators`, `KSPSetOperators`

    Source code at petsc4py/PETSc/KSP.pyx:809

  setOptionsPrefix(prefix)

    Set the prefix used for all `KSP` options in the database.

    Logically collective.

    Parameters:

      prefix (str | None) – The options prefix.

    Return type:

      None

    Notes

    A hyphen (-) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen. For example, to distinguish between the runtime options for two different `KSP` contexts, one could call `` KSPSetOptionsPrefix(ksp1, "sys1_") KSPSetOptionsPrefix(ksp2, "sys2_") ``

    This would enable use of different options for each system, such as `` -sys1_ksp_type gmres -sys1_ksp_rtol 1.e-3 -sys2_ksp_type bcgs -sys2_ksp_rtol 1.e-4 ``

    See also

    Working with PETSc options, `KSPSetOptionsPrefix`

    Source code at petsc4py/PETSc/KSP.pyx:523

  setPC(pc)

    Set the preconditioner.

    Collective.

    Set the preconditioner to be used to calculate the application of the preconditioner on a vector.

    Parameters:

      pc (PC) – The preconditioner object

    Return type:

      None

    See also

    `PETSc.KSP`, `getPC`, `KSPSetPC`

    Source code at petsc4py/PETSc/KSP.pyx:877

  setPCSide(side)

    Set the preconditioning side.

    Logically collective.

    Parameters:

      side (Side) – The preconditioning side (see `PC.Side`).

    Return type:

      None

    Notes

    Left preconditioning is used by default for most Krylov methods except `Type.FGMRES` which only supports right preconditioning.

    For methods changing the side of the preconditioner changes the norm type that is used, see `setNormType`.

    Symmetric preconditioning is currently available only for the `Type.QCG` method. Note, however, that symmetric preconditioning can be emulated by using either right or left preconditioning and a pre or post processing step.

    Setting the PC side often affects the default norm type. See `setNormType` for details.

    See also

    `PC.Side`, Working with PETSc options, `getPCSide`, `setNormType`, `getNormType`, `KSPSetPCSide`

    Source code at petsc4py/PETSc/KSP.pyx:1315

  setPostSolve(postsolve, args=None, kargs=None)

    Set the function that is called at the end of each `KSP.solve`.

    Logically collective.

    Parameters:

      - postsolve (KSPPostSolveFunction | None) – The callback function.

      - args (tuple[Any, ...] | None) – Positional arguments for the callback function.

      - kargs (dict[str, Any] | None) – Keyword arguments for the callback function.

    Return type:

      None

    See also

    `solve`, `KSPSetPreSolve`, `KSPSetPostSolve`

    Source code at petsc4py/PETSc/KSP.pyx:1670

  setPreSolve(presolve, args=None, kargs=None)

    Set the function that is called at the beginning of each `KSP.solve`.

    Logically collective.

    Parameters:

      - presolve (KSPPreSolveFunction | None) – The callback function.

      - args (tuple[Any, ...] | None) – Positional arguments for the callback function.

      - kargs (dict[str, Any] | None) – Keyword arguments for the callback function.

    Return type:

      None

    See also

    `solve`, `KSPSetPreSolve`, `KSPSetPostSolve`

    Source code at petsc4py/PETSc/KSP.pyx:1637

  setPythonContext(context=None)

    Set the instance of the class implementing Python methods.

    Not collective.

    See also

    PETSc Python linear solver type, `getPythonContext`

    Source code at petsc4py/PETSc/KSP.pyx:2183

    Parameters:

      context (Any | None)

    Return type:

      None

  setPythonType(py_type)

    Set the fully qualified Python name of the class to be used.

    Collective.

    See also

    PETSc Python linear solver type, `setPythonContext`, `getPythonType`, `KSPPythonSetType`

    Source code at petsc4py/PETSc/KSP.pyx:2210

    Parameters:

      py_type (str)

    Return type:

      None

  setResidualNorm(rnorm)

    Use `norm` property.

    Source code at petsc4py/PETSc/KSP.pyx:1860

    Parameters:

      rnorm (float)

    Return type:

      None

  setTolerances(rtol=None, atol=None, divtol=None, max_it=None)

    Set various tolerances used by the KSP convergence testers.

    Logically collective.

    Set the relative, absolute, divergence, and maximum iteration tolerances used by the default KSP convergence testers.

    Parameters:

      - rtol (float | None) – The relative convergence tolerance, relative decrease in the (possibly preconditioned) residual norm. Or `DETERMINE` to use the value when the object’s type was set.

      - atol (float | None) – The absolute convergence tolerance absolute size of the (possibly preconditioned) residual norm. Or `DETERMINE` to use the value when the object’s type was set.

      - dtol – The divergence tolerance, amount (possibly preconditioned) residual norm can increase before `KSPConvergedDefault` concludes that the method is diverging. Or `DETERMINE` to use the value when the object’s type was set.

      - max_it (int | None) – Maximum number of iterations to use. Or `DETERMINE` to use the value when the object’s type was set.

      - divtol (float | None)

    Return type:

      None

    Notes

    Use `None` to retain the default value of any of the tolerances.

    See also

    Working with PETSc options, `getTolerances`, `setConvergenceTest`, `KSPSetTolerances`, `KSPConvergedDefault`

    Source code at petsc4py/PETSc/KSP.pyx:914

  setType(ksp_type)

    Build the `KSP` data structure for a particular `Type`.

    Logically collective.

    Parameters:

      ksp_type (Type | str) – KSP Type object

    Return type:

      None

    Notes

    See `Type` for available methods (for instance, `Type.CG` or `Type.GMRES`).

    Normally, it is best to use the `setFromOptions` command and then set the KSP type from the options database rather than by using this routine. Using the options database provides the user with maximum flexibility in evaluating the many different Krylov methods. This method is provided for those situations where it is necessary to set the iterative solver independently of the command line or options database. This might be the case, for example, when the choice of iterative solver changes during the execution of the program, and the user’s application is taking responsibility for choosing the appropriate method. In other words, this routine is not for beginners.

    See also

    `KSPSetType`

    Source code at petsc4py/PETSc/KSP.pyx:473

  setUp()

    Set up internal data structures for an iterative solver.

    Collective.

    See also

    `KSPSetUp`

    Source code at petsc4py/PETSc/KSP.pyx:1595

    Return type:

      None

  setUpOnBlocks()

    Set up the preconditioner for each block in a block method.

    Collective.

    Methods include: block Jacobi, block Gauss-Seidel, and overlapping Schwarz methods.

    See also

    `KSPSetUpOnBlocks`

    Source code at petsc4py/PETSc/KSP.pyx:1622

    Return type:

      None

  setUseFischerGuess(model, size)

    Use the Paul Fischer algorithm to compute initial guesses.

    Logically collective.

    Use the Paul Fischer algorithm or its variants to compute initial guesses for a set of solves with related right hand sides.

    Parameters:

      - model (int) – Use model `1`, model `2`, model `3`, any other number to turn it off.

      - size (int) – Size of subspace used to generate initial guess.

    Return type:

      None

    See also

    `KSPSetUseFischerGuess`

    Source code at petsc4py/PETSc/KSP.pyx:1567

  solve(b, x)

    Solve the linear system.

    Collective.

    Parameters:

      - b (Vec) – Right hand side vector.

      - x (Vec) – Solution vector.

    Return type:

      None

    Notes

    If one uses `setDM` then `x` or `b` need not be passed. Use `getSolution` to access the solution in this case.

    The operator is specified with `setOperators`.

    `solve` will normally return without generating an error regardless of whether the linear system was solved or if constructing the preconditioner failed. Call `getConvergedReason` to determine if the solver converged or failed and why. The option `-ksp_error_if_not_converged` or function `setErrorIfNotConverged` will cause `solve` to error as soon as an error occurs in the linear solver. In inner solves, `DIVERGED_MAX_IT` is not treated as an error because when using nested solvers it may be fine that inner solvers in the preconditioner do not converge during the solution process.

    The number of iterations can be obtained from `its`.

    If you provide a matrix that has a `Mat.setNullSpace` and `Mat.setTransposeNullSpace` this will use that information to solve singular systems in the least squares sense with a norm minimizing solution.

    Ax = b where b = bₚ + bₜ where bₜ is not in the range of A (and hence by the fundamental theorem of linear algebra is in the nullspace(Aᵀ), see `Mat.setNullSpace`.

    KSP first removes bₜ producing the linear system Ax = bₚ (which has multiple solutions) and solves this to find the ∥x∥ minimizing solution (and hence it finds the solution x orthogonal to the nullspace(A). The algorithm is simply in each iteration of the Krylov method we remove the nullspace(A) from the search direction thus the solution which is a linear combination of the search directions has no component in the nullspace(A).

    We recommend always using `Type.GMRES` for such singular systems. If nullspace(A) = nullspace(Aᵀ) (note symmetric matrices always satisfy this property) then both left and right preconditioning will work If nullspace(A) != nullspace(Aᵀ) then left preconditioning will work but right preconditioning may not work (or it may).

    If using a direct method (e.g., via the KSP solver `Type.PREONLY` and a preconditioner such as `PC.Type.LU` or `PC.Type.ILU`, then its=1. See `setTolerances` for more details.

    Understanding Convergence

    The routines `setMonitor` and `computeEigenvalues` provide information on additional options to monitor convergence and print eigenvalue information.

    See also

    `create`, `setUp`, `destroy`, `setTolerances`, `is_converged`, `solveTranspose`, `its`, `Mat.setNullSpace`, `Mat.setTransposeNullSpace`, `Type`, `setErrorIfNotConverged`, `KSPSolve`

    Source code at petsc4py/PETSc/KSP.pyx:1703

  solveTranspose(b, x)

    Solve the transpose of a linear system.

    Collective.

    Parameters:

      - b (Vec) – Right hand side vector.

      - x (Vec) – Solution vector.

    Return type:

      None

    Notes

    For complex numbers this solve the non-Hermitian transpose system.

    See also

    `solve`, `KSPSolveTranspose`

    Source code at petsc4py/PETSc/KSP.pyx:1784

  view(viewer=None)

    Print the KSP data structure.

    Collective.

    Parameters:

      viewer (Viewer | None) – Viewer used to display the KSP.

    Return type:

      None

    See also

    `KSPView`

    Source code at petsc4py/PETSc/KSP.pyx:425

  Attributes Documentation

  appctx

    The solver application context.

    Source code at petsc4py/PETSc/KSP.pyx:2242

  atol

    The absolute tolerance of the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2335

  divtol

    The divergence tolerance of the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2343

  dm

    The solver `DM`.

    Source code at petsc4py/PETSc/KSP.pyx:2252

  guess_knoll

    Whether solver uses Knoll trick.

    Source code at petsc4py/PETSc/KSP.pyx:2294

  guess_nonzero

    Whether guess is non-zero.

    Source code at petsc4py/PETSc/KSP.pyx:2286

  history

    The convergence history of the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2377

  is_converged

    Boolean indicating if the solver has converged.

    Source code at petsc4py/PETSc/KSP.pyx:2397

  is_diverged

    Boolean indicating if the solver has failed.

    Source code at petsc4py/PETSc/KSP.pyx:2402

  is_iterating

    Boolean indicating if the solver has not converged yet.

    Source code at petsc4py/PETSc/KSP.pyx:2392

  its

    The current number of iterations the solver has taken.

    Source code at petsc4py/PETSc/KSP.pyx:2361

  mat_op

    The system matrix operator.

    Source code at petsc4py/PETSc/KSP.pyx:2274

  mat_pc

    The preconditioner operator.

    Source code at petsc4py/PETSc/KSP.pyx:2279

  max_it

    The maximum number of iteration the solver may take.

    Source code at petsc4py/PETSc/KSP.pyx:2351

  norm

    The norm of the residual at the current iteration.

    Source code at petsc4py/PETSc/KSP.pyx:2369

  norm_type

    The norm used by the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2317

  pc

    The `PC` of the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2304

  pc_side

    The side on which preconditioning is performed.

    Source code at petsc4py/PETSc/KSP.pyx:2309

  reason

    The converged reason.

    Source code at petsc4py/PETSc/KSP.pyx:2384

  rtol

    The relative tolerance of the solver.

    Source code at petsc4py/PETSc/KSP.pyx:2327

  vec_rhs

    The right-hand side vector.

    Source code at petsc4py/PETSc/KSP.pyx:2267

  vec_sol

    The solution vector.

    Source code at petsc4py/PETSc/KSP.pyx:2262