Date: 2015-10-02T22:20:21+00:00

Actual source code: petscksp.h
petsc-3.6.2 2015-10-02
Report Typos and Errors

      1: /*
      2:    Defines the interface functions for the Krylov subspace accelerators.
      3: */
      4: #ifndef __PETSCKSP_H
      6: #include <petscpc.h>

      8: PETSC_EXTERN PetscErrorCode KSPInitializePackage(void);

     10: /*S
     11:      KSP - Abstract PETSc object that manages all Krylov methods. This is the object that manages the
     12:          linear solves in PETSc (even those such as direct solvers that do no use Krylov accelerators).

     14:    Level: beginner

     16:   Concepts: Krylov methods

     18:         Notes: When a direct solver is used but no Krylov solver is used the KSP object is still used by with a
     19:        KSPType of KSPPREONLY (meaning application of the preconditioner is only used as the linear solver).

     21: .seealso:  KSPCreate(), KSPSetType(), KSPType, SNES, TS, PC, KSP, KSPDestroy()
     22: S*/
     23: typedef struct _p_KSP*     KSP;

     25: /*J
     26:     KSPType - String with the name of a PETSc Krylov method.

     28:    Level: beginner

     30: .seealso: KSPSetType(), KSP, KSPRegister(), KSPCreate(), KSPSetFromOptions()
     31: J*/
     32: typedef const char* KSPType;
     33: #define KSPRICHARDSON "richardson"
     34: #define KSPCHEBYSHEV  "chebyshev"
     35: #define KSPCG         "cg"
     36: #define KSPGROPPCG    "groppcg"
     37: #define KSPPIPECG     "pipecg"
     38: #define   KSPCGNE       "cgne"
     39: #define   KSPNASH       "nash"
     40: #define   KSPSTCG       "stcg"
     41: #define   KSPGLTR       "gltr"
     42: #define KSPFCG        "fcg"
     43: #define KSPGMRES      "gmres"
     44: #define   KSPFGMRES     "fgmres"
     45: #define   KSPLGMRES     "lgmres"
     46: #define   KSPDGMRES     "dgmres"
     47: #define   KSPPGMRES     "pgmres"
     48: #define KSPTCQMR      "tcqmr"
     49: #define KSPBCGS       "bcgs"
     50: #define   KSPIBCGS      "ibcgs"
     51: #define   KSPFBCGS      "fbcgs"
     52: #define   KSPFBCGSR     "fbcgsr"
     53: #define   KSPBCGSL      "bcgsl"
     54: #define KSPCGS        "cgs"
     55: #define KSPTFQMR      "tfqmr"
     56: #define KSPCR         "cr"
     57: #define KSPPIPECR     "pipecr"
     58: #define KSPLSQR       "lsqr"
     59: #define KSPPREONLY    "preonly"
     60: #define KSPQCG        "qcg"
     61: #define KSPBICG       "bicg"
     62: #define KSPMINRES     "minres"
     63: #define KSPSYMMLQ     "symmlq"
     64: #define KSPLCD        "lcd"
     65: #define KSPPYTHON     "python"
     66: #define KSPGCR        "gcr"

     68: /* Logging support */
     69: PETSC_EXTERN PetscClassId KSP_CLASSID;
     70: PETSC_EXTERN PetscClassId DMKSP_CLASSID;

     72: PETSC_EXTERN PetscErrorCode KSPCreate(MPI_Comm,KSP *);
     73: PETSC_EXTERN PetscErrorCode KSPSetType(KSP,KSPType);
     74: PETSC_EXTERN PetscErrorCode KSPGetType(KSP,KSPType *);
     75: PETSC_EXTERN PetscErrorCode KSPSetUp(KSP);
     76: PETSC_EXTERN PetscErrorCode KSPSetUpOnBlocks(KSP);
     77: PETSC_EXTERN PetscErrorCode KSPSolve(KSP,Vec,Vec);
     78: PETSC_EXTERN PetscErrorCode KSPSolveTranspose(KSP,Vec,Vec);
     79: PETSC_EXTERN PetscErrorCode KSPReset(KSP);
     80: PETSC_EXTERN PetscErrorCode KSPDestroy(KSP*);
     81: PETSC_EXTERN PetscErrorCode KSPSetReusePreconditioner(KSP,PetscBool);
     82: PETSC_EXTERN PetscErrorCode KSPSetSkipPCSetFromOptions(KSP,PetscBool);

     84: PETSC_EXTERN PetscFunctionList KSPList;
     85: PETSC_EXTERN PetscErrorCode KSPRegister(const char[],PetscErrorCode (*)(KSP));

     87: PETSC_EXTERN PetscErrorCode KSPSetPCSide(KSP,PCSide);
     88: PETSC_EXTERN PetscErrorCode KSPGetPCSide(KSP,PCSide*);
     89: PETSC_EXTERN PetscErrorCode KSPSetTolerances(KSP,PetscReal,PetscReal,PetscReal,PetscInt);
     90: PETSC_EXTERN PetscErrorCode KSPGetTolerances(KSP,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
     91: PETSC_EXTERN PetscErrorCode KSPSetInitialGuessNonzero(KSP,PetscBool );
     92: PETSC_EXTERN PetscErrorCode KSPGetInitialGuessNonzero(KSP,PetscBool  *);
     93: PETSC_EXTERN PetscErrorCode KSPSetInitialGuessKnoll(KSP,PetscBool );
     94: PETSC_EXTERN PetscErrorCode KSPGetInitialGuessKnoll(KSP,PetscBool *);
     95: PETSC_EXTERN PetscErrorCode KSPSetErrorIfNotConverged(KSP,PetscBool );
     96: PETSC_EXTERN PetscErrorCode KSPGetErrorIfNotConverged(KSP,PetscBool  *);
     97: PETSC_EXTERN PetscErrorCode KSPSetComputeEigenvalues(KSP,PetscBool );
     98: PETSC_EXTERN PetscErrorCode KSPGetComputeEigenvalues(KSP,PetscBool *);
     99: PETSC_EXTERN PetscErrorCode KSPSetComputeSingularValues(KSP,PetscBool );
    100: PETSC_EXTERN PetscErrorCode KSPGetComputeSingularValues(KSP,PetscBool *);
    101: PETSC_EXTERN PetscErrorCode KSPGetRhs(KSP,Vec *);
    102: PETSC_EXTERN PetscErrorCode KSPGetSolution(KSP,Vec *);
    103: PETSC_EXTERN PetscErrorCode KSPGetResidualNorm(KSP,PetscReal*);
    104: PETSC_EXTERN PetscErrorCode KSPGetIterationNumber(KSP,PetscInt*);
    105: PETSC_EXTERN PetscErrorCode KSPGetTotalIterations(KSP,PetscInt*);
    106: PETSC_EXTERN PetscErrorCode KSPCreateVecs(KSP,PetscInt,Vec**,PetscInt,Vec**);
    107: PETSC_DEPRECATED("Use KSPCreateVecs()") PETSC_STATIC_INLINE PetscErrorCode KSPGetVecs(KSP ksp,PetscInt n,Vec **x,PetscInt m,Vec **y) {return KSPCreateVecs(ksp,n,x,m,y);}

    109: PETSC_EXTERN PetscErrorCode KSPSetPreSolve(KSP,PetscErrorCode (*)(KSP,Vec,Vec,void*),void*);
    110: PETSC_EXTERN PetscErrorCode KSPSetPostSolve(KSP,PetscErrorCode (*)(KSP,Vec,Vec,void*),void*);

    112: PETSC_EXTERN PetscErrorCode KSPSetPC(KSP,PC);
    113: PETSC_EXTERN PetscErrorCode KSPGetPC(KSP,PC*);

    115: PETSC_EXTERN PetscErrorCode KSPMonitor(KSP,PetscInt,PetscReal);
    116: PETSC_EXTERN PetscErrorCode KSPMonitorSet(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void**));
    117: PETSC_EXTERN PetscErrorCode KSPMonitorCancel(KSP);
    118: PETSC_EXTERN PetscErrorCode KSPGetMonitorContext(KSP,void **);
    119: PETSC_EXTERN PetscErrorCode KSPGetResidualHistory(KSP,PetscReal*[],PetscInt *);
    120: PETSC_EXTERN PetscErrorCode KSPSetResidualHistory(KSP,PetscReal[],PetscInt,PetscBool );

    122: PETSC_EXTERN PetscErrorCode KSPBuildSolutionDefault(KSP,Vec,Vec*);
    123: PETSC_EXTERN PetscErrorCode KSPBuildResidualDefault(KSP,Vec,Vec,Vec *);
    124: PETSC_EXTERN PetscErrorCode KSPDestroyDefault(KSP);
    125: PETSC_EXTERN PetscErrorCode KSPSetWorkVecs(KSP,PetscInt);

    127: PETSC_EXTERN PetscErrorCode PCKSPGetKSP(PC,KSP*);
    128: PETSC_EXTERN PetscErrorCode PCBJacobiGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
    129: PETSC_EXTERN PetscErrorCode PCASMGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
    130: PETSC_EXTERN PetscErrorCode PCGASMGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
    131: PETSC_EXTERN PetscErrorCode PCFieldSplitGetSubKSP(PC,PetscInt*,KSP*[]);
    132: PETSC_EXTERN PetscErrorCode PCMGGetSmoother(PC,PetscInt,KSP*);
    133: PETSC_EXTERN PetscErrorCode PCMGGetSmootherDown(PC,PetscInt,KSP*);
    134: PETSC_EXTERN PetscErrorCode PCMGGetSmootherUp(PC,PetscInt,KSP*);
    135: PETSC_EXTERN PetscErrorCode PCMGGetCoarseSolve(PC,KSP*);
    136: PETSC_EXTERN PetscErrorCode PCGalerkinGetKSP(PC,KSP *);

    138: PETSC_EXTERN PetscErrorCode KSPBuildSolution(KSP,Vec,Vec *);
    139: PETSC_EXTERN PetscErrorCode KSPBuildResidual(KSP,Vec,Vec,Vec *);

    141: PETSC_EXTERN PetscErrorCode KSPRichardsonSetScale(KSP,PetscReal);
    142: PETSC_EXTERN PetscErrorCode KSPRichardsonSetSelfScale(KSP,PetscBool );
    143: PETSC_EXTERN PetscErrorCode KSPChebyshevSetEigenvalues(KSP,PetscReal,PetscReal);
    144: PETSC_EXTERN PetscErrorCode KSPChebyshevEstEigSet(KSP,PetscReal,PetscReal,PetscReal,PetscReal);
    145: PETSC_EXTERN PetscErrorCode KSPChebyshevEstEigSetRandom(KSP,PetscRandom);
    146: PETSC_EXTERN PetscErrorCode KSPChebyshevEstEigGetKSP(KSP,KSP*);
    147: PETSC_EXTERN PetscErrorCode KSPComputeExtremeSingularValues(KSP,PetscReal*,PetscReal*);
    148: PETSC_EXTERN PetscErrorCode KSPComputeEigenvalues(KSP,PetscInt,PetscReal[],PetscReal[],PetscInt *);
    149: PETSC_EXTERN PetscErrorCode KSPComputeEigenvaluesExplicitly(KSP,PetscInt,PetscReal[],PetscReal[]);

    151: /*E

    153:   KSPFCGTruncationType - Define how stored directions are used to orthogonalize in FCG

    155:   KSP_FCG_TRUNC_TYPE_STANDARD uses all (up to mmax) stored directions
    156:   KSP_FCG_TRUNC_TYPE_NOTAY uses the last max(1,mod(i,mmax)) stored directions at iteration i=0,1..

    158:    Level: intermediate

    160: .seealso : KSPFCG,KSPFCGSetTruncationType(),KSPFCGGetTruncationType()

    162: E*/
    163: typedef enum {KSP_FCG_TRUNC_TYPE_STANDARD,KSP_FCG_TRUNC_TYPE_NOTAY} KSPFCGTruncationType;
    164: PETSC_EXTERN const char *const KSPFCGTruncationTypes[];

    166: PETSC_EXTERN PetscErrorCode KSPFCGSetMmax(KSP,PetscInt);
    167: PETSC_EXTERN PetscErrorCode KSPFCGGetMmax(KSP,PetscInt*);
    168: PETSC_EXTERN PetscErrorCode KSPFCGSetNprealloc(KSP,PetscInt);
    169: PETSC_EXTERN PetscErrorCode KSPFCGGetNprealloc(KSP,PetscInt*);
    170: PETSC_EXTERN PetscErrorCode KSPFCGSetTruncationType(KSP,KSPFCGTruncationType);
    171: PETSC_EXTERN PetscErrorCode KSPFCGGetTruncationType(KSP,KSPFCGTruncationType*);

    173: PETSC_EXTERN PetscErrorCode KSPGMRESSetRestart(KSP, PetscInt);
    174: PETSC_EXTERN PetscErrorCode KSPGMRESGetRestart(KSP, PetscInt*);
    175: PETSC_EXTERN PetscErrorCode KSPGMRESSetHapTol(KSP,PetscReal);

    177: PETSC_EXTERN PetscErrorCode KSPGMRESSetPreAllocateVectors(KSP);
    178: PETSC_EXTERN PetscErrorCode KSPGMRESSetOrthogonalization(KSP,PetscErrorCode (*)(KSP,PetscInt));
    179: PETSC_EXTERN PetscErrorCode KSPGMRESGetOrthogonalization(KSP,PetscErrorCode (**)(KSP,PetscInt));
    180: PETSC_EXTERN PetscErrorCode KSPGMRESModifiedGramSchmidtOrthogonalization(KSP,PetscInt);
    181: PETSC_EXTERN PetscErrorCode KSPGMRESClassicalGramSchmidtOrthogonalization(KSP,PetscInt);

    183: PETSC_EXTERN PetscErrorCode KSPLGMRESSetAugDim(KSP,PetscInt);
    184: PETSC_EXTERN PetscErrorCode KSPLGMRESSetConstant(KSP);

    186: PETSC_EXTERN PetscErrorCode KSPGCRSetRestart(KSP,PetscInt);
    187: PETSC_EXTERN PetscErrorCode KSPGCRGetRestart(KSP,PetscInt*);
    188: PETSC_EXTERN PetscErrorCode KSPGCRSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));

    190: /*E
    191:     KSPGMRESCGSRefinementType - How the classical (unmodified) Gram-Schmidt is performed.

    193:    Level: advanced

    195: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
    196:           KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSPGMRESModifiedGramSchmidtOrthogonalization()

    198: E*/
    199: typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType;
    200: PETSC_EXTERN const char *const KSPGMRESCGSRefinementTypes[];
    201: /*MC
    202:     KSP_GMRES_CGS_REFINE_NEVER - Do the classical (unmodified) Gram-Schmidt process

    204:    Level: advanced

    206:    Note: Possible unstable, but the fastest to compute

    208: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
    209:           KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
    210:           KSPGMRESModifiedGramSchmidtOrthogonalization()
    211: M*/

    213: /*MC
    214:     KSP_GMRES_CGS_REFINE_IFNEEDED - Do the classical (unmodified) Gram-Schmidt process and one step of
    215:           iterative refinement if an estimate of the orthogonality of the resulting vectors indicates
    216:           poor orthogonality.

    218:    Level: advanced

    220:    Note: This is slower than KSP_GMRES_CGS_REFINE_NEVER because it requires an extra norm computation to
    221:      estimate the orthogonality but is more stable.

    223: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
    224:           KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_ALWAYS,
    225:           KSPGMRESModifiedGramSchmidtOrthogonalization()
    226: M*/

    228: /*MC
    229:     KSP_GMRES_CGS_REFINE_NEVER - Do two steps of the classical (unmodified) Gram-Schmidt process.

    231:    Level: advanced

    233:    Note: This is roughly twice the cost of KSP_GMRES_CGS_REFINE_NEVER because it performs the process twice
    234:      but it saves the extra norm calculation needed by KSP_GMRES_CGS_REFINE_IFNEEDED.

    236:         You should only use this if you absolutely know that the iterative refinement is needed.

    238: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
    239:           KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
    240:           KSPGMRESModifiedGramSchmidtOrthogonalization()
    241: M*/

    243: PETSC_EXTERN PetscErrorCode KSPGMRESSetCGSRefinementType(KSP,KSPGMRESCGSRefinementType);
    244: PETSC_EXTERN PetscErrorCode KSPGMRESGetCGSRefinementType(KSP,KSPGMRESCGSRefinementType*);

    246: PETSC_EXTERN PetscErrorCode KSPFGMRESModifyPCNoChange(KSP,PetscInt,PetscInt,PetscReal,void*);
    247: PETSC_EXTERN PetscErrorCode KSPFGMRESModifyPCKSP(KSP,PetscInt,PetscInt,PetscReal,void*);
    248: PETSC_EXTERN PetscErrorCode KSPFGMRESSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));

    250: PETSC_EXTERN PetscErrorCode KSPQCGSetTrustRegionRadius(KSP,PetscReal);
    251: PETSC_EXTERN PetscErrorCode KSPQCGGetQuadratic(KSP,PetscReal*);
    252: PETSC_EXTERN PetscErrorCode KSPQCGGetTrialStepNorm(KSP,PetscReal*);

    254: PETSC_EXTERN PetscErrorCode KSPBCGSLSetXRes(KSP,PetscReal);
    255: PETSC_EXTERN PetscErrorCode KSPBCGSLSetPol(KSP,PetscBool );
    256: PETSC_EXTERN PetscErrorCode KSPBCGSLSetEll(KSP,PetscInt);
    257: PETSC_EXTERN PetscErrorCode KSPBCGSLSetUsePseudoinverse(KSP,PetscBool);

    259: PETSC_EXTERN PetscErrorCode KSPSetFromOptions(KSP);
    260: PETSC_EXTERN PetscErrorCode KSPAddOptionsChecker(PetscErrorCode (*)(KSP));

    262: PETSC_EXTERN PetscErrorCode KSPMonitorSingularValue(KSP,PetscInt,PetscReal,void *);
    263: PETSC_EXTERN PetscErrorCode KSPMonitorDefault(KSP,PetscInt,PetscReal,void *);
    264: PETSC_EXTERN PetscErrorCode KSPLSQRMonitorDefault(KSP,PetscInt,PetscReal,void *);
    265: PETSC_EXTERN PetscErrorCode KSPMonitorRange(KSP,PetscInt,PetscReal,void *);
    266: PETSC_EXTERN PetscErrorCode KSPMonitorDynamicTolerance(KSP ksp,PetscInt its,PetscReal fnorm,void *dummy);
    267: PETSC_EXTERN PetscErrorCode KSPMonitorDynamicToleranceDestroy(void **dummy);
    268: PETSC_EXTERN PetscErrorCode KSPMonitorTrueResidualNorm(KSP,PetscInt,PetscReal,void *);
    269: PETSC_EXTERN PetscErrorCode KSPMonitorTrueResidualMaxNorm(KSP,PetscInt,PetscReal,void *);
    270: PETSC_EXTERN PetscErrorCode KSPMonitorDefaultShort(KSP,PetscInt,PetscReal,void *);
    271: PETSC_EXTERN PetscErrorCode KSPMonitorSolution(KSP,PetscInt,PetscReal,void *);
    272: PETSC_EXTERN PetscErrorCode KSPMonitorSAWs(KSP,PetscInt,PetscReal,void*);
    273: PETSC_EXTERN PetscErrorCode KSPMonitorSAWsCreate(KSP,void**);
    274: PETSC_EXTERN PetscErrorCode KSPMonitorSAWsDestroy(void**);
    275: PETSC_EXTERN PetscErrorCode KSPGMRESMonitorKrylov(KSP,PetscInt,PetscReal,void *);

    277: PETSC_EXTERN PetscErrorCode KSPUnwindPreconditioner(KSP,Vec,Vec);
    278: PETSC_EXTERN PetscErrorCode KSPInitialResidual(KSP,Vec,Vec,Vec,Vec,Vec);

    280: PETSC_EXTERN PetscErrorCode KSPSetOperators(KSP,Mat,Mat);
    281: PETSC_EXTERN PetscErrorCode KSPGetOperators(KSP,Mat*,Mat*);
    282: PETSC_EXTERN PetscErrorCode KSPGetOperatorsSet(KSP,PetscBool *,PetscBool *);
    283: PETSC_EXTERN PetscErrorCode KSPSetOptionsPrefix(KSP,const char[]);
    284: PETSC_EXTERN PetscErrorCode KSPAppendOptionsPrefix(KSP,const char[]);
    285: PETSC_EXTERN PetscErrorCode KSPGetOptionsPrefix(KSP,const char*[]);
    286: PETSC_EXTERN PetscErrorCode KSPSetTabLevel(KSP,PetscInt);
    287: PETSC_EXTERN PetscErrorCode KSPGetTabLevel(KSP,PetscInt*);

    289: PETSC_EXTERN PetscErrorCode KSPSetDiagonalScale(KSP,PetscBool );
    290: PETSC_EXTERN PetscErrorCode KSPGetDiagonalScale(KSP,PetscBool *);
    291: PETSC_EXTERN PetscErrorCode KSPSetDiagonalScaleFix(KSP,PetscBool );
    292: PETSC_EXTERN PetscErrorCode KSPGetDiagonalScaleFix(KSP,PetscBool *);

    294: PETSC_EXTERN PetscErrorCode KSPView(KSP,PetscViewer);
    295: PETSC_EXTERN PetscErrorCode KSPLoad(KSP,PetscViewer);
    296: PETSC_STATIC_INLINE PetscErrorCode KSPViewFromOptions(KSP A,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)A,obj,name);}
    297: PETSC_EXTERN PetscErrorCode KSPReasonView(KSP,PetscViewer);
    298: PETSC_EXTERN PetscErrorCode KSPReasonViewFromOptions(KSP);

    300: #define KSP_FILE_CLASSID 1211223

    302: PETSC_EXTERN PetscErrorCode KSPLSQRSetStandardErrorVec(KSP,Vec);
    303: PETSC_EXTERN PetscErrorCode KSPLSQRGetStandardErrorVec(KSP,Vec*);

    305: PETSC_EXTERN PetscErrorCode PCRedundantGetKSP(PC,KSP*);
    306: PETSC_EXTERN PetscErrorCode PCRedistributeGetKSP(PC,KSP*);

    308: /*E
    309:     KSPNormType - Norm that is passed in the Krylov convergence
    310:        test routines.

    312:    Level: advanced

    314:    Each solver only supports a subset of these and some may support different ones
    315:    depending on left or right preconditioning, see KSPSetPCSide()

    317:    Notes: this must match petsc/finclude/petscksp.h

    319: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(),
    320:           KSPSetConvergenceTest(), KSPSetPCSide()
    321: E*/
    322: typedef enum {KSP_NORM_DEFAULT = -1,KSP_NORM_NONE = 0,KSP_NORM_PRECONDITIONED = 1,KSP_NORM_UNPRECONDITIONED = 2,KSP_NORM_NATURAL = 3} KSPNormType;
    323: #define KSP_NORM_MAX (KSP_NORM_NATURAL + 1)
    324: PETSC_EXTERN const char *const*const KSPNormTypes;

    326: /*MC
    327:     KSP_NORM_NONE - Do not compute a norm during the Krylov process. This will
    328:           possibly save some computation but means the convergence test cannot
    329:           be based on a norm of a residual etc.

    331:    Level: advanced

    333:     Note: Some Krylov methods need to compute a residual norm (such as GMRES) and then this option is ignored

    335: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL
    336: M*/

    338: /*MC
    339:     KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual B*(b - A*x), if left preconditioning, and pass that to the
    340:        convergence test routine.

    342:    Level: advanced

    344: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
    345: M*/

    347: /*MC
    348:     KSP_NORM_UNPRECONDITIONED - Compute the norm of the true residual (b - A*x) and pass that to the
    349:        convergence test routine.

    351:    Level: advanced

    353: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
    354: M*/

    356: /*MC
    357:     KSP_NORM_NATURAL - Compute the 'natural norm' of residual sqrt((b - A*x)*B*(b - A*x)) and pass that to the
    358:        convergence test routine. This is only supported by  KSPCG, KSPCR, KSPCGNE, KSPCGS, KSPFCG

    360:    Level: advanced

    362: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSPSetConvergenceTest()
    363: M*/

    365: PETSC_EXTERN PetscErrorCode KSPSetNormType(KSP,KSPNormType);
    366: PETSC_EXTERN PetscErrorCode KSPGetNormType(KSP,KSPNormType*);
    367: PETSC_EXTERN PetscErrorCode KSPSetSupportedNorm(KSP ksp,KSPNormType,PCSide,PetscInt);
    368: PETSC_EXTERN PetscErrorCode KSPSetCheckNormIteration(KSP,PetscInt);
    369: PETSC_EXTERN PetscErrorCode KSPSetLagNorm(KSP,PetscBool);

    371: /*E
    372:     KSPConvergedReason - reason a Krylov method was said to have converged or diverged

    374:    Level: beginner

    376:    Notes: See KSPGetConvergedReason() for explanation of each value

    378:    Developer notes: this must match petsc/finclude/petscksp.h

    380:       The string versions of these are KSPConvergedReasons; if you change
    381:       any of the values here also change them that array of names.

    383: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetTolerances()
    384: E*/
    385: typedef enum {/* converged */
    386:               KSP_CONVERGED_RTOL_NORMAL        =  1,
    387:               KSP_CONVERGED_ATOL_NORMAL        =  9,
    388:               KSP_CONVERGED_RTOL               =  2,
    389:               KSP_CONVERGED_ATOL               =  3,
    390:               KSP_CONVERGED_ITS                =  4,
    391:               KSP_CONVERGED_CG_NEG_CURVE       =  5,
    392:               KSP_CONVERGED_CG_CONSTRAINED     =  6,
    393:               KSP_CONVERGED_STEP_LENGTH        =  7,
    394:               KSP_CONVERGED_HAPPY_BREAKDOWN    =  8,
    395:               /* diverged */
    396:               KSP_DIVERGED_NULL                = -2,
    397:               KSP_DIVERGED_ITS                 = -3,
    398:               KSP_DIVERGED_DTOL                = -4,
    399:               KSP_DIVERGED_BREAKDOWN           = -5,
    400:               KSP_DIVERGED_BREAKDOWN_BICG      = -6,
    401:               KSP_DIVERGED_NONSYMMETRIC        = -7,
    402:               KSP_DIVERGED_INDEFINITE_PC       = -8,
    403:               KSP_DIVERGED_NANORINF            = -9,
    404:               KSP_DIVERGED_INDEFINITE_MAT      = -10,
    405:               KSP_DIVERGED_PCSETUP_FAILED      = -11,

    407:               KSP_CONVERGED_ITERATING          =  0} KSPConvergedReason;
    408: PETSC_EXTERN const char *const*KSPConvergedReasons;

    410: /*MC
    411:      KSP_CONVERGED_RTOL - norm(r) <= rtol*norm(b)

    413:    Level: beginner

    415:    See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
    416:        for left preconditioning it is the 2-norm of the preconditioned residual, and the
    417:        2-norm of the residual for right preconditioning

    419: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    421: M*/

    423: /*MC
    424:      KSP_CONVERGED_ATOL - norm(r) <= atol

    426:    Level: beginner

    428:    See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
    429:        for left preconditioning it is the 2-norm of the preconditioned residual, and the
    430:        2-norm of the residual for right preconditioning

    432:    Level: beginner

    434: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    436: M*/

    438: /*MC
    439:      KSP_DIVERGED_DTOL - norm(r) >= dtol*norm(b)

    441:    Level: beginner

    443:    See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
    444:        for left preconditioning it is the 2-norm of the preconditioned residual, and the
    445:        2-norm of the residual for right preconditioning

    447:    Level: beginner

    449: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    451: M*/

    453: /*MC
    454:      KSP_DIVERGED_ITS - Ran out of iterations before any convergence criteria was
    455:       reached

    457:    Level: beginner

    459: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    461: M*/

    463: /*MC
    464:      KSP_CONVERGED_ITS - Used by the KSPPREONLY solver after the single iteration of
    465:            the preconditioner is applied. Also used when the KSPConvergedSkip() convergence
    466:            test routine is set in KSP.

    468:    Level: beginner

    470: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    472: M*/

    474: /*MC
    475:      KSP_DIVERGED_BREAKDOWN - A breakdown in the Krylov method was detected so the
    476:           method could not continue to enlarge the Krylov space. Could be due to a singlular matrix or
    477:           preconditioner.

    479:    Level: beginner

    481: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    483: M*/

    485: /*MC
    486:      KSP_DIVERGED_BREAKDOWN_BICG - A breakdown in the KSPBICG method was detected so the
    487:           method could not continue to enlarge the Krylov space.

    489:    Level: beginner

    491: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    493: M*/

    495: /*MC
    496:      KSP_DIVERGED_NONSYMMETRIC - It appears the operator or preconditioner is not
    497:         symmetric and this Krylov method (KSPCG, KSPMINRES, KSPCR) requires symmetry

    499:    Level: beginner

    501: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    503: M*/

    505: /*MC
    506:      KSP_DIVERGED_INDEFINITE_PC - It appears the preconditioner is indefinite (has both
    507:         positive and negative eigenvalues) and this Krylov method (KSPCG) requires it to
    508:         be positive definite

    510:    Level: beginner

    512:      Notes: This can happen with the PCICC preconditioner, use -pc_factor_shift_positive_definite to force
    513:   the PCICC preconditioner to generate a positive definite preconditioner

    515: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    517: M*/

    519: /*MC
    520:      KSP_CONVERGED_ITERATING - This flag is returned if you call KSPGetConvergedReason()
    521:         while the KSPSolve() is still running.

    523:    Level: beginner

    525: .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()

    527: M*/

    529: PETSC_EXTERN PetscErrorCode KSPSetConvergenceTest(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *,PetscErrorCode (*)(void*));
    530: PETSC_EXTERN PetscErrorCode KSPGetConvergenceContext(KSP,void **);
    531: PETSC_EXTERN PetscErrorCode KSPConvergedDefault(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
    532: PETSC_EXTERN PetscErrorCode KSPConvergedLSQR(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
    533: PETSC_EXTERN PetscErrorCode KSPConvergedDefaultDestroy(void *);
    534: PETSC_EXTERN PetscErrorCode KSPConvergedDefaultCreate(void **);
    535: PETSC_EXTERN PetscErrorCode KSPConvergedDefaultSetUIRNorm(KSP);
    536: PETSC_EXTERN PetscErrorCode KSPConvergedDefaultSetUMIRNorm(KSP);
    537: PETSC_EXTERN PetscErrorCode KSPConvergedSkip(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
    538: PETSC_EXTERN PetscErrorCode KSPGetConvergedReason(KSP,KSPConvergedReason *);

    540: PETSC_DEPRECATED("Use KSPConvergedDefault()") PETSC_STATIC_INLINE void KSPDefaultConverged(void) { /* never called */ }
    541: #define KSPDefaultConverged (KSPDefaultConverged, KSPConvergedDefault)
    542: PETSC_DEPRECATED("Use KSPConvergedDefaultDestroy()") PETSC_STATIC_INLINE void KSPDefaultConvergedDestroy(void) { /* never called */ }
    543: #define KSPDefaultConvergedDestroy (KSPDefaultConvergedDestroy, KSPConvergedDefaultDestroy)
    544: PETSC_DEPRECATED("Use KSPConvergedDefaultCreate()") PETSC_STATIC_INLINE void KSPDefaultConvergedCreate(void) { /* never called */ }
    545: #define KSPDefaultConvergedCreate (KSPDefaultConvergedCreate, KSPConvergedDefaultCreate)
    546: PETSC_DEPRECATED("Use KSPConvergedDefaultSetUIRNorm()") PETSC_STATIC_INLINE void KSPDefaultConvergedSetUIRNorm(void) { /* never called */ }
    547: #define KSPDefaultConvergedSetUIRNorm (KSPDefaultConvergedSetUIRNorm, KSPConvergedDefaultSetUIRNorm)
    548: PETSC_DEPRECATED("Use KSPConvergedDefaultSetUMIRNorm()") PETSC_STATIC_INLINE void KSPDefaultConvergedSetUMIRNorm(void) { /* never called */ }
    549: #define KSPDefaultConvergedSetUMIRNorm (KSPDefaultConvergedSetUMIRNorm, KSPConvergedDefaultSetUMIRNorm)
    550: PETSC_DEPRECATED("Use KSPConvergedSkip()") PETSC_STATIC_INLINE void KSPSkipConverged(void) { /* never called */ }
    551: #define KSPSkipConverged (KSPSkipConverged, KSPConvergedSkip)

    553: PETSC_EXTERN PetscErrorCode KSPComputeExplicitOperator(KSP,Mat *);

    555: /*E
    556:     KSPCGType - Determines what type of CG to use

    558:    Level: beginner

    560: .seealso: KSPCGSetType()
    561: E*/
    562: typedef enum {KSP_CG_SYMMETRIC=0,KSP_CG_HERMITIAN=1} KSPCGType;
    563: PETSC_EXTERN const char *const KSPCGTypes[];

    565: PETSC_EXTERN PetscErrorCode KSPCGSetType(KSP,KSPCGType);
    566: PETSC_EXTERN PetscErrorCode KSPCGUseSingleReduction(KSP,PetscBool );

    568: PETSC_EXTERN PetscErrorCode KSPNASHSetRadius(KSP,PetscReal);
    569: PETSC_EXTERN PetscErrorCode KSPNASHGetNormD(KSP,PetscReal *);
    570: PETSC_EXTERN PetscErrorCode KSPNASHGetObjFcn(KSP,PetscReal *);

    572: PETSC_EXTERN PetscErrorCode KSPSTCGSetRadius(KSP,PetscReal);
    573: PETSC_EXTERN PetscErrorCode KSPSTCGGetNormD(KSP,PetscReal *);
    574: PETSC_EXTERN PetscErrorCode KSPSTCGGetObjFcn(KSP,PetscReal *);

    576: PETSC_EXTERN PetscErrorCode KSPGLTRSetRadius(KSP,PetscReal);
    577: PETSC_EXTERN PetscErrorCode KSPGLTRGetNormD(KSP,PetscReal *);
    578: PETSC_EXTERN PetscErrorCode KSPGLTRGetObjFcn(KSP,PetscReal *);
    579: PETSC_EXTERN PetscErrorCode KSPGLTRGetMinEig(KSP,PetscReal *);
    580: PETSC_EXTERN PetscErrorCode KSPGLTRGetLambda(KSP,PetscReal *);

    582: PETSC_EXTERN PetscErrorCode KSPPythonSetType(KSP,const char[]);

    584: PETSC_EXTERN PetscErrorCode PCPreSolve(PC,KSP);
    585: PETSC_EXTERN PetscErrorCode PCPostSolve(PC,KSP);

    587: #include <petscdrawtypes.h>
    588: PETSC_EXTERN PetscErrorCode KSPMonitorLGResidualNormCreate(const char[],const char[],int,int,int,int,PetscObject**);
    589: PETSC_EXTERN PetscErrorCode KSPMonitorLGResidualNorm(KSP,PetscInt,PetscReal,PetscObject*);
    590: PETSC_EXTERN PetscErrorCode KSPMonitorLGResidualNormDestroy(PetscObject**);
    591: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNormCreate(const char[],const char[],int,int,int,int,PetscObject**);
    592: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNorm(KSP,PetscInt,PetscReal,PetscObject*);
    593: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNormDestroy(PetscObject**);
    594: PETSC_EXTERN PetscErrorCode KSPMonitorLGRange(KSP,PetscInt,PetscReal,void*);

    596: PETSC_EXTERN PetscErrorCode PCShellSetPreSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));
    597: PETSC_EXTERN PetscErrorCode PCShellSetPostSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));

    599: /* see src/ksp/ksp/interface/iguess.c */
    600: typedef struct _p_KSPFischerGuess {PetscInt method,curl,maxl,refcnt;PetscBool  monitor;Mat mat; KSP ksp;}* KSPFischerGuess;

    602: PETSC_EXTERN PetscErrorCode KSPFischerGuessCreate(KSP,PetscInt,PetscInt,KSPFischerGuess*);
    603: PETSC_EXTERN PetscErrorCode KSPFischerGuessDestroy(KSPFischerGuess*);
    604: PETSC_EXTERN PetscErrorCode KSPFischerGuessReset(KSPFischerGuess);
    605: PETSC_EXTERN PetscErrorCode KSPFischerGuessUpdate(KSPFischerGuess,Vec);
    606: PETSC_EXTERN PetscErrorCode KSPFischerGuessFormGuess(KSPFischerGuess,Vec,Vec);
    607: PETSC_EXTERN PetscErrorCode KSPFischerGuessSetFromOptions(KSPFischerGuess);

    609: PETSC_EXTERN PetscErrorCode KSPSetUseFischerGuess(KSP,PetscInt,PetscInt);
    610: PETSC_EXTERN PetscErrorCode KSPSetFischerGuess(KSP,KSPFischerGuess);
    611: PETSC_EXTERN PetscErrorCode KSPGetFischerGuess(KSP,KSPFischerGuess*);

    613: /*E
    614:     MatSchurComplementAinvType - Determines how to approximate the inverse of the (0,0) block in Schur complement preconditioning matrix assembly routines

    616:     Level: intermediate

    618: .seealso: MatSchurComplementGetAinvType(), MatSchurComplementSetAinvType(), MatSchurComplementGetPmat(), MatGetSchurComplement(), MatCreateSchurComplementPmat()
    619: E*/
    620: typedef enum {MAT_SCHUR_COMPLEMENT_AINV_DIAG, MAT_SCHUR_COMPLEMENT_AINV_LUMP} MatSchurComplementAinvType;
    621: PETSC_EXTERN const char *const MatSchurComplementAinvTypes[];

    623: PETSC_EXTERN PetscErrorCode MatCreateSchurComplement(Mat,Mat,Mat,Mat,Mat,Mat*);
    624: PETSC_EXTERN PetscErrorCode MatSchurComplementGetKSP(Mat,KSP*);
    625: PETSC_EXTERN PetscErrorCode MatSchurComplementSetKSP(Mat,KSP);
    626: PETSC_EXTERN PetscErrorCode MatSchurComplementSetSubMatrices(Mat,Mat,Mat,Mat,Mat,Mat);
    627: PETSC_EXTERN PetscErrorCode MatSchurComplementUpdateSubMatrices(Mat,Mat,Mat,Mat,Mat,Mat);
    628: PETSC_EXTERN PetscErrorCode MatSchurComplementGetSubMatrices(Mat,Mat*,Mat*,Mat*,Mat*,Mat*);
    629: PETSC_EXTERN PetscErrorCode MatSchurComplementSetAinvType(Mat,MatSchurComplementAinvType);
    630: PETSC_EXTERN PetscErrorCode MatSchurComplementGetAinvType(Mat,MatSchurComplementAinvType*);
    631: PETSC_EXTERN PetscErrorCode MatSchurComplementGetPmat(Mat,MatReuse,Mat*);
    632: PETSC_EXTERN PetscErrorCode MatSchurComplementComputeExplicitOperator(Mat,Mat*);
    633: PETSC_EXTERN PetscErrorCode MatGetSchurComplement(Mat,IS,IS,IS,IS,MatReuse,Mat *,MatSchurComplementAinvType,MatReuse,Mat *);
    634: PETSC_EXTERN PetscErrorCode MatCreateSchurComplementPmat(Mat,Mat,Mat,Mat,MatSchurComplementAinvType,MatReuse,Mat*);

    636: PETSC_EXTERN PetscErrorCode KSPSetDM(KSP,DM);
    637: PETSC_EXTERN PetscErrorCode KSPSetDMActive(KSP,PetscBool );
    638: PETSC_EXTERN PetscErrorCode KSPGetDM(KSP,DM*);
    639: PETSC_EXTERN PetscErrorCode KSPSetApplicationContext(KSP,void*);
    640: PETSC_EXTERN PetscErrorCode KSPGetApplicationContext(KSP,void*);
    641: PETSC_EXTERN PetscErrorCode KSPSetComputeRHS(KSP,PetscErrorCode (*func)(KSP,Vec,void*),void *);
    642: PETSC_EXTERN PetscErrorCode KSPSetComputeOperators(KSP,PetscErrorCode(*)(KSP,Mat,Mat,void*),void*);
    643: PETSC_EXTERN PetscErrorCode KSPSetComputeInitialGuess(KSP,PetscErrorCode(*)(KSP,Vec,void*),void*);
    644: PETSC_EXTERN PetscErrorCode DMKSPSetComputeOperators(DM,PetscErrorCode(*)(KSP,Mat,Mat,void*),void*);
    645: PETSC_EXTERN PetscErrorCode DMKSPGetComputeOperators(DM,PetscErrorCode(**)(KSP,Mat,Mat,void*),void*);
    646: PETSC_EXTERN PetscErrorCode DMKSPSetComputeRHS(DM,PetscErrorCode(*)(KSP,Vec,void*),void*);
    647: PETSC_EXTERN PetscErrorCode DMKSPGetComputeRHS(DM,PetscErrorCode(**)(KSP,Vec,void*),void*);
    648: PETSC_EXTERN PetscErrorCode DMKSPSetComputeInitialGuess(DM,PetscErrorCode(*)(KSP,Vec,void*),void*);
    649: PETSC_EXTERN PetscErrorCode DMKSPGetComputeInitialGuess(DM,PetscErrorCode(**)(KSP,Vec,void*),void*);

    651: PETSC_EXTERN PetscErrorCode DMGlobalToLocalSolve(DM,Vec,Vec);
    652: PETSC_EXTERN PetscErrorCode DMPlexProjectField(DM, Vec, void (**)(const PetscScalar[], const PetscScalar[], const PetscScalar[], const PetscScalar[], const PetscScalar[], const PetscScalar[], const PetscReal [], PetscScalar []), InsertMode, Vec);
    653: #endif