Actual source code: petscksp.h
petsc-3.3-p7 2013-05-11
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(const char[]);
10: /*S
11: KSP - Abstract PETSc object that manages all Krylov methods
13: Level: beginner
15: Concepts: Krylov methods
17: .seealso: KSPCreate(), KSPSetType(), KSPType, SNES, TS, PC, KSP
18: S*/
19: typedef struct _p_KSP* KSP;
21: /*J
22: KSPType - String with the name of a PETSc Krylov method or the creation function
23: with an optional dynamic library name, for example
24: http://www.mcs.anl.gov/petsc/lib.a:mykspcreate()
26: Level: beginner
28: .seealso: KSPSetType(), KSP
29: J*/
30: #define KSPType char*
31: #define KSPRICHARDSON "richardson"
32: #define KSPCHEBYSHEV "chebyshev"
33: #define KSPCG "cg"
34: #define KSPCGNE "cgne"
35: #define KSPNASH "nash"
36: #define KSPSTCG "stcg"
37: #define KSPGLTR "gltr"
38: #define KSPGMRES "gmres"
39: #define KSPFGMRES "fgmres"
40: #define KSPLGMRES "lgmres"
41: #define KSPDGMRES "dgmres"
42: #define KSPPGMRES "pgmres"
43: #define KSPTCQMR "tcqmr"
44: #define KSPBCGS "bcgs"
45: #define KSPIBCGS "ibcgs"
46: #define KSPFBCGS "fbcgs"
47: #define KSPIFBCGS "ifbcgs"
48: #define KSPBCGSL "bcgsl"
49: #define KSPCGS "cgs"
50: #define KSPTFQMR "tfqmr"
51: #define KSPCR "cr"
52: #define KSPLSQR "lsqr"
53: #define KSPPREONLY "preonly"
54: #define KSPQCG "qcg"
55: #define KSPBICG "bicg"
56: #define KSPMINRES "minres"
57: #define KSPSYMMLQ "symmlq"
58: #define KSPLCD "lcd"
59: #define KSPPYTHON "python"
60: #define KSPGCR "gcr"
61: #define KSPSPECEST "specest"
63: /* Logging support */
64: PETSC_EXTERN PetscClassId KSP_CLASSID;
66: PETSC_EXTERN PetscErrorCode KSPCreate(MPI_Comm,KSP *);
67: PETSC_EXTERN PetscErrorCode KSPSetType(KSP,const KSPType);
68: PETSC_EXTERN PetscErrorCode KSPSetUp(KSP);
69: PETSC_EXTERN PetscErrorCode KSPSetUpOnBlocks(KSP);
70: PETSC_EXTERN PetscErrorCode KSPSolve(KSP,Vec,Vec);
71: PETSC_EXTERN PetscErrorCode KSPSolveTranspose(KSP,Vec,Vec);
72: PETSC_EXTERN PetscErrorCode KSPReset(KSP);
73: PETSC_EXTERN PetscErrorCode KSPDestroy(KSP*);
75: PETSC_EXTERN PetscFList KSPList;
76: PETSC_EXTERN PetscBool KSPRegisterAllCalled;
77: PETSC_EXTERN PetscErrorCode KSPRegisterAll(const char[]);
78: PETSC_EXTERN PetscErrorCode KSPRegisterDestroy(void);
79: PETSC_EXTERN PetscErrorCode KSPRegister(const char[],const char[],const char[],PetscErrorCode (*)(KSP));
81: /*MC
82: KSPRegisterDynamic - Adds a method to the Krylov subspace solver package.
84: Synopsis:
85: PetscErrorCode KSPRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(KSP))
87: Not Collective
89: Input Parameters:
90: + name_solver - name of a new user-defined solver
91: . path - path (either absolute or relative) the library containing this solver
92: . name_create - name of routine to create method context
93: - routine_create - routine to create method context
95: Notes:
96: KSPRegisterDynamic() may be called multiple times to add several user-defined solvers.
98: If dynamic libraries are used, then the fourth input argument (routine_create)
99: is ignored.
101: Sample usage:
102: .vb
103: KSPRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,
104: "MySolverCreate",MySolverCreate);
105: .ve
107: Then, your solver can be chosen with the procedural interface via
108: $ KSPSetType(ksp,"my_solver")
109: or at runtime via the option
110: $ -ksp_type my_solver
112: Level: advanced
114: Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
115: and others of the form ${any_environmental_variable} occuring in pathname will be
116: replaced with appropriate values.
117: If your function is not being put into a shared library then use KSPRegister() instead
119: .keywords: KSP, register
121: .seealso: KSPRegisterAll(), KSPRegisterDestroy()
123: M*/
124: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
125: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,0)
126: #else
127: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,d)
128: #endif
130: PETSC_EXTERN PetscErrorCode KSPGetType(KSP,const KSPType *);
131: PETSC_EXTERN PetscErrorCode KSPSetPCSide(KSP,PCSide);
132: PETSC_EXTERN PetscErrorCode KSPGetPCSide(KSP,PCSide*);
133: PETSC_EXTERN PetscErrorCode KSPGetTolerances(KSP,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
134: PETSC_EXTERN PetscErrorCode KSPSetTolerances(KSP,PetscReal,PetscReal,PetscReal,PetscInt);
135: PETSC_EXTERN PetscErrorCode KSPSetInitialGuessNonzero(KSP,PetscBool );
136: PETSC_EXTERN PetscErrorCode KSPGetInitialGuessNonzero(KSP,PetscBool *);
137: PETSC_EXTERN PetscErrorCode KSPSetInitialGuessKnoll(KSP,PetscBool );
138: PETSC_EXTERN PetscErrorCode KSPGetInitialGuessKnoll(KSP,PetscBool *);
139: PETSC_EXTERN PetscErrorCode KSPSetErrorIfNotConverged(KSP,PetscBool );
140: PETSC_EXTERN PetscErrorCode KSPGetErrorIfNotConverged(KSP,PetscBool *);
141: PETSC_EXTERN PetscErrorCode KSPGetComputeEigenvalues(KSP,PetscBool *);
142: PETSC_EXTERN PetscErrorCode KSPSetComputeEigenvalues(KSP,PetscBool );
143: PETSC_EXTERN PetscErrorCode KSPGetComputeSingularValues(KSP,PetscBool *);
144: PETSC_EXTERN PetscErrorCode KSPSetComputeSingularValues(KSP,PetscBool );
145: PETSC_EXTERN PetscErrorCode KSPGetRhs(KSP,Vec *);
146: PETSC_EXTERN PetscErrorCode KSPGetSolution(KSP,Vec *);
147: PETSC_EXTERN PetscErrorCode KSPGetResidualNorm(KSP,PetscReal*);
148: PETSC_EXTERN PetscErrorCode KSPGetIterationNumber(KSP,PetscInt*);
149: PETSC_EXTERN PetscErrorCode KSPSetNullSpace(KSP,MatNullSpace);
150: PETSC_EXTERN PetscErrorCode KSPGetNullSpace(KSP,MatNullSpace*);
151: PETSC_EXTERN PetscErrorCode KSPGetVecs(KSP,PetscInt,Vec**,PetscInt,Vec**);
153: PETSC_EXTERN PetscErrorCode KSPSetPC(KSP,PC);
154: PETSC_EXTERN PetscErrorCode KSPGetPC(KSP,PC*);
156: PETSC_EXTERN PetscErrorCode KSPMonitor(KSP,PetscInt,PetscReal);
157: PETSC_EXTERN PetscErrorCode KSPMonitorSet(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void**));
158: PETSC_EXTERN PetscErrorCode KSPMonitorCancel(KSP);
159: PETSC_EXTERN PetscErrorCode KSPGetMonitorContext(KSP,void **);
160: PETSC_EXTERN PetscErrorCode KSPGetResidualHistory(KSP,PetscReal*[],PetscInt *);
161: PETSC_EXTERN PetscErrorCode KSPSetResidualHistory(KSP,PetscReal[],PetscInt,PetscBool );
163: /* not sure where to put this */
164: PETSC_EXTERN PetscErrorCode PCKSPGetKSP(PC,KSP*);
165: PETSC_EXTERN PetscErrorCode PCBJacobiGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
166: PETSC_EXTERN PetscErrorCode PCASMGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
167: PETSC_EXTERN PetscErrorCode PCGASMGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
168: PETSC_EXTERN PetscErrorCode PCFieldSplitGetSubKSP(PC,PetscInt*,KSP*[]);
170: PETSC_EXTERN PetscErrorCode PCGalerkinGetKSP(PC,KSP *);
172: PETSC_EXTERN PetscErrorCode KSPBuildSolution(KSP,Vec,Vec *);
173: PETSC_EXTERN PetscErrorCode KSPBuildResidual(KSP,Vec,Vec,Vec *);
175: PETSC_EXTERN PetscErrorCode KSPRichardsonSetScale(KSP,PetscReal);
176: PETSC_EXTERN PetscErrorCode KSPRichardsonSetSelfScale(KSP,PetscBool );
177: PETSC_EXTERN PetscErrorCode KSPChebyshevSetEigenvalues(KSP,PetscReal,PetscReal);
178: PETSC_EXTERN PetscErrorCode KSPChebyshevSetEstimateEigenvalues(KSP,PetscReal,PetscReal,PetscReal,PetscReal);
179: PETSC_EXTERN PetscErrorCode KSPChebyshevSetNewMatrix(KSP);
180: PETSC_EXTERN PetscErrorCode KSPComputeExtremeSingularValues(KSP,PetscReal*,PetscReal*);
181: PETSC_EXTERN PetscErrorCode KSPComputeEigenvalues(KSP,PetscInt,PetscReal*,PetscReal*,PetscInt *);
182: PETSC_EXTERN PetscErrorCode KSPComputeEigenvaluesExplicitly(KSP,PetscInt,PetscReal*,PetscReal*);
184: PETSC_EXTERN PetscErrorCode KSPGMRESSetRestart(KSP, PetscInt);
185: PETSC_EXTERN PetscErrorCode KSPGMRESGetRestart(KSP, PetscInt*);
186: PETSC_EXTERN PetscErrorCode KSPGMRESSetHapTol(KSP,PetscReal);
188: PETSC_EXTERN PetscErrorCode KSPGMRESSetPreAllocateVectors(KSP);
189: PETSC_EXTERN PetscErrorCode KSPGMRESSetOrthogonalization(KSP,PetscErrorCode (*)(KSP,PetscInt));
190: PETSC_EXTERN PetscErrorCode KSPGMRESGetOrthogonalization(KSP,PetscErrorCode (**)(KSP,PetscInt));
191: PETSC_EXTERN PetscErrorCode KSPGMRESModifiedGramSchmidtOrthogonalization(KSP,PetscInt);
192: PETSC_EXTERN PetscErrorCode KSPGMRESClassicalGramSchmidtOrthogonalization(KSP,PetscInt);
194: PETSC_EXTERN PetscErrorCode KSPLGMRESSetAugDim(KSP,PetscInt);
195: PETSC_EXTERN PetscErrorCode KSPLGMRESSetConstant(KSP);
197: PETSC_EXTERN PetscErrorCode KSPGCRSetRestart(KSP,PetscInt);
198: PETSC_EXTERN PetscErrorCode KSPGCRGetRestart(KSP,PetscInt*);
199: PETSC_EXTERN PetscErrorCode KSPGCRSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));
201: /*E
202: KSPGMRESCGSRefinementType - How the classical (unmodified) Gram-Schmidt is performed.
204: Level: advanced
206: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
207: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSPGMRESModifiedGramSchmidtOrthogonalization()
209: E*/
210: typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType;
211: PETSC_EXTERN const char *KSPGMRESCGSRefinementTypes[];
212: /*MC
213: KSP_GMRES_CGS_REFINE_NEVER - Just do the classical (unmodified) Gram-Schmidt process
215: Level: advanced
217: Note: Possible unstable, but the fastest to compute
219: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
220: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
221: KSPGMRESModifiedGramSchmidtOrthogonalization()
222: M*/
224: /*MC
225: KSP_GMRES_CGS_REFINE_IFNEEDED - Do the classical (unmodified) Gram-Schmidt process and one step of
226: iterative refinement if an estimate of the orthogonality of the resulting vectors indicates
227: poor orthogonality.
229: Level: advanced
231: Note: This is slower than KSP_GMRES_CGS_REFINE_NEVER because it requires an extra norm computation to
232: estimate the orthogonality but is more stable.
234: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
235: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_ALWAYS,
236: KSPGMRESModifiedGramSchmidtOrthogonalization()
237: M*/
239: /*MC
240: KSP_GMRES_CGS_REFINE_NEVER - Do two steps of the classical (unmodified) Gram-Schmidt process.
242: Level: advanced
244: Note: This is roughly twice the cost of KSP_GMRES_CGS_REFINE_NEVER because it performs the process twice
245: but it saves the extra norm calculation needed by KSP_GMRES_CGS_REFINE_IFNEEDED.
247: You should only use this if you absolutely know that the iterative refinement is needed.
249: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
250: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
251: KSPGMRESModifiedGramSchmidtOrthogonalization()
252: M*/
254: PETSC_EXTERN PetscErrorCode KSPGMRESSetCGSRefinementType(KSP,KSPGMRESCGSRefinementType);
255: PETSC_EXTERN PetscErrorCode KSPGMRESGetCGSRefinementType(KSP,KSPGMRESCGSRefinementType*);
257: PETSC_EXTERN PetscErrorCode KSPFGMRESModifyPCNoChange(KSP,PetscInt,PetscInt,PetscReal,void*);
258: PETSC_EXTERN PetscErrorCode KSPFGMRESModifyPCKSP(KSP,PetscInt,PetscInt,PetscReal,void*);
259: PETSC_EXTERN PetscErrorCode KSPFGMRESSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));
261: PETSC_EXTERN PetscErrorCode KSPQCGSetTrustRegionRadius(KSP,PetscReal);
262: PETSC_EXTERN PetscErrorCode KSPQCGGetQuadratic(KSP,PetscReal*);
263: PETSC_EXTERN PetscErrorCode KSPQCGGetTrialStepNorm(KSP,PetscReal*);
265: PETSC_EXTERN PetscErrorCode KSPBCGSLSetXRes(KSP,PetscReal);
266: PETSC_EXTERN PetscErrorCode KSPBCGSLSetPol(KSP,PetscBool );
267: PETSC_EXTERN PetscErrorCode KSPBCGSLSetEll(KSP,PetscInt);
269: PETSC_EXTERN PetscErrorCode KSPSetFromOptions(KSP);
270: PETSC_EXTERN PetscErrorCode KSPAddOptionsChecker(PetscErrorCode (*)(KSP));
272: PETSC_EXTERN PetscErrorCode KSPMonitorSingularValue(KSP,PetscInt,PetscReal,void *);
273: PETSC_EXTERN PetscErrorCode KSPMonitorDefault(KSP,PetscInt,PetscReal,void *);
274: PETSC_EXTERN PetscErrorCode KSPLSQRMonitorDefault(KSP,PetscInt,PetscReal,void *);
275: PETSC_EXTERN PetscErrorCode KSPMonitorRange(KSP,PetscInt,PetscReal,void *);
276: PETSC_EXTERN PetscErrorCode KSPMonitorTrueResidualNorm(KSP,PetscInt,PetscReal,void *);
277: PETSC_EXTERN PetscErrorCode KSPMonitorDefaultShort(KSP,PetscInt,PetscReal,void *);
278: PETSC_EXTERN PetscErrorCode KSPMonitorSolution(KSP,PetscInt,PetscReal,void *);
279: PETSC_EXTERN PetscErrorCode KSPMonitorAMS(KSP,PetscInt,PetscReal,void*);
280: PETSC_EXTERN PetscErrorCode KSPMonitorAMSCreate(KSP,const char*,void**);
281: PETSC_EXTERN PetscErrorCode KSPMonitorAMSDestroy(void**);
282: PETSC_EXTERN PetscErrorCode KSPGMRESMonitorKrylov(KSP,PetscInt,PetscReal,void *);
284: PETSC_EXTERN PetscErrorCode KSPUnwindPreconditioner(KSP,Vec,Vec);
285: PETSC_EXTERN PetscErrorCode KSPDefaultBuildSolution(KSP,Vec,Vec*);
286: PETSC_EXTERN PetscErrorCode KSPDefaultBuildResidual(KSP,Vec,Vec,Vec *);
287: PETSC_EXTERN PetscErrorCode KSPInitialResidual(KSP,Vec,Vec,Vec,Vec,Vec);
289: PETSC_EXTERN PetscErrorCode KSPSetOperators(KSP,Mat,Mat,MatStructure);
290: PETSC_EXTERN PetscErrorCode KSPGetOperators(KSP,Mat*,Mat*,MatStructure*);
291: PETSC_EXTERN PetscErrorCode KSPGetOperatorsSet(KSP,PetscBool *,PetscBool *);
292: PETSC_EXTERN PetscErrorCode KSPSetOptionsPrefix(KSP,const char[]);
293: PETSC_EXTERN PetscErrorCode KSPAppendOptionsPrefix(KSP,const char[]);
294: PETSC_EXTERN PetscErrorCode KSPGetOptionsPrefix(KSP,const char*[]);
296: PETSC_EXTERN PetscErrorCode KSPSetDiagonalScale(KSP,PetscBool );
297: PETSC_EXTERN PetscErrorCode KSPGetDiagonalScale(KSP,PetscBool *);
298: PETSC_EXTERN PetscErrorCode KSPSetDiagonalScaleFix(KSP,PetscBool );
299: PETSC_EXTERN PetscErrorCode KSPGetDiagonalScaleFix(KSP,PetscBool *);
301: PETSC_EXTERN PetscErrorCode KSPView(KSP,PetscViewer);
303: PETSC_EXTERN PetscErrorCode KSPLSQRSetStandardErrorVec(KSP,Vec);
304: PETSC_EXTERN PetscErrorCode KSPLSQRGetStandardErrorVec(KSP,Vec*);
306: PETSC_EXTERN PetscErrorCode PCRedundantGetKSP(PC,KSP*);
307: PETSC_EXTERN PetscErrorCode PCRedistributeGetKSP(PC,KSP*);
309: /*E
310: KSPNormType - Norm that is passed in the Krylov convergence
311: test routines.
313: Level: advanced
315: Each solver only supports a subset of these and some may support different ones
316: depending on left or right preconditioning, see KSPSetPCSide()
318: Notes: this must match finclude/petscksp.h
320: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(),
321: KSPSetConvergenceTest(), KSPSetPCSide()
322: E*/
323: typedef enum {KSP_NORM_DEFAULT = -1,KSP_NORM_NONE = 0,KSP_NORM_PRECONDITIONED = 1,KSP_NORM_UNPRECONDITIONED = 2,KSP_NORM_NATURAL = 3} KSPNormType;
324: #define KSP_NORM_MAX (KSP_NORM_NATURAL + 1)
325: PETSC_EXTERN const char *const*const KSPNormTypes;
327: /*MC
328: KSP_NORM_NONE - Do not compute a norm during the Krylov process. This will
329: possibly save some computation but means the convergence test cannot
330: be based on a norm of a residual etc.
332: Level: advanced
334: Note: Some Krylov methods need to compute a residual norm and then this option is ignored
336: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL
337: M*/
339: /*MC
340: KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual and pass that to the
341: convergence test routine.
343: Level: advanced
345: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
346: M*/
348: /*MC
349: KSP_NORM_UNPRECONDITIONED - Compute the norm of the true residual (b - A*x) and pass that to the
350: convergence test routine.
352: Level: advanced
354: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
355: M*/
357: /*MC
358: KSP_NORM_NATURAL - Compute the 'natural norm' of residual sqrt((b - A*x)*B*(b - A*x)) and pass that to the
359: convergence test routine. This is only supported by KSPCG, KSPCR, KSPCGNE, KSPCGS
361: Level: advanced
363: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSPSetConvergenceTest()
364: M*/
366: PETSC_EXTERN PetscErrorCode KSPSetNormType(KSP,KSPNormType);
367: PETSC_EXTERN PetscErrorCode KSPGetNormType(KSP,KSPNormType*);
368: PETSC_EXTERN PetscErrorCode KSPSetSupportedNorm(KSP ksp,KSPNormType,PCSide,PetscInt);
369: PETSC_EXTERN PetscErrorCode KSPSetCheckNormIteration(KSP,PetscInt);
370: PETSC_EXTERN PetscErrorCode KSPSetLagNorm(KSP,PetscBool );
372: /*E
373: KSPConvergedReason - reason a Krylov method was said to
374: have converged or diverged
376: Level: beginner
378: Notes: See KSPGetConvergedReason() for explanation of each value
380: Developer notes: this must match finclude/petscksp.h
382: The string versions of these are KSPConvergedReasons; if you change
383: any of the values here also change them that array of names.
385: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetTolerances()
386: E*/
387: typedef enum {/* converged */
388: KSP_CONVERGED_RTOL_NORMAL = 1,
389: KSP_CONVERGED_ATOL_NORMAL = 9,
390: KSP_CONVERGED_RTOL = 2,
391: KSP_CONVERGED_ATOL = 3,
392: KSP_CONVERGED_ITS = 4,
393: KSP_CONVERGED_CG_NEG_CURVE = 5,
394: KSP_CONVERGED_CG_CONSTRAINED = 6,
395: KSP_CONVERGED_STEP_LENGTH = 7,
396: KSP_CONVERGED_HAPPY_BREAKDOWN = 8,
397: /* diverged */
398: KSP_DIVERGED_NULL = -2,
399: KSP_DIVERGED_ITS = -3,
400: KSP_DIVERGED_DTOL = -4,
401: KSP_DIVERGED_BREAKDOWN = -5,
402: KSP_DIVERGED_BREAKDOWN_BICG = -6,
403: KSP_DIVERGED_NONSYMMETRIC = -7,
404: KSP_DIVERGED_INDEFINITE_PC = -8,
405: KSP_DIVERGED_NAN = -9,
406: KSP_DIVERGED_INDEFINITE_MAT = -10,
407:
408: KSP_CONVERGED_ITERATING = 0} KSPConvergedReason;
409: PETSC_EXTERN const char *const*KSPConvergedReasons;
411: /*MC
412: KSP_CONVERGED_RTOL - norm(r) <= rtol*norm(b)
414: Level: beginner
416: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
417: for left preconditioning it is the 2-norm of the preconditioned residual, and the
418: 2-norm of the residual for right preconditioning
420: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
422: M*/
424: /*MC
425: KSP_CONVERGED_ATOL - norm(r) <= atol
427: Level: beginner
429: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
430: for left preconditioning it is the 2-norm of the preconditioned residual, and the
431: 2-norm of the residual for right preconditioning
433: Level: beginner
435: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
437: M*/
439: /*MC
440: KSP_DIVERGED_DTOL - norm(r) >= dtol*norm(b)
442: Level: beginner
444: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
445: for left preconditioning it is the 2-norm of the preconditioned residual, and the
446: 2-norm of the residual for right preconditioning
448: Level: beginner
450: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
452: M*/
454: /*MC
455: KSP_DIVERGED_ITS - Ran out of iterations before any convergence criteria was
456: reached
458: Level: beginner
460: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
462: M*/
464: /*MC
465: KSP_CONVERGED_ITS - Used by the KSPPREONLY solver after the single iteration of
466: the preconditioner is applied. Also used when the KSPSkipConverged() convergence
467: test routine is set in KSP.
470: Level: beginner
473: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
475: M*/
477: /*MC
478: KSP_DIVERGED_BREAKDOWN - A breakdown in the Krylov method was detected so the
479: method could not continue to enlarge the Krylov space. Could be due to a singlular matrix or
480: preconditioner.
482: Level: beginner
484: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
486: M*/
488: /*MC
489: KSP_DIVERGED_BREAKDOWN_BICG - A breakdown in the KSPBICG method was detected so the
490: method could not continue to enlarge the Krylov space.
493: Level: beginner
496: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
498: M*/
500: /*MC
501: KSP_DIVERGED_NONSYMMETRIC - It appears the operator or preconditioner is not
502: symmetric and this Krylov method (KSPCG, KSPMINRES, KSPCR) requires symmetry
504: Level: beginner
506: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
508: M*/
510: /*MC
511: KSP_DIVERGED_INDEFINITE_PC - It appears the preconditioner is indefinite (has both
512: positive and negative eigenvalues) and this Krylov method (KSPCG) requires it to
513: be positive definite
515: Level: beginner
517: Notes: This can happen with the PCICC preconditioner, use -pc_factor_shift_positive_definite to force
518: the PCICC preconditioner to generate a positive definite preconditioner
520: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
522: M*/
524: /*MC
525: KSP_CONVERGED_ITERATING - This flag is returned if you call KSPGetConvergedReason()
526: while the KSPSolve() is still running.
528: Level: beginner
530: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
532: M*/
534: PETSC_EXTERN PetscErrorCode KSPSetConvergenceTest(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *,PetscErrorCode (*)(void*));
535: PETSC_EXTERN PetscErrorCode KSPGetConvergenceContext(KSP,void **);
536: PETSC_EXTERN PetscErrorCode KSPDefaultConverged(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
537: PETSC_EXTERN PetscErrorCode KSPConvergedLSQR(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
538: PETSC_EXTERN PetscErrorCode KSPDefaultConvergedDestroy(void *);
539: PETSC_EXTERN PetscErrorCode KSPDefaultConvergedCreate(void **);
540: PETSC_EXTERN PetscErrorCode KSPDefaultConvergedSetUIRNorm(KSP);
541: PETSC_EXTERN PetscErrorCode KSPDefaultConvergedSetUMIRNorm(KSP);
542: PETSC_EXTERN PetscErrorCode KSPSkipConverged(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
543: PETSC_EXTERN PetscErrorCode KSPGetConvergedReason(KSP,KSPConvergedReason *);
545: PETSC_EXTERN PetscErrorCode KSPComputeExplicitOperator(KSP,Mat *);
547: /*E
548: KSPCGType - Determines what type of CG to use
550: Level: beginner
552: .seealso: KSPCGSetType()
553: E*/
554: typedef enum {KSP_CG_SYMMETRIC=0,KSP_CG_HERMITIAN=1} KSPCGType;
555: PETSC_EXTERN const char *KSPCGTypes[];
557: PETSC_EXTERN PetscErrorCode KSPCGSetType(KSP,KSPCGType);
558: PETSC_EXTERN PetscErrorCode KSPCGUseSingleReduction(KSP,PetscBool );
560: PETSC_EXTERN PetscErrorCode KSPNASHSetRadius(KSP,PetscReal);
561: PETSC_EXTERN PetscErrorCode KSPNASHGetNormD(KSP,PetscReal *);
562: PETSC_EXTERN PetscErrorCode KSPNASHGetObjFcn(KSP,PetscReal *);
564: PETSC_EXTERN PetscErrorCode KSPSTCGSetRadius(KSP,PetscReal);
565: PETSC_EXTERN PetscErrorCode KSPSTCGGetNormD(KSP,PetscReal *);
566: PETSC_EXTERN PetscErrorCode KSPSTCGGetObjFcn(KSP,PetscReal *);
568: PETSC_EXTERN PetscErrorCode KSPGLTRSetRadius(KSP,PetscReal);
569: PETSC_EXTERN PetscErrorCode KSPGLTRGetNormD(KSP,PetscReal *);
570: PETSC_EXTERN PetscErrorCode KSPGLTRGetObjFcn(KSP,PetscReal *);
571: PETSC_EXTERN PetscErrorCode KSPGLTRGetMinEig(KSP,PetscReal *);
572: PETSC_EXTERN PetscErrorCode KSPGLTRGetLambda(KSP,PetscReal *);
574: PETSC_EXTERN PetscErrorCode KSPPythonSetType(KSP,const char[]);
576: PETSC_EXTERN PetscErrorCode PCPreSolve(PC,KSP);
577: PETSC_EXTERN PetscErrorCode PCPostSolve(PC,KSP);
579: PETSC_EXTERN PetscErrorCode KSPMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
580: PETSC_EXTERN PetscErrorCode KSPMonitorLG(KSP,PetscInt,PetscReal,void*);
581: PETSC_EXTERN PetscErrorCode KSPMonitorLGDestroy(PetscDrawLG*);
582: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNormCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
583: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNorm(KSP,PetscInt,PetscReal,void*);
584: PETSC_EXTERN PetscErrorCode KSPMonitorLGTrueResidualNormDestroy(PetscDrawLG*);
585: PETSC_EXTERN PetscErrorCode KSPMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
586: PETSC_EXTERN PetscErrorCode KSPMonitorLGRange(KSP,PetscInt,PetscReal,void*);
587: PETSC_EXTERN PetscErrorCode KSPMonitorLGRangeDestroy(PetscDrawLG*);
589: PETSC_EXTERN PetscErrorCode PCShellSetPreSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));
590: PETSC_EXTERN PetscErrorCode PCShellSetPostSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));
592: /* see src/ksp/ksp/interface/iguess.c */
593: typedef struct _p_KSPFischerGuess {PetscInt method,curl,maxl,refcnt;PetscBool monitor;Mat mat; KSP ksp;}* KSPFischerGuess;
595: PETSC_EXTERN PetscErrorCode KSPFischerGuessCreate(KSP,PetscInt,PetscInt,KSPFischerGuess*);
596: PETSC_EXTERN PetscErrorCode KSPFischerGuessDestroy(KSPFischerGuess*);
597: PETSC_EXTERN PetscErrorCode KSPFischerGuessReset(KSPFischerGuess);
598: PETSC_EXTERN PetscErrorCode KSPFischerGuessUpdate(KSPFischerGuess,Vec);
599: PETSC_EXTERN PetscErrorCode KSPFischerGuessFormGuess(KSPFischerGuess,Vec,Vec);
600: PETSC_EXTERN PetscErrorCode KSPFischerGuessSetFromOptions(KSPFischerGuess);
602: PETSC_EXTERN PetscErrorCode KSPSetUseFischerGuess(KSP,PetscInt,PetscInt);
603: PETSC_EXTERN PetscErrorCode KSPSetFischerGuess(KSP,KSPFischerGuess);
604: PETSC_EXTERN PetscErrorCode KSPGetFischerGuess(KSP,KSPFischerGuess*);
606: PETSC_EXTERN PetscErrorCode MatCreateSchurComplement(Mat,Mat,Mat,Mat,Mat,Mat*);
607: PETSC_EXTERN PetscErrorCode MatSchurComplementGetKSP(Mat,KSP*);
608: PETSC_EXTERN PetscErrorCode MatSchurComplementUpdate(Mat,Mat,Mat,Mat,Mat,Mat,MatStructure);
609: PETSC_EXTERN PetscErrorCode MatSchurComplementGetSubmatrices(Mat,Mat*,Mat*,Mat*,Mat*,Mat*);
610: PETSC_EXTERN PetscErrorCode MatGetSchurComplement(Mat,IS,IS,IS,IS,MatReuse,Mat *,MatReuse,Mat *);
612: PETSC_EXTERN PetscErrorCode MatGetSchurComplement_Basic(Mat mat,IS isrow0,IS iscol0,IS isrow1,IS iscol1,MatReuse mreuse,Mat *newmat,MatReuse preuse,Mat *newpmat);
614: PETSC_EXTERN PetscErrorCode KSPSetDM(KSP,DM);
615: PETSC_EXTERN PetscErrorCode KSPSetDMActive(KSP,PetscBool );
616: PETSC_EXTERN PetscErrorCode KSPGetDM(KSP,DM*);
617: PETSC_EXTERN PetscErrorCode KSPSetApplicationContext(KSP,void*);
618: PETSC_EXTERN PetscErrorCode KSPGetApplicationContext(KSP,void*);
619: PETSC_EXTERN PetscErrorCode KSPSetComputeOperators(KSP,PetscErrorCode(*)(KSP,Mat,Mat,MatStructure*,void*),void*);
620: PETSC_EXTERN PetscErrorCode KSPSetComputeRHS(KSP,PetscErrorCode(*)(KSP,Vec,void*),void*);
621: PETSC_EXTERN PetscErrorCode DMKSPSetComputeOperators(DM,PetscErrorCode(*)(KSP,Mat,Mat,MatStructure*,void*),void*);
622: PETSC_EXTERN PetscErrorCode DMKSPGetComputeOperators(DM,PetscErrorCode(**)(KSP,Mat,Mat,MatStructure*,void*),void*);
623: PETSC_EXTERN PetscErrorCode DMKSPSetComputeRHS(DM,PetscErrorCode(*)(KSP,Vec,void*),void*);
624: PETSC_EXTERN PetscErrorCode DMKSPGetComputeRHS(DM,PetscErrorCode(**)(KSP,Vec,void*),void*);
626: #endif