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

  9: EXTERN PetscErrorCode  KSPInitializePackage(const char[]);

 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: /*E
 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: E*/
 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 KSPTCQMR      "tcqmr"
 43: #define KSPBCGS       "bcgs"
 44: #define KSPIBCGS        "ibcgs"
 45: #define KSPBCGSL        "bcgsl"
 46: #define KSPCGS        "cgs"
 47: #define KSPTFQMR      "tfqmr"
 48: #define KSPCR         "cr"
 49: #define KSPLSQR       "lsqr"
 50: #define KSPPREONLY    "preonly"
 51: #define KSPQCG        "qcg"
 52: #define KSPBICG       "bicg"
 53: #define KSPMINRES     "minres"
 54: #define KSPSYMMLQ     "symmlq"
 55: #define KSPLCD        "lcd"
 56: #define KSPPYTHON     "python"
 57: #define KSPBROYDEN    "broyden"
 58: #define KSPGCR        "gcr"

 60: /* Logging support */

 63: EXTERN PetscErrorCode  KSPCreate(MPI_Comm,KSP *);
 64: EXTERN PetscErrorCode  KSPSetType(KSP,const KSPType);
 65: EXTERN PetscErrorCode  KSPSetUp(KSP);
 66: EXTERN PetscErrorCode  KSPSetUpOnBlocks(KSP);
 67: EXTERN PetscErrorCode  KSPSolve(KSP,Vec,Vec);
 68: EXTERN PetscErrorCode  KSPSolveTranspose(KSP,Vec,Vec);
 69: EXTERN PetscErrorCode  KSPDestroy(KSP);

 73: EXTERN PetscErrorCode  KSPRegisterAll(const char[]);
 74: EXTERN PetscErrorCode  KSPRegisterDestroy(void);
 75: EXTERN PetscErrorCode  KSPRegister(const char[],const char[],const char[],PetscErrorCode (*)(KSP));

 77: /*MC
 78:    KSPRegisterDynamic - Adds a method to the Krylov subspace solver package.

 80:    Synopsis:
 81:    PetscErrorCode KSPRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(KSP))

 83:    Not Collective

 85:    Input Parameters:
 86: +  name_solver - name of a new user-defined solver
 87: .  path - path (either absolute or relative) the library containing this solver
 88: .  name_create - name of routine to create method context
 89: -  routine_create - routine to create method context

 91:    Notes:
 92:    KSPRegisterDynamic() may be called multiple times to add several user-defined solvers.

 94:    If dynamic libraries are used, then the fourth input argument (routine_create)
 95:    is ignored.

 97:    Sample usage:
 98: .vb
 99:    KSPRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,
100:                "MySolverCreate",MySolverCreate);
101: .ve

103:    Then, your solver can be chosen with the procedural interface via
104: $     KSPSetType(ksp,"my_solver")
105:    or at runtime via the option
106: $     -ksp_type my_solver

108:    Level: advanced

110:    Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
111:           and others of the form ${any_environmental_variable} occuring in pathname will be 
112:           replaced with appropriate values.
113:          If your function is not being put into a shared library then use KSPRegister() instead

115: .keywords: KSP, register

117: .seealso: KSPRegisterAll(), KSPRegisterDestroy()

119: M*/
120: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
121: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,0)
122: #else
123: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,d)
124: #endif

