petsc-3.4.2 2013-07-02

# KSPSetOperators

Sets the matrix associated with the linear system and a (possibly) different one associated with the preconditioner.

### Synopsis

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

Collective on KSP and Mat

### 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.
| flag | - flag indicating information about the preconditioner matrix structure during successive linear solves. This flag is ignored the first time a linear system is solved, and thus is irrelevant when solving just one linear system.

### Notes

The flag can be used to eliminate unnecessary work in the preconditioner during the repeated solution of linear systems of the same size. The available options are

       SAME_PRECONDITIONER -

         Pmat is identical during successive linear solves.

         This option is intended for folks who are using

         different Amat and Pmat matrices and want to reuse the

         same preconditioner matrix.  For example, this option

         saves work by not recomputing incomplete factorization

         for ILU/ICC preconditioners.

       SAME_NONZERO_PATTERN -

         Pmat has the same nonzero structure during

         successive linear solves.

       DIFFERENT_NONZERO_PATTERN -

         Pmat does not have the same nonzero structure.

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().

### Caution

If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion and does not check the structure of the matrix. If you erroneously claim that the structure is the same when it actually is not, the new preconditioner will not function correctly. Thus, use this optimization feature carefully!

If in doubt about whether your preconditioner matrix has changed structure or not, use the flag DIFFERENT_NONZERO_PATTERN.

Alternative usage: If the operators have NOT been set with KSP/PCSetOperators() then the operators are created in 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 KSP/PCSetOperators() 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,

            KSP/PCGetOperators(ksp/pc,&mat,NULL,NULL); is equivalent to

              set size, type, etc of mat

            MatCreate(comm,&mat);

            KSP/PCSetOperators(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);

            PetscObjectDereference((PetscObject)mat);

              set size, type, etc of mat

and

            KSP/PCGetOperators(ksp/pc,&mat,&pmat,NULL); is equivalent to

              set size, type, etc of mat and pmat

            MatCreate(comm,&mat);

            MatCreate(comm,&pmat);

            KSP/PCSetOperators(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);

            PetscObjectDereference((PetscObject)mat);

            PetscObjectDereference((PetscObject)pmat);

              set size, type, etc of mat and pmat

The rational 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 livespans 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?

### Keywords

KSP, set, operators, matrix, preconditioner, linear system

### See Also

KSPSolve(), KSPGetPC(), PCGetOperators(), PCSetOperators(), KSPGetOperators()

Level:beginner
Location:src/ksp/ksp/interface/itcreate.c
Index of all KSP routines
Table of Contents for all manual pages
Index of all manual pages

### Examples

src/ksp/pc/examples/tutorials/ex1.c.html
src/ksp/pc/examples/tutorials/ex2.c.html
src/ksp/ksp/examples/tutorials/ex1.c.html
src/ksp/ksp/examples/tutorials/ex2.c.html
src/ksp/ksp/examples/tutorials/ex3.c.html
src/ksp/ksp/examples/tutorials/ex4.c.html
src/ksp/ksp/examples/tutorials/ex5.c.html
src/ksp/ksp/examples/tutorials/ex7.c.html
src/ksp/ksp/examples/tutorials/ex8.c.html
src/ksp/ksp/examples/tutorials/ex8g.c.html
src/ksp/ksp/examples/tutorials/ex9.c.html