:orphan:
# KSPSolve
Solves linear system. 
## Synopsis
```
#include "petscksp.h" 
#include "petscmat.h" 
PetscErrorCode KSPSolve(KSP ksp, Vec b, Vec x)
```
Collective


## Parameters

- ***ksp -*** iterative context obtained from `KSPCreate()`
- ***b -*** the right hand side vector
- ***x -*** the solution (this may be the same vector as b, then b will be overwritten with answer)



## Options Database Keys

- ***-ksp_view_eigenvalues -*** compute preconditioned operators eigenvalues
- ***-ksp_view_eigenvalues_explicit -*** compute the eigenvalues by forming the dense operator and using LAPACK
- ***-ksp_view_mat binary -*** save matrix to the default binary viewer
- ***-ksp_view_pmat binary -*** save matrix used to build preconditioner to the default binary viewer
- ***-ksp_view_rhs binary -*** save right hand side vector to the default binary viewer
- ***-ksp_view_solution binary -*** save computed solution vector to the default binary viewer
(can be read later with src/ksp/tutorials/ex10.c for testing solvers)
- ***-ksp_view_mat_explicit -*** for matrix-free operators, computes the matrix entries and views them
- ***-ksp_view_preconditioned_operator_explicit -*** computes the product of the preconditioner and matrix as an explicit matrix and views it
- ***-ksp_converged_reason -*** print reason for converged or diverged, also prints number of iterations
- ***-ksp_view_final_residual -*** print 2-norm of true linear system residual at the end of the solution process
- ***-ksp_error_if_not_converged -*** stop the program as soon as an error is detected in a `KSPSolve()`
- ***-ksp_view -*** print the ksp data structure at the end of the system solution



## Notes

If one uses `KSPSetDM()` then x or b need not be passed. Use `KSPGetSolution()` to access the solution in this case.

The operator is specified with `KSPSetOperators()`.

`KSPSolve()` will normally return without generating an error regardless of whether the linear system was solved or if constructing the preconditioner failed.
Call `KSPGetConvergedReason()` to determine if the solver converged or failed and why. The option -ksp_error_if_not_converged or function `KSPSetErrorIfNotConverged()`
will cause `KSPSolve()` to error as soon as an error occurs in the linear solver.  In inner KSPSolves() KSP_DIVERGED_ITS 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 `KSPGetIterationNumber()`.

If you provide a matrix that has a `MatSetNullSpace()` and `MatSetTransposeNullSpace()` this will use that information to solve singular systems
in the least squares sense with a norm minimizing solution.

