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
contextAmat - 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#
Examples#
src/ksp/pc/tutorials/ex1.c
src/dm/impls/stag/tutorials/ex4.c
src/ksp/pc/tutorials/ex3.c
src/dm/impls/swarm/tutorials/ex1f90.F90
src/dm/impls/stag/tutorials/ex1.c
src/dm/impls/stag/tutorials/ex2.c
src/dm/impls/stag/tutorials/ex3.c
src/dm/impls/stag/tutorials/ex8.c
src/ksp/pc/tutorials/ex2.c
src/ksp/pc/tutorials/ex4.c
Index of all KSP routines
Table of Contents for all manual pages
Index of all manual pages