126: EXTERN PetscErrorCode  KSPGetType(KSP,const KSPType *);
127: EXTERN PetscErrorCode  KSPSetPreconditionerSide(KSP,PCSide);
128: EXTERN PetscErrorCode  KSPGetPreconditionerSide(KSP,PCSide*);
129: EXTERN PetscErrorCode  KSPGetTolerances(KSP,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
130: EXTERN PetscErrorCode  KSPSetTolerances(KSP,PetscReal,PetscReal,PetscReal,PetscInt);
131: EXTERN PetscErrorCode  KSPSetInitialGuessNonzero(KSP,PetscTruth);
132: EXTERN PetscErrorCode  KSPGetInitialGuessNonzero(KSP,PetscTruth *);
133: EXTERN PetscErrorCode  KSPSetInitialGuessKnoll(KSP,PetscTruth);
134: EXTERN PetscErrorCode  KSPGetInitialGuessKnoll(KSP,PetscTruth*);
135: EXTERN PetscErrorCode  KSPGetComputeEigenvalues(KSP,PetscTruth*);
136: EXTERN PetscErrorCode  KSPSetComputeEigenvalues(KSP,PetscTruth);
137: EXTERN PetscErrorCode  KSPGetComputeSingularValues(KSP,PetscTruth*);
138: EXTERN PetscErrorCode  KSPSetComputeSingularValues(KSP,PetscTruth);
139: EXTERN PetscErrorCode  KSPGetRhs(KSP,Vec *);
140: EXTERN PetscErrorCode  KSPGetSolution(KSP,Vec *);
141: EXTERN PetscErrorCode  KSPGetResidualNorm(KSP,PetscReal*);
142: EXTERN PetscErrorCode  KSPGetIterationNumber(KSP,PetscInt*);
143: EXTERN PetscErrorCode  KSPSetNullSpace(KSP,MatNullSpace);
144: EXTERN PetscErrorCode  KSPGetNullSpace(KSP,MatNullSpace*);
145: EXTERN PetscErrorCode  KSPGetVecs(KSP,PetscInt,Vec**,PetscInt,Vec**);

147: EXTERN PetscErrorCode  KSPSetPC(KSP,PC);
148: EXTERN PetscErrorCode  KSPGetPC(KSP,PC*);

150: EXTERN PetscErrorCode  KSPMonitorSet(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
151: EXTERN PetscErrorCode  KSPMonitorCancel(KSP);
152: EXTERN PetscErrorCode  KSPGetMonitorContext(KSP,void **);
153: EXTERN PetscErrorCode  KSPGetResidualHistory(KSP,PetscReal*[],PetscInt *);
154: EXTERN PetscErrorCode  KSPSetResidualHistory(KSP,PetscReal[],PetscInt,PetscTruth);

156: /* not sure where to put this */
157: EXTERN PetscErrorCode  PCKSPGetKSP(PC,KSP*);
158: EXTERN PetscErrorCode  PCBJacobiGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
159: EXTERN PetscErrorCode  PCASMGetSubKSP(PC,PetscInt*,PetscInt*,KSP*[]);
160: EXTERN PetscErrorCode  PCFieldSplitGetSubKSP(PC,PetscInt*,KSP*[]);

162: EXTERN PetscErrorCode  PCGalerkinGetKSP(PC,KSP *);

164: EXTERN PetscErrorCode  KSPBuildSolution(KSP,Vec,Vec *);
165: EXTERN PetscErrorCode  KSPBuildResidual(KSP,Vec,Vec,Vec *);

167: EXTERN PetscErrorCode  KSPRichardsonSetScale(KSP,PetscReal);
168: EXTERN PetscErrorCode  KSPChebychevSetEigenvalues(KSP,PetscReal,PetscReal);
169: EXTERN PetscErrorCode  KSPComputeExtremeSingularValues(KSP,PetscReal*,PetscReal*);
170: EXTERN PetscErrorCode  KSPComputeEigenvalues(KSP,PetscInt,PetscReal*,PetscReal*,PetscInt *);
171: EXTERN PetscErrorCode  KSPComputeEigenvaluesExplicitly(KSP,PetscInt,PetscReal*,PetscReal*);

173: EXTERN PetscErrorCode  KSPGMRESSetRestart(KSP, PetscInt);
174: EXTERN PetscErrorCode  KSPGMRESSetHapTol(KSP,PetscReal);

176: EXTERN PetscErrorCode  KSPGMRESSetPreAllocateVectors(KSP);
177: EXTERN PetscErrorCode  KSPGMRESSetOrthogonalization(KSP,PetscErrorCode (*)(KSP,PetscInt));
178: EXTERN PetscErrorCode  KSPGMRESModifiedGramSchmidtOrthogonalization(KSP,PetscInt);
179: EXTERN PetscErrorCode  KSPGMRESClassicalGramSchmidtOrthogonalization(KSP,PetscInt);

181: EXTERN PetscErrorCode  KSPLGMRESSetAugDim(KSP,PetscInt);
182: EXTERN PetscErrorCode  KSPLGMRESSetConstant(KSP);

184: EXTERN PetscErrorCode  KSPGCRSetRestart(KSP,PetscInt);
185: EXTERN PetscErrorCode  KSPGCRSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));

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

