Actual source code: petscksp.h

  1: /* $Id: petscksp.h,v 1.107 2001/08/06 21:16:38 bsmith Exp $ */
  2: /*
  3:    Defines the interface functions for the Krylov subspace accelerators.
  4: */
  5: #ifndef __PETSCKSP_H
 7:  #include petscpc.h

  9: /*S
 10:      KSP - Abstract PETSc object that manages all Krylov methods

 12:    Level: beginner

 14:   Concepts: Krylov methods

 16: .seealso:  KSPCreate(), KSPSetType(), KSPType, SNES, TS, PC, SLES
 17: S*/
 18: typedef struct _p_KSP*     KSP;

 20: /*E
 21:     KSPType - String with the name of a PETSc Krylov method or the creation function
 22:        with an optional dynamic library name, for example
 23:        http://www.mcs.anl.gov/petsc/lib.a:mykspcreate()

 25:    Level: beginner

 27: .seealso: KSPSetType(), KSP
 28: E*/
 29: #define KSPRICHARDSON "richardson"
 30: #define KSPCHEBYCHEV  "chebychev"
 31: #define KSPCG         "cg"
 32: #define KSPGMRES      "gmres"
 33: #define KSPTCQMR      "tcqmr"
 34: #define KSPBCGS       "bcgs"
 35: #define KSPCGS        "cgs"
 36: #define KSPTFQMR      "tfqmr"
 37: #define KSPCR         "cr"
 38: #define KSPLSQR       "lsqr"
 39: #define KSPPREONLY    "preonly"
 40: #define KSPQCG        "qcg"
 41: #define KSPBICG       "bicg"
 42: #define KSPFGMRES     "fgmres" 
 43: #define KSPMINRES     "minres"
 44: #define KSPSYMMLQ     "symmlq"
 45: #define KSPLGMRES     "lgmres"
 46: typedef char * KSPType;

 48: /* Logging support */
 49: extern int KSP_COOKIE;
 50: extern int KSP_GMRESOrthogonalization;

 52: EXTERN int KSPCreate(MPI_Comm,KSP *);
 53: EXTERN int KSPSetType(KSP,KSPType);
 54: EXTERN int KSPSetUp(KSP);
 55: EXTERN int KSPSolve(KSP,int *);
 56: EXTERN int KSPSolveTranspose(KSP,int *);
 57: EXTERN int KSPDestroy(KSP);

 59: extern PetscFList KSPList;
 60: EXTERN int KSPRegisterAll(const char[]);
 61: EXTERN int KSPRegisterDestroy(void);

 63: EXTERN int KSPRegister(const char[],const char[],const char[],int(*)(KSP));

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

 68:    Synopsis:
 69:    int KSPRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(KSP))

 71:    Not Collective

 73:    Input Parameters:
 74: +  name_solver - name of a new user-defined solver
 75: .  path - path (either absolute or relative) the library containing this solver
 76: .  name_create - name of routine to create method context
 77: -  routine_create - routine to create method context

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

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

 85:    Sample usage:
 86: .vb
 87:    KSPRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,
 88:                "MySolverCreate",MySolverCreate);
 89: .ve

 91:    Then, your solver can be chosen with the procedural interface via
 92: $     KSPSetType(ksp,"my_solver")
 93:    or at runtime via the option
 94: $     -ksp_type my_solver

 96:    Level: advanced

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

103: .keywords: KSP, register

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

107: M*/
108: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
109: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,0)
110: #else
111: #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,d)
112: #endif

