Actual source code: petscksp.h
1: /*
2: Defines the interface functions for the Krylov subspace accelerators.
3: */
4: #ifndef __PETSCKSP_H
6: #include petscpc.h
11: /*S
12: KSP - Abstract PETSc object that manages all Krylov methods
14: Level: beginner
16: Concepts: Krylov methods
18: .seealso: KSPCreate(), KSPSetType(), KSPType, SNES, TS, PC, KSP
19: S*/
20: typedef struct _p_KSP* KSP;
22: /*J
23: KSPType - String with the name of a PETSc Krylov method or the creation function
24: with an optional dynamic library name, for example
25: http://www.mcs.anl.gov/petsc/lib.a:mykspcreate()
27: Level: beginner
29: .seealso: KSPSetType(), KSP
30: J*/
31: #define KSPType char*
32: #define KSPRICHARDSON "richardson"
33: #define KSPCHEBYCHEV "chebychev"
34: #define KSPCG "cg"
35: #define KSPCGNE "cgne"
36: #define KSPNASH "nash"
37: #define KSPSTCG "stcg"
38: #define KSPGLTR "gltr"
39: #define KSPGMRES "gmres"
40: #define KSPFGMRES "fgmres"
41: #define KSPLGMRES "lgmres"
42: #define KSPDGMRES "dgmres"
43: #define KSPTCQMR "tcqmr"
44: #define KSPBCGS "bcgs"
45: #define KSPIBCGS "ibcgs"
46: #define KSPBCGSL "bcgsl"
47: #define KSPCGS "cgs"
48: #define KSPTFQMR "tfqmr"
49: #define KSPCR "cr"
50: #define KSPLSQR "lsqr"
51: #define KSPPREONLY "preonly"
52: #define KSPQCG "qcg"
53: #define KSPBICG "bicg"
54: #define KSPMINRES "minres"
55: #define KSPSYMMLQ "symmlq"
56: #define KSPLCD "lcd"
57: #define KSPPYTHON "python"
58: #define KSPBROYDEN "broyden"
59: #define KSPGCR "gcr"
60: #define KSPNGMRES "ngmres"
61: #define KSPSPECEST "specest"
63: /* Logging support */
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
163: /* not sure where to put this */
200: /*E
201: KSPGMRESCGSRefinementType - How the classical (unmodified) Gram-Schmidt is performed.
203: Level: advanced
205: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
206: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSPGMRESModifiedGramSchmidtOrthogonalization()
208: E*/
209: typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType;
211: /*MC
212: KSP_GMRES_CGS_REFINE_NEVER - Just do the classical (unmodified) Gram-Schmidt process
214: Level: advanced
216: Note: Possible unstable, but the fastest to compute
218: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
219: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
220: KSPGMRESModifiedGramSchmidtOrthogonalization()
221: M*/
223: /*MC
224: KSP_GMRES_CGS_REFINE_IFNEEDED - Do the classical (unmodified) Gram-Schmidt process and one step of
225: iterative refinement if an estimate of the orthogonality of the resulting vectors indicates
226: poor orthogonality.
228: Level: advanced
230: Note: This is slower than KSP_GMRES_CGS_REFINE_NEVER because it requires an extra norm computation to
231: estimate the orthogonality but is more stable.
233: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
234: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_ALWAYS,
235: KSPGMRESModifiedGramSchmidtOrthogonalization()
236: M*/
238: /*MC
239: KSP_GMRES_CGS_REFINE_NEVER - Do two steps of the classical (unmodified) Gram-Schmidt process.
241: Level: advanced
243: Note: This is roughly twice the cost of KSP_GMRES_CGS_REFINE_NEVER because it performs the process twice
244: but it saves the extra norm calculation needed by KSP_GMRES_CGS_REFINE_IFNEEDED.
246: You should only use this if you absolutely know that the iterative refinement is needed.
248: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), KSPGMRESGetOrthogonalization(),
249: KSPGMRESSetCGSRefinementType(), KSPGMRESGetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
250: KSPGMRESModifiedGramSchmidtOrthogonalization()
251: M*/
305: /*E
306: KSPNormType - Norm that is passed in the Krylov convergence
307: test routines.
309: Level: advanced
311: Each solver only supports a subset of these and some may support different ones
312: depending on left or right preconditioning, see KSPSetPCSide()
314: Notes: this must match finclude/petscksp.h
316: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(),
317: KSPSetConvergenceTest(), KSPSetPCSide()
318: E*/
319: typedef enum {KSP_NORM_DEFAULT = -1,KSP_NORM_NONE = 0,KSP_NORM_PRECONDITIONED = 1,KSP_NORM_UNPRECONDITIONED = 2,KSP_NORM_NATURAL = 3} KSPNormType;
320: #define KSP_NORM_MAX (KSP_NORM_NATURAL + 1)
323: /*MC
324: KSP_NORM_NONE - Do not compute a norm during the Krylov process. This will
325: possibly save some computation but means the convergence test cannot
326: be based on a norm of a residual etc.
328: Level: advanced
330: Note: Some Krylov methods need to compute a residual norm and then this option is ignored
332: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL
333: M*/
335: /*MC
336: KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual and pass that to the
337: convergence test routine.
339: Level: advanced
341: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
342: M*/
344: /*MC
345: KSP_NORM_UNPRECONDITIONED - Compute the norm of the true residual (b - A*x) and pass that to the
346: convergence test routine.
348: Level: advanced
350: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
351: M*/
353: /*MC
354: KSP_NORM_NATURAL - Compute the 'natural norm' of residual sqrt((b - A*x)*B*(b - A*x)) and pass that to the
355: convergence test routine. This is only supported by KSPCG, KSPCR, KSPCGNE, KSPCGS
357: Level: advanced
359: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NONE, KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSPSetConvergenceTest()
360: M*/
368: /*E
369: KSPConvergedReason - reason a Krylov method was said to
370: have converged or diverged
372: Level: beginner
374: Notes: See KSPGetConvergedReason() for explanation of each value
376: Developer notes: this must match finclude/petscksp.h
378: The string versions of these are KSPConvergedReasons; if you change
379: any of the values here also change them that array of names.
381: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetTolerances()
382: E*/
383: typedef enum {/* converged */
384: KSP_CONVERGED_RTOL_NORMAL = 1,
385: KSP_CONVERGED_ATOL_NORMAL = 9,
386: KSP_CONVERGED_RTOL = 2,
387: KSP_CONVERGED_ATOL = 3,
388: KSP_CONVERGED_ITS = 4,
389: KSP_CONVERGED_CG_NEG_CURVE = 5,
390: KSP_CONVERGED_CG_CONSTRAINED = 6,
391: KSP_CONVERGED_STEP_LENGTH = 7,
392: KSP_CONVERGED_HAPPY_BREAKDOWN = 8,
393: /* diverged */
394: KSP_DIVERGED_NULL = -2,
395: KSP_DIVERGED_ITS = -3,
396: KSP_DIVERGED_DTOL = -4,
397: KSP_DIVERGED_BREAKDOWN = -5,
398: KSP_DIVERGED_BREAKDOWN_BICG = -6,
399: KSP_DIVERGED_NONSYMMETRIC = -7,
400: KSP_DIVERGED_INDEFINITE_PC = -8,
401: KSP_DIVERGED_NAN = -9,
402: KSP_DIVERGED_INDEFINITE_MAT = -10,
403:
404: KSP_CONVERGED_ITERATING = 0} KSPConvergedReason;
407: /*MC
408: KSP_CONVERGED_RTOL - norm(r) <= rtol*norm(b)
410: Level: beginner
412: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
413: for left preconditioning it is the 2-norm of the preconditioned residual, and the
414: 2-norm of the residual for right preconditioning
416: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
418: M*/
420: /*MC
421: KSP_CONVERGED_ATOL - norm(r) <= atol
423: Level: beginner
425: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
426: for left preconditioning it is the 2-norm of the preconditioned residual, and the
427: 2-norm of the residual for right preconditioning
429: Level: beginner
431: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
433: M*/
435: /*MC
436: KSP_DIVERGED_DTOL - norm(r) >= dtol*norm(b)
438: Level: beginner
440: See KSPNormType and KSPSetNormType() for possible norms that may be used. By default
441: for left preconditioning it is the 2-norm of the preconditioned residual, and the
442: 2-norm of the residual for right preconditioning
444: Level: beginner
446: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
448: M*/
450: /*MC
451: KSP_DIVERGED_ITS - Ran out of iterations before any convergence criteria was
452: reached
454: Level: beginner
456: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
458: M*/
460: /*MC
461: KSP_CONVERGED_ITS - Used by the KSPPREONLY solver after the single iteration of
462: the preconditioner is applied. Also used when the KSPSkipConverged() convergence
463: test routine is set in KSP.
466: Level: beginner
469: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
471: M*/
473: /*MC
474: KSP_DIVERGED_BREAKDOWN - A breakdown in the Krylov method was detected so the
475: method could not continue to enlarge the Krylov space. Could be due to a singlular matrix or
476: preconditioner.
478: Level: beginner
480: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
482: M*/
484: /*MC
485: KSP_DIVERGED_BREAKDOWN_BICG - A breakdown in the KSPBICG method was detected so the
486: method could not continue to enlarge the Krylov space.
489: Level: beginner
492: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
494: M*/
496: /*MC
497: KSP_DIVERGED_NONSYMMETRIC - It appears the operator or preconditioner is not
498: symmetric and this Krylov method (KSPCG, KSPMINRES, KSPCR) requires symmetry
500: Level: beginner
502: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
504: M*/
506: /*MC
507: KSP_DIVERGED_INDEFINITE_PC - It appears the preconditioner is indefinite (has both
508: positive and negative eigenvalues) and this Krylov method (KSPCG) requires it to
509: be positive definite
511: Level: beginner
513: Notes: This can happen with the PCICC preconditioner, use -pc_factor_shift_positive_definite to force
514: the PCICC preconditioner to generate a positive definite preconditioner
516: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
518: M*/
520: /*MC
521: KSP_CONVERGED_ITERATING - This flag is returned if you call KSPGetConvergedReason()
522: while the KSPSolve() is still running.
524: Level: beginner
526: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
528: M*/
543: /*E
544: KSPCGType - Determines what type of CG to use
546: Level: beginner
548: .seealso: KSPCGSetType()
549: E*/
550: typedef enum {KSP_CG_SYMMETRIC=0,KSP_CG_HERMITIAN=1} KSPCGType;
588: /* see src/ksp/ksp/interface/iguess.c */
589: typedef struct _p_KSPFischerGuess {PetscInt method,curl,maxl,refcnt;PetscBool monitor;Mat mat; KSP ksp;}* KSPFischerGuess;
617: #endif