A x = b   where b = b_p + b_t where b_t is not in the range of A (and hence by the fundamental theorem of linear algebra is in the nullspace(A') see `MatSetNullSpace()`

`KSP` first removes b_t producing the linear system  A x = b_p (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 `KSPGMRES` 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).

Developer Note: The reason we cannot always solve  nullspace(A) != nullspace(A') systems with right preconditioning is because we need to remove at each iteration
the nullspace(AB) from the search direction. While we know the nullspace(A) the nullspace(AB) equals B^-1 times the nullspace(A) but except for trivial preconditioners
such as diagonal scaling we cannot apply the inverse of the preconditioner to a vector and thus cannot compute the nullspace(AB).

If using a direct method (e.g., via the `KSP` solver
`KSPPREONLY` and a preconditioner such as `PCLU` or `PCILU`,
then its=1.  See `KSPSetTolerances()` and `KSPConvergedDefault()`
for more details.


## Understanding Convergence
The routines `KSPMonitorSet()`, `KSPComputeEigenvalues()`, and
`KSPComputeEigenvaluesExplicitly()` provide information on additional
options to monitor convergence and print eigenvalue information.




## See Also
 [](ch_ksp), `KSPCreate()`, `KSPSetUp()`, `KSPDestroy()`, `KSPSetTolerances()`, `KSPConvergedDefault()`,
`KSPSolveTranspose()`, `KSPGetIterationNumber()`, `MatNullSpaceCreate()`, `MatSetNullSpace()`, `MatSetTransposeNullSpace()`, `KSP`,
`KSPConvergedReasonView()`, `KSPCheckSolve()`, `KSPSetErrorIfNotConverged()`

## Level
beginner

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/interface/itfunc.c.html#KSPSolve">src/ksp/ksp/interface/itfunc.c</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/stag/tutorials/ex1.c.html">src/dm/impls/stag/tutorials/ex1.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/stag/tutorials/ex2.c.html">src/dm/impls/stag/tutorials/ex2.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/stag/tutorials/ex3.c.html">src/dm/impls/stag/tutorials/ex3.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/stag/tutorials/ex4.c.html">src/dm/impls/stag/tutorials/ex4.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/dm/impls/stag/tutorials/ex8.c.html">src/dm/impls/stag/tutorials/ex8.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/bench_kspsolve.c.html">src/ksp/ksp/tutorials/bench_kspsolve.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex1.c.html">src/ksp/ksp/tutorials/ex1.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex10.c.html">src/ksp/ksp/tutorials/ex10.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex100.c.html">src/ksp/ksp/tutorials/ex100.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex100f.F90.html">src/ksp/ksp/tutorials/ex100f.F90</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex11.c.html">src/ksp/ksp/tutorials/ex11.c</A><BR>

## Implementations

<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgs/bcgs.c.html#KSPSolve_BCGS">KSPSolve_BCGS in src/ksp/ksp/impls/bcgs/bcgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgs/fbcgs/fbcgs.c.html#KSPSolve_FBCGS">KSPSolve_FBCGS in src/ksp/ksp/impls/bcgs/fbcgs/fbcgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgs/fbcgsr/fbcgsr.c.html#KSPSolve_FBCGSR">KSPSolve_FBCGSR in src/ksp/ksp/impls/bcgs/fbcgsr/fbcgsr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgs/pipebcgs/pipebcgs.c.html#KSPSolve_PIPEBCGS">KSPSolve_PIPEBCGS in src/ksp/ksp/impls/bcgs/pipebcgs/pipebcgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgs/qmrcgs/qmrcgs.c.html#KSPSolve_QMRCGS">KSPSolve_QMRCGS in src/ksp/ksp/impls/bcgs/qmrcgs/qmrcgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bcgsl/bcgsl.c.html#KSPSolve_BCGSL">KSPSolve_BCGSL in src/ksp/ksp/impls/bcgsl/bcgsl.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/bicg/bicg.c.html#KSPSolve_BiCG">KSPSolve_BiCG in src/ksp/ksp/impls/bicg/bicg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/cg.c.html#KSPSolve_CG">KSPSolve_CG in src/ksp/ksp/impls/cg/cg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/cgls.c.html#KSPSolve_CGLS">KSPSolve_CGLS in src/ksp/ksp/impls/cg/cgls.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/cgne/cgne.c.html#KSPSolve_CGNE">KSPSolve_CGNE in src/ksp/ksp/impls/cg/cgne/cgne.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/groppcg/groppcg.c.html#KSPSolve_GROPPCG">KSPSolve_GROPPCG in src/ksp/ksp/impls/cg/groppcg/groppcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/pipecg/pipecg.c.html#KSPSolve_PIPECG">KSPSolve_PIPECG in src/ksp/ksp/impls/cg/pipecg/pipecg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/pipecg2/pipecg2.c.html#KSPSolve_PIPECG2">KSPSolve_PIPECG2 in src/ksp/ksp/impls/cg/pipecg2/pipecg2.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/pipecgrr/pipecgrr.c.html#KSPSolve_PIPECGRR">KSPSolve_PIPECGRR in src/ksp/ksp/impls/cg/pipecgrr/pipecgrr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/pipelcg/pipelcg.c.html#KSPSolve_PIPELCG">KSPSolve_PIPELCG in src/ksp/ksp/impls/cg/pipelcg/pipelcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cg/pipeprcg/pipeprcg.c.html#KSPSolve_PIPEPRCG">KSPSolve_PIPEPRCG in src/ksp/ksp/impls/cg/pipeprcg/pipeprcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cgs/cgs.c.html#KSPSolve_CGS">KSPSolve_CGS in src/ksp/ksp/impls/cgs/cgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cr/cr.c.html#KSPSolve_CR">KSPSolve_CR in src/ksp/ksp/impls/cr/cr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/cr/pipecr/pipecr.c.html#KSPSolve_PIPECR">KSPSolve_PIPECR in src/ksp/ksp/impls/cr/pipecr/pipecr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/fcg/fcg.c.html#KSPSolve_FCG">KSPSolve_FCG in src/ksp/ksp/impls/fcg/fcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/fcg/pipefcg/pipefcg.c.html#KSPSolve_PIPEFCG">KSPSolve_PIPEFCG in src/ksp/ksp/impls/fcg/pipefcg/pipefcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/fetidp/fetidp.c.html#KSPSolve_FETIDP">KSPSolve_FETIDP in src/ksp/ksp/impls/fetidp/fetidp.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gcr/gcr.c.html#KSPSolve_GCR">KSPSolve_GCR in src/ksp/ksp/impls/gcr/gcr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gcr/pipegcr/pipegcr.c.html#KSPSolve_PIPEGCR">KSPSolve_PIPEGCR in src/ksp/ksp/impls/gcr/pipegcr/pipegcr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/agmres/agmres.c.html#KSPSolve_AGMRES">KSPSolve_AGMRES in src/ksp/ksp/impls/gmres/agmres/agmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/dgmres/dgmres.c.html#KSPSolve_DGMRES">KSPSolve_DGMRES in src/ksp/ksp/impls/gmres/dgmres/dgmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/fgmres/fgmres.c.html#KSPSolve_FGMRES">KSPSolve_FGMRES in src/ksp/ksp/impls/gmres/fgmres/fgmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/gmres.c.html#KSPSolve_GMRES">KSPSolve_GMRES in src/ksp/ksp/impls/gmres/gmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/lgmres/lgmres.c.html#KSPSolve_LGMRES">KSPSolve_LGMRES in src/ksp/ksp/impls/gmres/lgmres/lgmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/pgmres/pgmres.c.html#KSPSolve_PGMRES">KSPSolve_PGMRES in src/ksp/ksp/impls/gmres/pgmres/pgmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/gmres/pipefgmres/pipefgmres.c.html#KSPSolve_PIPEFGMRES">KSPSolve_PIPEFGMRES in src/ksp/ksp/impls/gmres/pipefgmres/pipefgmres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/hpddm/hpddm.cxx.html#KSPSolve_HPDDM">KSPSolve_HPDDM in src/ksp/ksp/impls/hpddm/hpddm.cxx</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/ibcgs/ibcgs.c.html#KSPSolve_IBCGS">KSPSolve_IBCGS in src/ksp/ksp/impls/ibcgs/ibcgs.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/lcd/lcd.c.html#KSPSolve_LCD">KSPSolve_LCD in src/ksp/ksp/impls/lcd/lcd.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/lsqr/lsqr.c.html#KSPSolve_LSQR">KSPSolve_LSQR in src/ksp/ksp/impls/lsqr/lsqr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/minres/minres.c.html#KSPSolve_MINRES">KSPSolve_MINRES in src/ksp/ksp/impls/minres/minres.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/preonly/preonly.c.html#KSPSolve_PREONLY">KSPSolve_PREONLY in src/ksp/ksp/impls/preonly/preonly.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/qcg/qcg.c.html#KSPSolve_QCG">KSPSolve_QCG in src/ksp/ksp/impls/qcg/qcg.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/rich/rich.c.html#KSPSolve_Richardson">KSPSolve_Richardson in src/ksp/ksp/impls/rich/rich.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/symmlq/symmlq.c.html#KSPSolve_SYMMLQ">KSPSolve_SYMMLQ in src/ksp/ksp/impls/symmlq/symmlq.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/tcqmr/tcqmr.c.html#KSPSolve_TCQMR">KSPSolve_TCQMR in src/ksp/ksp/impls/tcqmr/tcqmr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/tfqmr/tfqmr.c.html#KSPSolve_TFQMR">KSPSolve_TFQMR in src/ksp/ksp/impls/tfqmr/tfqmr.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/impls/tsirm/tsirm.c.html#KSPSolve_TSIRM">KSPSolve_TSIRM in src/ksp/ksp/impls/tsirm/tsirm.c</A><BR>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/ksp/ksp/interface/itfunc.c)


[Index of all KSP routines](index.md)  
[Table of Contents for all manual pages](/manualpages/index.md)  
[Index of all manual pages](/manualpages/singleindex.md)