190:    Level: advanced

192: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(),
193:           KSPGMRESSetCGSRefinementType(), KSPGMRESModifiedGramSchmidtOrthogonalization()

195: E*/
196: typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType;
198: /*MC
199:     KSP_GMRES_CGS_REFINE_NEVER - Just do the classical (unmodified) Gram-Schmidt process

201:    Level: advanced

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

205: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(),
206:           KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
207:           KSPGMRESModifiedGramSchmidtOrthogonalization()
208: M*/

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

215:    Level: advanced

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

220: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(),
221:           KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_ALWAYS,
222:           KSPGMRESModifiedGramSchmidtOrthogonalization()
223: M*/

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

228:    Level: advanced

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

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

235: .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(),
236:           KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS,
237:           KSPGMRESModifiedGramSchmidtOrthogonalization()
238: M*/

240: EXTERN PetscErrorCode  KSPGMRESSetCGSRefinementType(KSP,KSPGMRESCGSRefinementType);

242: EXTERN PetscErrorCode  KSPFGMRESModifyPCNoChange(KSP,PetscInt,PetscInt,PetscReal,void*);
243: EXTERN PetscErrorCode  KSPFGMRESModifyPCKSP(KSP,PetscInt,PetscInt,PetscReal,void*);
244: EXTERN PetscErrorCode  KSPFGMRESSetModifyPC(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscInt,PetscReal,void*),void*,PetscErrorCode(*)(void*));

246: EXTERN PetscErrorCode  KSPQCGSetTrustRegionRadius(KSP,PetscReal);
247: EXTERN PetscErrorCode  KSPQCGGetQuadratic(KSP,PetscReal*);
248: EXTERN PetscErrorCode  KSPQCGGetTrialStepNorm(KSP,PetscReal*);

250: EXTERN PetscErrorCode  KSPBCGSLSetXRes(KSP,PetscReal);
251: EXTERN PetscErrorCode  KSPBCGSLSetPol(KSP,PetscTruth);
252: EXTERN PetscErrorCode  KSPBCGSLSetEll(KSP,int);

254: EXTERN PetscErrorCode  KSPSetFromOptions(KSP);
255: EXTERN PetscErrorCode  KSPAddOptionsChecker(PetscErrorCode (*)(KSP));

257: EXTERN PetscErrorCode  KSPMonitorSingularValue(KSP,PetscInt,PetscReal,void *);
258: EXTERN PetscErrorCode  KSPMonitorDefault(KSP,PetscInt,PetscReal,void *);
259: EXTERN PetscErrorCode  KSPMonitorDefaultLSQR(KSP,PetscInt,PetscReal,void *);
260: EXTERN PetscErrorCode  KSPMonitorRange(KSP,PetscInt,PetscReal,void *);
261: EXTERN PetscErrorCode  KSPMonitorTrueResidualNorm(KSP,PetscInt,PetscReal,void *);
262: EXTERN PetscErrorCode  KSPMonitorDefaultShort(KSP,PetscInt,PetscReal,void *);
263: EXTERN PetscErrorCode  KSPMonitorSolution(KSP,PetscInt,PetscReal,void *);
264: EXTERN PetscErrorCode  KSPGMRESMonitorKrylov(KSP,PetscInt,PetscReal,void *);

266: EXTERN PetscErrorCode  KSPUnwindPreconditioner(KSP,Vec,Vec);
267: EXTERN PetscErrorCode  KSPDefaultBuildSolution(KSP,Vec,Vec*);
268: EXTERN PetscErrorCode  KSPDefaultBuildResidual(KSP,Vec,Vec,Vec *);
269: EXTERN PetscErrorCode  KSPInitialResidual(KSP,Vec,Vec,Vec,Vec,Vec);

