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