KSPSetOperators — PETSc 3.21.4 documentation

Skip to main content
`Ctrl`+`K`

# KSPSetOperators

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

## Synopsis

    #include "petscksp.h"
    PetscErrorCode KSPSetOperators(KSP ksp, Mat Amat, Mat Pmat)

Collective

## Input Parameters

- ksp - the `KSP` context

- Amat - the matrix that defines the linear system

- Pmat - the matrix to be used in constructing the preconditioner, usually the same as Amat.

## Notes

If you know the operator Amat has a null space you can use `MatSetNullSpace()` and `MatSetTransposeNullSpace()` to supply the null space to `Amat` and the `KSP` solvers will automatically use that null space as needed during the solution process.

All future calls to `KSPSetOperators()` must use the same size matrices!

Passing a `NULL` for `Amat` or `Pmat` removes the matrix that is currently used.

If you wish to replace either `Amat` or `Pmat` but leave the other one untouched then first call `KSPGetOperators()` to get the one you wish to keep, call `PetscObjectReference()` on it and then pass it back in your call to `KSPSetOperators()`.

## Developer Notes

If the operators have NOT been set with `KSPSetOperators()` then the operators are created in the `PC` and returned to the user. In this case, if both operators mat and pmat are requested, two DIFFERENT operators will be returned. If only one is requested both operators in the `PC` will be the same (i.e. as if one had called `KSPSetOperators()` with the same argument for both `Mat`s). The user must set the sizes of the returned matrices and their type etc just as if the user created them with `MatCreate()`. For example,

             KSPGetOperators(ksp/pc,&mat,NULL); is equivalent to
               set size, type, etc of mat

             MatCreate(comm,&mat);
             KSP/PCSetOperators(ksp/pc,mat,mat);
             PetscObjectDereference((PetscObject)mat);
               set size, type, etc of mat

         and

             KSP/PCGetOperators(ksp/pc,&mat,&pmat); is equivalent to
               set size, type, etc of mat and pmat

             MatCreate(comm,&mat);
             MatCreate(comm,&pmat);
             KSP/PCSetOperators(ksp/pc,mat,pmat);
             PetscObjectDereference((PetscObject)mat);
             PetscObjectDereference((PetscObject)pmat);
               set size, type, etc of mat and pmat

The rationale for this support is so that when creating a `TS`, `SNES`, or `KSP` the hierarchy of underlying objects (i.e. `SNES`, `KSP`, `PC`, `Mat`) and their lifespans can be completely managed by the top most level object (i.e. the `TS`, `SNES`, or `KSP`). Another way to look at this is when you create a `SNES` you do not NEED to create a `KSP` and attach it to the `SNES` object (the `SNES` object manages it for you). Similarly when you create a `KSP` you do not need to attach a `PC` to it (the `KSP` object manages the `PC` object for you). Thus, why should YOU have to create the `Mat` and attach it to the `SNES`/`KSP`/`PC`, when it can be created for you?

## See Also

KSP: Linear System Solvers, `KSP`, `Mat`, `KSPSolve()`, `KSPGetPC()`, `PCGetOperators()`, `PCSetOperators()`, `KSPGetOperators()`, `KSPSetComputeOperators()`, `KSPSetComputeInitialGuess()`, `KSPSetComputeRHS()`

## Level

beginner

## Location

src/ksp/ksp/interface/itcreate.c

## Examples

src/dm/impls/stag/tutorials/ex8.c
src/dm/impls/swarm/tutorials/ex1f90.F90
src/ksp/ksp/tutorials/ex11.c
src/ksp/ksp/tutorials/ex12.c
src/dm/impls/stag/tutorials/ex1.c
src/dm/impls/stag/tutorials/ex2.c
src/dm/impls/stag/tutorials/ex4.c
src/ksp/ksp/tutorials/ex16.c
src/dm/impls/stag/tutorials/ex3.c
src/ksp/ksp/tutorials/ex21.c

Index of all KSP routines
Table of Contents for all manual pages
Index of all manual pages