271: EXTERN PetscErrorCode  KSPSetOperators(KSP,Mat,Mat,MatStructure);
272: EXTERN PetscErrorCode  KSPGetOperators(KSP,Mat*,Mat*,MatStructure*);
273: EXTERN PetscErrorCode  KSPGetOperatorsSet(KSP,PetscTruth*,PetscTruth*);
274: EXTERN PetscErrorCode  KSPSetOptionsPrefix(KSP,const char[]);
275: EXTERN PetscErrorCode  KSPAppendOptionsPrefix(KSP,const char[]);
276: EXTERN PetscErrorCode  KSPGetOptionsPrefix(KSP,const char*[]);

278: EXTERN PetscErrorCode  KSPSetDiagonalScale(KSP,PetscTruth);
279: EXTERN PetscErrorCode  KSPGetDiagonalScale(KSP,PetscTruth*);
280: EXTERN PetscErrorCode  KSPSetDiagonalScaleFix(KSP,PetscTruth);
281: EXTERN PetscErrorCode  KSPGetDiagonalScaleFix(KSP,PetscTruth*);

283: EXTERN PetscErrorCode  KSPView(KSP,PetscViewer);

285: EXTERN PetscErrorCode  KSPLSQRSetStandardErrorVec(KSP,Vec);
286: EXTERN PetscErrorCode  KSPLSQRGetStandardErrorVec(KSP,Vec*);

288: /*E
289:     KSPNormType - Norm that is passed in the Krylov convergence
290:        test routines.

292:    Level: advanced

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

297:    Notes: this must match finclude/petscksp.h 

299: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(),
300:           KSPSetConvergenceTest(), KSPSetPreconditionerSide()
301: E*/
302: typedef enum {KSP_NORM_NO = 0,KSP_NORM_PRECONDITIONED = 1,KSP_NORM_UNPRECONDITIONED = 2,KSP_NORM_NATURAL = 3} KSPNormType;
304: /*MC
305:     KSP_NORM_NO - Do not compute a norm during the Krylov process. This will 
306:           possibly save some computation but means the convergence test cannot
307:           be based on a norm of a residual etc.

309:    Level: advanced

311:     Note: Some Krylov methods need to compute a residual norm and then this option is ignored

313: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL
314: M*/

316: /*MC
317:     KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual and pass that to the 
318:        convergence test routine.

320:    Level: advanced

322: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NO, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
323: M*/

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

329:    Level: advanced

331: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NO, KSP_NORM_PRECONDITIONED, KSP_NORM_NATURAL, KSPSetConvergenceTest()
332: M*/

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

338:    Level: advanced

340: .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_NO, KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSPSetConvergenceTest()
341: M*/

343: EXTERN PetscErrorCode  KSPSetNormType(KSP,KSPNormType);
344: EXTERN PetscErrorCode  KSPGetNormType(KSP,KSPNormType*);
345: EXTERN PetscErrorCode  KSPSetCheckNormIteration(KSP,PetscInt);
346: EXTERN PetscErrorCode  KSPSetLagNorm(KSP,PetscTruth);

348: /*E
349:     KSPConvergedReason - reason a Krylov method was said to 
350:          have converged or diverged

352:    Level: beginner

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

356:    Developer notes: this must match finclude/petscksp.h 

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

361: .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetTolerances()
362: E*/
363: typedef enum {/* converged */
364:               KSP_CONVERGED_RTOL               =  2,
365:               KSP_CONVERGED_ATOL               =  3,
366:               KSP_CONVERGED_ITS                =  4,
367:               KSP_CONVERGED_CG_NEG_CURVE       =  5,
368:               KSP_CONVERGED_CG_CONSTRAINED     =  6,
369:               KSP_CONVERGED_STEP_LENGTH        =  7,
370:               KSP_CONVERGED_HAPPY_BREAKDOWN    =  8,
371:               /* diverged */
372:               KSP_DIVERGED_NULL                = -2,
373:               KSP_DIVERGED_ITS                 = -3,
374:               KSP_DIVERGED_DTOL                = -4,
375:               KSP_DIVERGED_BREAKDOWN           = -5,
376:               KSP_DIVERGED_BREAKDOWN_BICG      = -6,
377:               KSP_DIVERGED_NONSYMMETRIC        = -7,
378:               KSP_DIVERGED_INDEFINITE_PC       = -8,
379:               KSP_DIVERGED_NAN                 = -9,
380:               KSP_DIVERGED_INDEFINITE_MAT      = -10,
381: 
382:               KSP_CONVERGED_ITERATING          =  0} KSPConvergedReason;

