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 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 Mats). 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?