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

`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.
`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.
`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.
`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 (Callable[[KSP, int, float], ConvergedReason]) – 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:1096

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

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

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

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

computeEigenvalues()#

Compute the extreme eigenvalues for the preconditioned operator.

Not collective.

See also

KSPComputeEigenvalues

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

Return type:: ndarray[tuple[Any, …], dtype[complexfloating]]

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

create(comm=None)#

Create the KSP context.

Collective.

See also

KSPCreate

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

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

destroy()#

Destroy KSP context.

Collective.

See also

KSPDestroy

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

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

Return type:: Any

getCGObjectiveValue()#

Return the CG objective function value.

Not collective.

See also

KSPCGGetObjFcn

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

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

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

Return type:: bool

getConvergedReason()#

Use reason property.

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

Return type:: ConvergedReason

getConvergenceHistory()#

Return array containing the residual history.

Not collective.

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

Return type:: ndarray[tuple[Any, …], dtype[floating]]

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

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

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

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

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

getErrorIfNotConverged()#

Return the flag indicating the solver will error if divergent.

Not collective.

See also

KSPGetErrorIfNotConverged

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

Return type:: bool

getHPDDMType()#

Return the Krylov solver type.

Not collective.

See also

KSPHPDDMGetType

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

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

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

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

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

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

Return type:: bool

getIterationNumber()#

Use its property.

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

Return type:: int

getMonitor()#

Return function used to monitor the residual.

Not collective.

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

Return type:: Callable[[KSP, int, float], None]

getNormType()#

Return the norm that is used for convergence testing.

Not collective.

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

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

getOptionsPrefix()#

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

Not collective.

See also

KSPGetOptionsPrefix

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

Return type:: str

getPC()#

Return the preconditioner.

Not collective.

See also

PETSc.KSP, setPC, KSPGetPC

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

Return type:: PC

getPCSide()#

Return the preconditioning side.

Not collective.

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

Return type:: Side

getPythonContext()#

Return the instance of the class implementing Python methods.

Not collective.

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

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

Return type:: str

getResidualNorm()#

Use norm property.

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

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

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

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

getType()#

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

Not collective.

See also

KSPGetType

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

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

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

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

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

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

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

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

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

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

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

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

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

Set routine to compute the linear operators.

Logically collective.

Parameters:

operators (Callable[[KSP, Mat, Mat], None]) – 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:792

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

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

Logically collective.

Parameters:

rhs (Callable[[KSP, Vec], None]) – 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:758

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

setConvergedReason(reason)#

Use reason property.

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

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

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

Set the function to be used to determine convergence.

Logically collective.

Parameters:

converged (Callable[[KSP, int, float], ConvergedReason]) – 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:1031

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

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

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

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

setEKSMShift(shift)#

Set the value of the shift used internally in EKSM.

Logically collective.

Parameters:: shift (float | complex) – The value of the shift.
Return type:: None

See also

getEKSMShift, KSPEKSMSetShift

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

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

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

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

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

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

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

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

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

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

setIterationNumber(its)#

Use its property.

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

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 (Callable[[KSP, int, float], None]) – 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:1261

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

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

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

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

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

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

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

Logically collective.

Parameters:

postsolve (Callable[[KSP, Vec, Vec], None] | 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:1710

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

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

Logically collective.

Parameters:

presolve (Callable[[KSP, Vec, Vec], None] | 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:1677

setPythonContext(context=None)#

Set the instance of the class implementing Python methods.

Not collective.

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

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

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

setResidualNorm(rnorm)#

Use norm property.

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

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

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

setUp()#

Set up internal data structures for an iterative solver.

Collective.

See also

KSPSetUp

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

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

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

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.