114: EXTERN int KSPGetType(KSP,KSPType *);
115: EXTERN int KSPSetPreconditionerSide(KSP,PCSide);
116: EXTERN int KSPGetPreconditionerSide(KSP,PCSide*);
117: EXTERN int KSPGetTolerances(KSP,PetscReal*,PetscReal*,PetscReal*,int*);
118: EXTERN int KSPSetTolerances(KSP,PetscReal,PetscReal,PetscReal,int);
119: EXTERN int KSPSetInitialGuessNonzero(KSP,PetscTruth);
120: EXTERN int KSPGetInitialGuessNonzero(KSP,PetscTruth *);
121: EXTERN int KSPSetInitialGuessKnoll(KSP,PetscTruth);
122: EXTERN int KSPGetInitialGuessKnoll(KSP,PetscTruth*);
123: EXTERN int KSPSetComputeEigenvalues(KSP,PetscTruth);
124: EXTERN int KSPSetComputeSingularValues(KSP,PetscTruth);
125: EXTERN int KSPSetRhs(KSP,Vec);
126: EXTERN int KSPGetRhs(KSP,Vec *);
127: EXTERN int KSPSetSolution(KSP,Vec);
128: EXTERN int KSPGetSolution(KSP,Vec *);
129: EXTERN int KSPGetResidualNorm(KSP,PetscReal*);
130: EXTERN int KSPGetIterationNumber(KSP,int*);

132: EXTERN int KSPSetPC(KSP,PC);
133: EXTERN int KSPGetPC(KSP,PC*);

135: EXTERN int KSPSetMonitor(KSP,int (*)(KSP,int,PetscReal,void*),void *,int (*)(void*));
136: EXTERN int KSPClearMonitor(KSP);
137: EXTERN int KSPGetMonitorContext(KSP,void **);
138: EXTERN int KSPGetResidualHistory(KSP,PetscReal*[],int *);
139: EXTERN int KSPSetResidualHistory(KSP,PetscReal[],int,PetscTruth);


142: EXTERN int KSPBuildSolution(KSP,Vec,Vec *);
143: EXTERN int KSPBuildResidual(KSP,Vec,Vec,Vec *);

145: EXTERN int KSPRichardsonSetScale(KSP,PetscReal);
146: EXTERN int KSPChebychevSetEigenvalues(KSP,PetscReal,PetscReal);
147: EXTERN int KSPComputeExtremeSingularValues(KSP,PetscReal*,PetscReal*);
148: EXTERN int KSPComputeEigenvalues(KSP,int,PetscReal*,PetscReal*,int *);
149: EXTERN int KSPComputeEigenvaluesExplicitly(KSP,int,PetscReal*,PetscReal*);

151: #define KSPGMRESSetRestart(ksp,r) PetscTryMethod((ksp),KSPGMRESSetRestart_C,(KSP,int),((ksp),(r)))
152: #define KSPGMRESSetHapTol(ksp,tol) PetscTryMethod((ksp),KSPGMRESSetHapTol_C,(KSP,PetscReal),((ksp),(tol)))

154: EXTERN int KSPGMRESSetPreAllocateVectors(KSP);
155: EXTERN int KSPGMRESSetOrthogonalization(KSP,int (*)(KSP,int));
156: EXTERN int KSPGMRESUnmodifiedGramSchmidtOrthogonalization(KSP,int);
157: EXTERN int KSPGMRESModifiedGramSchmidtOrthogonalization(KSP,int);
158: EXTERN int KSPGMRESIROrthogonalization(KSP,int);

160: EXTERN int KSPFGMRESModifyPCNoChange(KSP,int,int,PetscReal,void*);
161: EXTERN int KSPFGMRESModifyPCSLES(KSP,int,int,PetscReal,void*);
162: EXTERN int KSPFGMRESSetModifyPC(KSP,int (*)(KSP,int,int,PetscReal,void*),void*,int(*)(void*));

164: EXTERN int KSPQCGSetTrustRegionRadius(KSP,PetscReal);
165: EXTERN int KSPQCGGetQuadratic(KSP,PetscReal*);
166: EXTERN int KSPQCGGetTrialStepNorm(KSP,PetscReal*);

168: EXTERN int KSPSetFromOptions(KSP);
169: EXTERN int KSPAddOptionsChecker(int (*)(KSP));

171: EXTERN int KSPSingularValueMonitor(KSP,int,PetscReal,void *);
172: EXTERN int KSPDefaultMonitor(KSP,int,PetscReal,void *);
173: EXTERN int KSPTrueMonitor(KSP,int,PetscReal,void *);
174: EXTERN int KSPDefaultSMonitor(KSP,int,PetscReal,void *);
175: EXTERN int KSPVecViewMonitor(KSP,int,PetscReal,void *);
176: EXTERN int KSPGMRESKrylovMonitor(KSP,int,PetscReal,void *);