385: /*MC
386:      KSP_CONVERGED_RTOL - norm(r) <= rtol*norm(b)

388:    Level: beginner

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

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

396: M*/

398: /*MC
399:      KSP_CONVERGED_ATOL - norm(r) <= atol

401:    Level: beginner

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

407:    Level: beginner

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

411: M*/

413: /*MC
414:      KSP_DIVERGED_DTOL - norm(r) >= dtol*norm(b)

416:    Level: beginner

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

422:    Level: beginner

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

426: M*/

428: /*MC
429:      KSP_DIVERGED_ITS - Ran out of iterations before any convergence criteria was 
430:       reached

432:    Level: beginner

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

436: M*/

438: /*MC
439:      KSP_CONVERGED_ITS - Used by the KSPPREONLY solver after the single iteration of 
440:            the preconditioner is applied. Also used when the KSPSkipConverged() convergence 
441:            test routine is set in KSP.


444:    Level: beginner


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

449: M*/

451: /*MC
452:      KSP_DIVERGED_BREAKDOWN - A breakdown in the Krylov method was detected so the
453:           method could not continue to enlarge the Krylov space.

455:    Level: beginner

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

459: M*/

461: /*MC
462:      KSP_DIVERGED_BREAKDOWN_BICG - A breakdown in the KSPBICG method was detected so the
463:           method could not continue to enlarge the Krylov space.


466:    Level: beginner


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

471: M*/

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

477:    Level: beginner

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

481: M*/

483: /*MC
484:      KSP_DIVERGED_INDEFINITE_PC - It appears the preconditioner is indefinite (has both
485:         positive and negative eigenvalues) and this Krylov method (KSPCG) requires it to
486:         be positive definite

488:    Level: beginner

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

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

495: M*/

497: /*MC
498:      KSP_CONVERGED_ITERATING - This flag is returned if you call KSPGetConvergedReason()
499:         while the KSPSolve() is still running.

501:    Level: beginner

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

505: M*/

