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.

Enumerations

`CGTRNormType`	`KSPCG` norm types for the trust-region constraint.
`ConvergedReason`	KSP Converged Reason.
`DMActive`	Argument to KSPSetDMActive().
`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.
`computeOperator`([mat_type])	Compute the explicit 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.
`getCGTRNormType`()	Return the norm type for the `KSPCG` trust-region constraint.
`getCGTRSolutionNorm`()	Return the solution norm used for the trust-region constraint.
`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.
`getEKSMHapTol`()	Get tolerance for detecting a happy breakdown in EKSM.
`getEKSMKSP`()	Return the internal `KSP` objects.
`getEKSMShift`()	Get the value of the shift used internally in EKSM.
`getErrorIfNotConverged`()	Return the flag indicating the solver will error if divergent.
`getHPDDMType`()	Return the Krylov solver type.
`getIDRCosine`()	Get the omega stabilization cosine threshold for IDR.
`getIDRRandom`()	Get the `Random` object used by the IDR solver.
`getIDRS`()	Get the shadow space dimension for the IDR solver.
`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.
`postSolve`(rhs, sol)	Run the post-solve callbacks.
`preSolve`(rhs, sol)	Run the pre-solve callbacks.
`reset`()	Resets a KSP context.
`setAppCtx`(appctx)	Set the optional user-defined context for the linear solver.
`setCGObjectiveTarget`(target)	Set the target value for the `KSPCG` quadratic objective.
`setCGRadius`(radius)	Set the `KSPCG` trust-region radius.
`setCGTRNormType`(normtype)	Set the norm type for the `KSPCG` trust-region constraint.
`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`(dmactive, flag)	`DM` should be used to generate system matrix & RHS vector.
`setEKSMHapTol`(tol)	Set the tolerance for detecting a happy breakdown in EKSM.
`setEKSMKSP`([ksps, kspm])	Set the `KSP` objects to be used internally by EKSM.
`setEKSMShift`(shift)	Set the value of the shift used internally in EKSM.
`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.
`setIDRCosine`(cth)	Set the omega stabilization cosine threshold for IDR.
`setIDRRandom`(rnd)	Set the `Random` object used by the IDR solver.
`setIDRS`(s)	Set the shadow space dimension for the IDR solver.
`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.

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

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:621

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:2263

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:2241

callConvergenceTest(its, rnorm)#

Call the convergence test callback.

Collective.

Parameters:

its (int) – Number of iterations.
rnorm (float) – The residual norm.

Returns:

reason – The convergence reason.

Return type:

ConvergedReason

Notes

This functionality is implemented in petsc4py.

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

computeEigenvalues()#

Compute the extreme eigenvalues for the preconditioned operator.

Not collective.

See also

KSPComputeEigenvalues

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

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:2341

computeOperator(mat_type=None)#

Compute the explicit preconditioned operator.

Collective.

Parameters:: mat_type (Type | str | None) – The output matrix type. If None, use a dense matrix.
Returns:: A newly created matrix owned by the caller.
Return type:: Mat

Notes

The operator uses the configured preconditioning side and includes null space removal when applicable. It is formed by applying the operator to columns of the identity matrix, so this computation is intended for relatively small systems.

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

create(comm=None)#

Create the KSP context.

Collective.

See also

KSPCreate

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

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

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

destroy()#

Destroy KSP context.

Collective.

See also

KSPDestroy

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

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:686

Return type:: Any

getCGObjectiveValue()#

Return the CG objective function value.

Not collective.

See also

KSPCGGetObjFcn

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

Return type:: float

getCGTRNormType()#

Return the norm type for the KSPCG trust-region constraint.

Not collective.

See also

setCGTRNormType, KSPCGGetTRNormType

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

Return type:: CGTRNormType

getCGTRSolutionNorm()#

Return the solution norm used for the trust-region constraint.

Not collective.

Notes

Computed using the norm type selected by setCGTRNormType and available after solve. KSPCG and KSPSTCG also update it before each monitor call when the radius is active. The single-reduction KSPCG variant does not provide this quantity.

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

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.

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

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.

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

Return type:: bool

getConvergedReason()#

Use reason property.

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

Return type:: ConvergedReason

getConvergenceHistory()#

Return array containing the residual history.

Not collective.

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

Return type:: ArrayReal

getConvergenceTest()#

Return the function to be used to determine convergence.

Logically collective.

Returns:: context – The callback, positional arguments, and keyword arguments, or None if the default convergence test is used.
Return type:: tuple or None

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

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:700

Return type:: DM

getEKSMHapTol()#

Get tolerance for detecting a happy breakdown in EKSM.

Not collective.

Returns:: tol – Tolerance for happy breakdown.
Return type:: float

See also

setEKSMHapTol, KSPEKSMGetHapTol

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

getEKSMKSP()#

Return the internal KSP objects.

Not collective.

Returns:

ksps (KSP) – Linear solver for K + s M.
kspm (KSP) – Linear solver for M.

Return type:

tuple[KSP, KSP]

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

getEKSMShift()#

Get the value of the shift used internally in EKSM.

Not collective.

Returns:: shift – The value of the shift.
Return type:: Scalar

See also

setEKSMShift, KSPEKSMGetShift

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

getErrorIfNotConverged()#

Return the flag indicating the solver will error if divergent.

Not collective.

See also

KSPGetErrorIfNotConverged

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

Return type:: bool

getHPDDMType()#

Return the Krylov solver type.

Not collective.

See also

KSPHPDDMGetType

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

Return type:: HPDDMType

getIDRCosine()#

Get the omega stabilization cosine threshold for IDR.

Not collective.

Returns:: cth – Stabilization cosine threshold.
Return type:: float

See also

setIDRCosine, KSPIDRGetCosine

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

getIDRRandom()#

Get the Random object used by the IDR solver.

Collective.

Returns:: The random number generator context.
Return type:: Random

See also

setIDRRandom, KSPIDRGetRandom

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

getIDRS()#

Get the shadow space dimension for the IDR solver.

Not collective.

Returns:: s – Shadow space dimension.
Return type:: int

See also

setIDRS, KSPIDRGetS

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

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:1609

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:1575

Return type:: bool

getIterationNumber()#

Use its property.

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

Return type:: int

getMonitor()#

Return function used to monitor the residual.

Not collective.

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

Return type:: KSPMonitorFunction

getNormType()#

Return the norm that is used for convergence testing.

Not collective.

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

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]

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

getOptionsPrefix()#

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

Not collective.

See also

KSPGetOptionsPrefix

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

Return type:: str

getPC()#

Return the preconditioner.

Not collective.

See also

PETSc.KSP, setPC, KSPGetPC

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

Return type:: PC

getPCSide()#

Return the preconditioning side.

Not collective.

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

Return type:: Side

getPythonContext()#

Return the instance of the class implementing Python methods.

Not collective.

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

Return type:: Any

getPythonType()#

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

Not collective.

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

Return type:: str

getResidualNorm()#

Use norm property.

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

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:2160

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:2175

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:1021

getType()#

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

Not collective.

See also

KSPGetType

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

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:2193

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:1264

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:1910

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:1932

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:1353

Parameters:

its (int)
rnorm (float)

Return type:

None

monitorCancel()#

Clear all monitors for a KSP object.

Logically collective.

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

Return type:: None

postSolve(rhs, sol)#

Run the post-solve callbacks.

Collective.

Parameters:

rhs (Vec) – Right hand side vector.
sol (Vec) – Solution vector.

Return type:

None

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

preSolve(rhs, sol)#

Run the pre-solve callbacks.

Collective.

Parameters:

rhs (Vec) – Right hand side vector.
sol (Vec) – Solution vector.

Return type:

None

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

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:1666

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:663

setCGObjectiveTarget(target)#

Set the target value for the KSPCG quadratic objective.

Logically collective.

Parameters:: target (float) – Stop when the quadratic objective reaches this value or less. A nonnegative value, including the default zero, disables the test.
Return type:: None

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

setCGRadius(radius)#

Set the KSPCG trust-region radius.

Logically collective.

Parameters:: radius (float) – Nonnegative radius. Zero, the default, disables the constraint.
Return type:: None

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

setCGTRNormType(normtype)#

Set the norm type for the KSPCG trust-region constraint.

Logically collective.

Parameters:: normtype (CGTRNormType | str) – The trust-region norm type, as a CGTRNormType value or the string 'preconditioned' or 'unpreconditioned'.
Return type:: None

Notes

The norm type selects the norm used for the trust-region constraint in KSPCG, KSPSTCG, KSPNASH, and KSPGLTR. It does not change the residual norm selected by setNormType.

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

setComputeEigenvalues(flag=True)#

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.

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

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

Set routine to compute the linear operators.

Logically collective.

Parameters:

operators (KSPComputeOperatorsFunction) – 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 and delimiters 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.

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

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.

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

setComputeSingularValues(flag=True)#

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.

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

setConvergedReason(reason)#

Use reason property.

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

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.

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

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.

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

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(KSP.DMActive.OPERATOR, 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.

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

setDMActive(dmactive, flag)#

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

Logically collective.

Parameters:

flag (bool) – Whether to use the DM.
dmactive (DMActive)

Return type:

None

Notes

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

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

setEKSMHapTol(tol)#

Set the tolerance for detecting a happy breakdown in EKSM.

Logically collective.

Parameters:: tol (float) – Tolerance for determining happy breakdown.
Return type:: None

See also

getEKSMHapTol, KSPEKSMSetHapTol

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

setEKSMKSP(ksps=None, kspm=None)#

Set the KSP objects to be used internally by EKSM.

Not collective.

Parameters:

ksps (KSP | None) – Linear solver for K + s M.
kspm (KSP | None) – Linear solver for M.

Return type:

None

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

setEKSMShift(shift)#

Set the value of the shift used internally in EKSM.

Logically collective.

Parameters:: shift (Scalar) – The value of the shift.
Return type:: None

See also

getEKSMShift, KSPEKSMSetShift

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

setErrorIfNotConverged(flag=True)#

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:2128

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.

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

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:2365

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:2096

setIDRCosine(cth)#

Set the omega stabilization cosine threshold for IDR.

Logically collective.

Parameters:: cth (float) – Stabilization cosine threshold.
Return type:: None

See also

getIDRCosine, KSPIDRSetCosine

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

setIDRRandom(rnd)#

Set the Random object used by the IDR solver.

Collective.

Parameters:: rnd (Random) – The random number generator context.
Return type:: None

See also

getIDRRandom, KSPIDRSetRandom

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

setIDRS(s)#

Set the shadow space dimension for the IDR solver.

Logically collective.

Parameters:: s (int) – Shadow space dimension.
Return type:: None

See also

getIDRS, KSPIDRSetS

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

setInitialGuessKnoll(flag=True)#

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:1589

setInitialGuessNonzero(flag=True)#

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:1553

setIterationNumber(its)#

Use its property.

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

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.

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

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.

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

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

This is equivalent to pc = ksp.getPC(); pc.setOperators(A, P) but is the preferred approach.

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.

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

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 `

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

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:927

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.

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

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

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

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

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

setPythonContext(context=None)#

Set the instance of the class implementing Python methods.

Not collective.

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

Parameters:: context (Any | None)
Return type:: None

setPythonType(py_type)#

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

Collective.

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

Parameters:: py_type (str)
Return type:: None

setResidualNorm(rnorm)#

Use norm property.

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

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.

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

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:519

setUp()#

Set up internal data structures for an iterative solver.

Collective.

See also

KSPSetUp

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

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:1681

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:1626

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 may be passed as None. Both positional arguments are required. 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.