178: EXTERN int KSPUnwindPreconditioner(KSP,Vec,Vec);
179: EXTERN int KSPDefaultBuildSolution(KSP,Vec,Vec*);
180: EXTERN int KSPDefaultBuildResidual(KSP,Vec,Vec,Vec *);

182: EXTERN int KSPSetOptionsPrefix(KSP,const char[]);
183: EXTERN int KSPAppendOptionsPrefix(KSP,const char[]);
184: EXTERN int KSPGetOptionsPrefix(KSP,char*[]);

186: EXTERN int KSPView(KSP,PetscViewer);

188: /*E
189:     KSPNormType - Norm that is passed in the Krylov convergence
190:        test routines.

192:    Level: advanced

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

196: .seealso: SLESSolve(), KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(),
197:           KSPSetConvergenceTest()
198: E*/
199: typedef enum {KSP_NO_NORM               = 0,
200:               KSP_PRECONDITIONED_NORM   = 1,
201:               KSP_UNPRECONDITIONED_NORM = 2,
202:               KSP_NATURAL_NORM          = 3} KSPNormType;
203: EXTERN int KSPSetNormType(KSP,KSPNormType);

205: /*E
206:     KSPConvergedReason - reason a Krylov method was said to 
207:          have converged or diverged

209:    Level: beginner

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

213: .seealso: SLESSolve(), KSPSolve(), KSPGetConvergedReason()
214: E*/
215: typedef enum {/* converged */
216:               KSP_CONVERGED_RTOL               =  2,
217:               KSP_CONVERGED_ATOL               =  3,
218:               KSP_CONVERGED_ITS                =  4,
219:               KSP_CONVERGED_QCG_NEG_CURVE      =  5,
220:               KSP_CONVERGED_QCG_CONSTRAINED    =  6,
221:               KSP_CONVERGED_STEP_LENGTH        =  7,
222:               /* diverged */
223:               KSP_DIVERGED_ITS                 = -3,
224:               KSP_DIVERGED_DTOL                = -4,
225:               KSP_DIVERGED_BREAKDOWN           = -5,
226:               KSP_DIVERGED_BREAKDOWN_BICG      = -6,
227:               KSP_DIVERGED_NONSYMMETRIC        = -7,
228:               KSP_DIVERGED_INDEFINITE_PC       = -8,
229: 
230:               KSP_CONVERGED_ITERATING          =  0} KSPConvergedReason;

232: EXTERN int KSPSetConvergenceTest(KSP,int (*)(KSP,int,PetscReal,KSPConvergedReason*,void*),void *);
233: EXTERN int KSPGetConvergenceContext(KSP,void **);
234: EXTERN int KSPDefaultConverged(KSP,int,PetscReal,KSPConvergedReason*,void *);
235: EXTERN int KSPSkipConverged(KSP,int,PetscReal,KSPConvergedReason*,void *);
236: EXTERN int KSPGetConvergedReason(KSP,KSPConvergedReason *);

238: EXTERN int KSPComputeExplicitOperator(KSP,Mat *);

240: /*E
241:     KSPCGType - Determines what type of CG to use

243:    Level: beginner

245: .seealso: KSPCGSetType()
246: E*/
247: typedef enum {KSP_CG_SYMMETRIC=1,KSP_CG_HERMITIAN=2} KSPCGType;

249: EXTERN int KSPCGSetType(KSP,KSPCGType);

251: EXTERN int PCPreSolve(PC,KSP);
252: EXTERN int PCPostSolve(PC,KSP);

254: EXTERN int KSPLGMonitorCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
255: EXTERN int KSPLGMonitor(KSP,int,PetscReal,void*);
256: EXTERN int KSPLGMonitorDestroy(PetscDrawLG);
257: EXTERN int KSPLGTrueMonitorCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
258: EXTERN int KSPLGTrueMonitor(KSP,int,PetscReal,void*);
259: EXTERN int KSPLGTrueMonitorDestroy(PetscDrawLG);

261: #endif