507: EXTERN PetscErrorCode  KSPSetConvergenceTest(KSP,PetscErrorCode (*)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *,PetscErrorCode (*)(void*));
508: EXTERN PetscErrorCode  KSPGetConvergenceContext(KSP,void **);
509: EXTERN PetscErrorCode  KSPDefaultConverged(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
510: EXTERN PetscErrorCode  KSPConvergedLSQR(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
511: EXTERN PetscErrorCode  KSPDefaultConvergedDestroy(void *);
512: EXTERN PetscErrorCode  KSPDefaultConvergedCreate(void **);
513: EXTERN PetscErrorCode  KSPDefaultConvergedSetUIRNorm(KSP);
514: EXTERN PetscErrorCode  KSPDefaultConvergedSetUMIRNorm(KSP);
515: EXTERN PetscErrorCode  KSPSkipConverged(KSP,PetscInt,PetscReal,KSPConvergedReason*,void *);
516: EXTERN PetscErrorCode  KSPGetConvergedReason(KSP,KSPConvergedReason *);

518: EXTERN PetscErrorCode  KSPComputeExplicitOperator(KSP,Mat *);

520: /*E
521:     KSPCGType - Determines what type of CG to use

523:    Level: beginner

525: .seealso: KSPCGSetType()
526: E*/
527: typedef enum {KSP_CG_SYMMETRIC=0,KSP_CG_HERMITIAN=1} KSPCGType;

530: EXTERN PetscErrorCode  KSPCGSetType(KSP,KSPCGType);
531: EXTERN PetscErrorCode  KSPCGUseSingleReduction(KSP,PetscTruth);

533: EXTERN PetscErrorCode  KSPNASHSetRadius(KSP,PetscReal);
534: EXTERN PetscErrorCode  KSPNASHGetNormD(KSP,PetscReal *);
535: EXTERN PetscErrorCode  KSPNASHGetObjFcn(KSP,PetscReal *);

537: EXTERN PetscErrorCode  KSPSTCGSetRadius(KSP,PetscReal);
538: EXTERN PetscErrorCode  KSPSTCGGetNormD(KSP,PetscReal *);
539: EXTERN PetscErrorCode  KSPSTCGGetObjFcn(KSP,PetscReal *);

541: EXTERN PetscErrorCode  KSPGLTRSetRadius(KSP,PetscReal);
542: EXTERN PetscErrorCode  KSPGLTRGetNormD(KSP,PetscReal *);
543: EXTERN PetscErrorCode  KSPGLTRGetObjFcn(KSP,PetscReal *);
544: EXTERN PetscErrorCode  KSPGLTRGetMinEig(KSP,PetscReal *);
545: EXTERN PetscErrorCode  KSPGLTRGetLambda(KSP,PetscReal *);

547: EXTERN PetscErrorCode  KSPPythonSetType(KSP,const char[]);

549: EXTERN PetscErrorCode  PCPreSolve(PC,KSP);
550: EXTERN PetscErrorCode  PCPostSolve(PC,KSP);

552: EXTERN PetscErrorCode  KSPMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
553: EXTERN PetscErrorCode  KSPMonitorLG(KSP,PetscInt,PetscReal,void*);
554: EXTERN PetscErrorCode  KSPMonitorLGDestroy(PetscDrawLG);
555: EXTERN PetscErrorCode  KSPMonitorLGTrueResidualNormCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
556: EXTERN PetscErrorCode  KSPMonitorLGTrueResidualNorm(KSP,PetscInt,PetscReal,void*);
557: EXTERN PetscErrorCode  KSPMonitorLGTrueResidualNormDestroy(PetscDrawLG);
558: EXTERN PetscErrorCode  KSPMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
559: EXTERN PetscErrorCode  KSPMonitorLGRange(KSP,PetscInt,PetscReal,void*);
560: EXTERN PetscErrorCode  KSPMonitorLGRangeDestroy(PetscDrawLG);

562: EXTERN PetscErrorCode  PCShellSetPreSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));
563: EXTERN PetscErrorCode  PCShellSetPostSolve(PC,PetscErrorCode (*)(PC,KSP,Vec,Vec));

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

568: EXTERN PetscErrorCode  KSPFischerGuessCreate(KSP,PetscInt,PetscInt,KSPFischerGuess*);
569: EXTERN PetscErrorCode  KSPFischerGuessDestroy(KSPFischerGuess);
570: EXTERN PetscErrorCode  KSPFischerGuessReset(KSPFischerGuess);
571: EXTERN PetscErrorCode  KSPFischerGuessUpdate(KSPFischerGuess,Vec);
572: EXTERN PetscErrorCode  KSPFischerGuessFormGuess(KSPFischerGuess,Vec,Vec);
573: EXTERN PetscErrorCode  KSPFischerGuessSetFromOptions(KSPFischerGuess);

575: EXTERN PetscErrorCode  KSPSetUseFischerGuess(KSP,PetscInt,PetscInt);
576: EXTERN PetscErrorCode  KSPSetFischerGuess(KSP,KSPFischerGuess);
577: EXTERN PetscErrorCode  KSPGetFischerGuess(KSP,KSPFischerGuess*);

579: EXTERN PetscErrorCode  MatCreateSchurComplement(Mat,Mat,Mat,Mat,Mat,Mat*);
580: EXTERN PetscErrorCode  MatSchurComplementGetKSP(Mat,KSP*);
581: EXTERN PetscErrorCode  MatSchurComplementUpdate(Mat,Mat,Mat,Mat,Mat,Mat,MatStructure);
582: EXTERN PetscErrorCode  MatSchurComplementGetSubmatrices(Mat,Mat*,Mat*,Mat*,Mat*,Mat*);
583: EXTERN PetscErrorCode  MatGetSchurComplement(Mat,IS,IS,IS,IS,MatReuse,Mat *,MatReuse,Mat *);

586: #endif