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 6 #define __PETSCKSP_H 7 #include "petscpc.h" 8 PETSC_EXTERN_CXX_BEGIN 9 10 EXTERN int KSPInitializePackage(const char[]); 11 12 /*S 13 KSP - Abstract PETSc object that manages all Krylov methods 14 15 Level: beginner 16 17 Concepts: Krylov methods 18 19 .seealso: KSPCreate(), KSPSetType(), KSPType, SNES, TS, PC, KSP 20 S*/ 21 typedef struct _p_KSP* KSP; 22 23 /*E 24 KSPType - String with the name of a PETSc Krylov method or the creation function 25 with an optional dynamic library name, for example 26 http://www.mcs.anl.gov/petsc/lib.a:mykspcreate() 27 28 Level: beginner 29 30 .seealso: KSPSetType(), KSP 31 E*/ 32 #define KSPRICHARDSON "richardson" 33 #define KSPCHEBYCHEV "chebychev" 34 #define KSPCG "cg" 35 #define KSPCGNE "cgne" 36 #define KSPGMRES "gmres" 37 #define KSPTCQMR "tcqmr" 38 #define KSPBCGS "bcgs" 39 #define KSPCGS "cgs" 40 #define KSPTFQMR "tfqmr" 41 #define KSPCR "cr" 42 #define KSPLSQR "lsqr" 43 #define KSPPREONLY "preonly" 44 #define KSPQCG "qcg" 45 #define KSPBICG "bicg" 46 #define KSPFGMRES "fgmres" 47 #define KSPMINRES "minres" 48 #define KSPSYMMLQ "symmlq" 49 #define KSPLGMRES "lgmres" 50 #define KSPType char* 51 52 /* Logging support */ 53 extern int KSP_COOKIE; 54 extern int KSP_GMRESOrthogonalization; 55 extern int KSP_SetUp, KSP_Solve; 56 57 EXTERN int KSPCreate(MPI_Comm,KSP *); 58 EXTERN int KSPSetType(KSP,const KSPType); 59 EXTERN int KSPSetUp(KSP); 60 EXTERN int KSPSetUpOnBlocks(KSP); 61 EXTERN int KSPSolve(KSP,Vec,Vec); 62 EXTERN int KSPSolveTranspose(KSP,Vec,Vec); 63 EXTERN int KSPDestroy(KSP); 64 65 extern PetscFList KSPList; 66 EXTERN int KSPRegisterAll(const char[]); 67 EXTERN int KSPRegisterDestroy(void); 68 69 EXTERN int KSPRegister(const char[],const char[],const char[],int(*)(KSP)); 70 71 /*MC 72 KSPRegisterDynamic - Adds a method to the Krylov subspace solver package. 73 74 Synopsis: 75 int KSPRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(KSP)) 76 77 Not Collective 78 79 Input Parameters: 80 + name_solver - name of a new user-defined solver 81 . path - path (either absolute or relative) the library containing this solver 82 . name_create - name of routine to create method context 83 - routine_create - routine to create method context 84 85 Notes: 86 KSPRegisterDynamic() may be called multiple times to add several user-defined solvers. 87 88 If dynamic libraries are used, then the fourth input argument (routine_create) 89 is ignored. 90 91 Sample usage: 92 .vb 93 KSPRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a, 94 "MySolverCreate",MySolverCreate); 95 .ve 96 97 Then, your solver can be chosen with the procedural interface via 98 $ KSPSetType(ksp,"my_solver") 99 or at runtime via the option 100 $ -ksp_type my_solver 101 102 Level: advanced 103 104 Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT}, 105 and others of the form ${any_environmental_variable} occuring in pathname will be 106 replaced with appropriate values. 107 If your function is not being put into a shared library then use KSPRegister() instead 108 109 .keywords: KSP, register 110 111 .seealso: KSPRegisterAll(), KSPRegisterDestroy() 112 113 M*/ 114 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 115 #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,0) 116 #else 117 #define KSPRegisterDynamic(a,b,c,d) KSPRegister(a,b,c,d) 118 #endif 119 120 EXTERN int KSPGetType(KSP,KSPType *); 121 EXTERN int KSPSetPreconditionerSide(KSP,PCSide); 122 EXTERN int KSPGetPreconditionerSide(KSP,PCSide*); 123 EXTERN int KSPGetTolerances(KSP,PetscReal*,PetscReal*,PetscReal*,int*); 124 EXTERN int KSPSetTolerances(KSP,PetscReal,PetscReal,PetscReal,int); 125 EXTERN int KSPSetInitialGuessNonzero(KSP,PetscTruth); 126 EXTERN int KSPGetInitialGuessNonzero(KSP,PetscTruth *); 127 EXTERN int KSPSetInitialGuessKnoll(KSP,PetscTruth); 128 EXTERN int KSPGetInitialGuessKnoll(KSP,PetscTruth*); 129 EXTERN int KSPSetComputeEigenvalues(KSP,PetscTruth); 130 EXTERN int KSPSetComputeSingularValues(KSP,PetscTruth); 131 EXTERN int KSPGetRhs(KSP,Vec *); 132 EXTERN int KSPSetSolution(KSP,Vec); 133 EXTERN int KSPGetSolution(KSP,Vec *); 134 EXTERN int KSPGetResidualNorm(KSP,PetscReal*); 135 EXTERN int KSPGetIterationNumber(KSP,int*); 136 EXTERN int KSPSetNullSpace(KSP,MatNullSpace); 137 EXTERN int KSPGetNullSpace(KSP,MatNullSpace*); 138 139 EXTERN int KSPSetPC(KSP,PC); 140 EXTERN int KSPGetPC(KSP,PC*); 141 142 EXTERN int KSPSetMonitor(KSP,int (*)(KSP,int,PetscReal,void*),void *,int (*)(void*)); 143 EXTERN int KSPClearMonitor(KSP); 144 EXTERN int KSPGetMonitorContext(KSP,void **); 145 EXTERN int KSPGetResidualHistory(KSP,PetscReal*[],int *); 146 EXTERN int KSPSetResidualHistory(KSP,PetscReal[],int,PetscTruth); 147 148 /* not sure where to put this */ 149 EXTERN int PCKSPGetKSP(PC,KSP*); 150 EXTERN int PCBJacobiGetSubKSP(PC,int*,int*,KSP*[]); 151 EXTERN int PCASMGetSubKSP(PC,int*,int*,KSP*[]); 152 153 EXTERN int KSPBuildSolution(KSP,Vec,Vec *); 154 EXTERN int KSPBuildResidual(KSP,Vec,Vec,Vec *); 155 156 EXTERN int KSPRichardsonSetScale(KSP,PetscReal); 157 EXTERN int KSPChebychevSetEigenvalues(KSP,PetscReal,PetscReal); 158 EXTERN int KSPComputeExtremeSingularValues(KSP,PetscReal*,PetscReal*); 159 EXTERN int KSPComputeEigenvalues(KSP,int,PetscReal*,PetscReal*,int *); 160 EXTERN int KSPComputeEigenvaluesExplicitly(KSP,int,PetscReal*,PetscReal*); 161 162 EXTERN int KSPGMRESSetRestart(KSP, int); 163 EXTERN int KSPGMRESSetHapTol(KSP,PetscReal); 164 165 EXTERN int KSPGMRESSetPreAllocateVectors(KSP); 166 EXTERN int KSPGMRESSetOrthogonalization(KSP,int (*)(KSP,int)); 167 EXTERN int KSPGMRESModifiedGramSchmidtOrthogonalization(KSP,int); 168 EXTERN int KSPGMRESClassicalGramSchmidtOrthogonalization(KSP,int); 169 170 EXTERN int KSPLGMRESSetAugDim(KSP,int); 171 EXTERN int KSPLGMRESSetConstant(KSP); 172 173 /*E 174 KSPGMRESCGSRefinementType - How the classical (unmodified) Gram-Schmidt is performed. 175 176 Level: advanced 177 178 .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), 179 KSPGMRESSetCGSRefinementType(), KSPGMRESModifiedGramSchmidtOrthogonalization() 180 181 E*/ 182 typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType; 183 184 /*M 185 KSP_GMRES_CGS_REFINE_NEVER - Just do the classical (unmodified) Gram-Schmidt process 186 187 Level: advanced 188 189 Note: Possible unstable, but the fastest to compute 190 191 .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), 192 KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS, 193 KSPGMRESModifiedGramSchmidtOrthogonalization() 194 M*/ 195 196 /*M 197 KSP_GMRES_CGS_REFINE_IFNEEDED - Do the classical (unmodified) Gram-Schmidt process and one step of 198 iterative refinement if an estimate of the orthogonality of the resulting vectors indicates 199 poor orthogonality. 200 201 Level: advanced 202 203 Note: This is slower than KSP_GMRES_CGS_REFINE_NEVER because it requires an extra norm computation to 204 estimate the orthogonality but is more stable. 205 206 .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), 207 KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_ALWAYS, 208 KSPGMRESModifiedGramSchmidtOrthogonalization() 209 M*/ 210 211 /*M 212 KSP_GMRES_CGS_REFINE_NEVER - Do two steps of the classical (unmodified) Gram-Schmidt process. 213 214 Level: advanced 215 216 Note: This is roughly twice the cost of KSP_GMRES_CGS_REFINE_NEVER because it performs the process twice 217 but it saves the extra norm calculation needed by KSP_GMRES_CGS_REFINE_IFNEEDED. 218 219 You should only use this if you absolutely know that the iterative refinement is needed. 220 221 .seealso: KSPGMRESClassicalGramSchmidtOrthogonalization(), KSPGMRESSetOrthogonalization(), 222 KSPGMRESSetCGSRefinementType(), KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS, 223 KSPGMRESModifiedGramSchmidtOrthogonalization() 224 M*/ 225 226 EXTERN int KSPGMRESSetCGSRefinementType(KSP,KSPGMRESCGSRefinementType); 227 228 EXTERN int KSPFGMRESModifyPCNoChange(KSP,int,int,PetscReal,void*); 229 EXTERN int KSPFGMRESModifyPCKSP(KSP,int,int,PetscReal,void*); 230 EXTERN int KSPFGMRESSetModifyPC(KSP,int (*)(KSP,int,int,PetscReal,void*),void*,int(*)(void*)); 231 232 EXTERN int KSPQCGSetTrustRegionRadius(KSP,PetscReal); 233 EXTERN int KSPQCGGetQuadratic(KSP,PetscReal*); 234 EXTERN int KSPQCGGetTrialStepNorm(KSP,PetscReal*); 235 236 EXTERN int KSPSetFromOptions(KSP); 237 EXTERN int KSPAddOptionsChecker(int (*)(KSP)); 238 239 EXTERN int KSPSingularValueMonitor(KSP,int,PetscReal,void *); 240 EXTERN int KSPDefaultMonitor(KSP,int,PetscReal,void *); 241 EXTERN int KSPTrueMonitor(KSP,int,PetscReal,void *); 242 EXTERN int KSPDefaultSMonitor(KSP,int,PetscReal,void *); 243 EXTERN int KSPVecViewMonitor(KSP,int,PetscReal,void *); 244 EXTERN int KSPGMRESKrylovMonitor(KSP,int,PetscReal,void *); 245 246 EXTERN int KSPUnwindPreconditioner(KSP,Vec,Vec); 247 EXTERN int KSPDefaultBuildSolution(KSP,Vec,Vec*); 248 EXTERN int KSPDefaultBuildResidual(KSP,Vec,Vec,Vec *); 249 250 EXTERN int KSPSetOperators(KSP,Mat,Mat,MatStructure); 251 EXTERN int KSPSetOptionsPrefix(KSP,const char[]); 252 EXTERN int KSPAppendOptionsPrefix(KSP,const char[]); 253 EXTERN int KSPGetOptionsPrefix(KSP,char*[]); 254 255 EXTERN int KSPSetDiagonalScale(KSP,PetscTruth); 256 EXTERN int KSPGetDiagonalScale(KSP,PetscTruth*); 257 EXTERN int KSPSetDiagonalScaleFix(KSP,PetscTruth); 258 EXTERN int KSPGetDiagonalScaleFix(KSP,PetscTruth*); 259 260 EXTERN int KSPView(KSP,PetscViewer); 261 262 /*E 263 KSPNormType - Norm that is passed in the Krylov convergence 264 test routines. 265 266 Level: advanced 267 268 Notes: this must match finclude/petscksp.h 269 270 .seealso: KSPSolve(), KSPGetConvergedReason(), KSPSetNormType(), 271 KSPSetConvergenceTest() 272 E*/ 273 typedef enum {KSP_NO_NORM = 0, 274 KSP_PRECONDITIONED_NORM = 1, 275 KSP_UNPRECONDITIONED_NORM = 2, 276 KSP_NATURAL_NORM = 3} KSPNormType; 277 278 /*M 279 KSP_NO_NORM - Do not compute a norm during the Krylov process. This will 280 possibly save some computation but means the convergence test cannot 281 be based on a norm of a residual etc. 282 283 Level: advanced 284 285 Note: Some Krylov methods need to compute a residual norm and then this is ignored 286 287 .seealso: KSPNormType, KSPSetNormType(), KSP_PRECONDITIONED_NORM, KSP_UNPRECONDITIONED_NORM, KSP_NATURAL_NORM 288 M*/ 289 290 /*M 291 KSP_PRECONDITIONED_NORM - Compute the norm of the preconditioned residual and pass that to the 292 convergence test routine. 293 294 Level: advanced 295 296 .seealso: KSPNormType, KSPSetNormType(), KSP_NO_NORM, KSP_UNPRECONDITIONED_NORM, KSP_NATURAL_NORM, KSPSetConvergenceTest() 297 M*/ 298 299 /*M 300 KSP_UNPRECONDITIONED_NORM - Compute the norm of the true residual (b - A*x) and pass that to the 301 convergence test routine. 302 303 Level: advanced 304 305 .seealso: KSPNormType, KSPSetNormType(), KSP_NO_NORM, KSP_PRECONDITIONED_NORM, KSP_NATURAL_NORM, KSPSetConvergenceTest() 306 M*/ 307 308 /*M 309 KSP_NATURAL_NORM - Compute the 'natural norm' of residual sqrt((b - A*x)*B*(b - A*x)) and pass that to the 310 convergence test routine. 311 312 Level: advanced 313 314 .seealso: KSPNormType, KSPSetNormType(), KSP_NO_NORM, KSP_PRECONDITIONED_NORM, KSP_UNPRECONDITIONED_NORM, KSPSetConvergenceTest() 315 M*/ 316 317 EXTERN int KSPSetNormType(KSP,KSPNormType); 318 319 /*E 320 KSPConvergedReason - reason a Krylov method was said to 321 have converged or diverged 322 323 Level: beginner 324 325 Notes: this must match finclude/petscksp.h 326 327 Developer note: The string versions of these are in 328 src/ksp/ksp/interface/itfunc.c called convergedreasons. 329 If these enums are changed you much change those. 330 331 .seealso: KSPSolve(), KSPGetConvergedReason() 332 E*/ 333 typedef enum {/* converged */ 334 KSP_CONVERGED_RTOL = 2, 335 KSP_CONVERGED_ATOL = 3, 336 KSP_CONVERGED_ITS = 4, 337 KSP_CONVERGED_QCG_NEG_CURVE = 5, 338 KSP_CONVERGED_QCG_CONSTRAINED = 6, 339 KSP_CONVERGED_STEP_LENGTH = 7, 340 /* diverged */ 341 KSP_DIVERGED_ITS = -3, 342 KSP_DIVERGED_DTOL = -4, 343 KSP_DIVERGED_BREAKDOWN = -5, 344 KSP_DIVERGED_BREAKDOWN_BICG = -6, 345 KSP_DIVERGED_NONSYMMETRIC = -7, 346 KSP_DIVERGED_INDEFINITE_PC = -8, 347 348 KSP_CONVERGED_ITERATING = 0} KSPConvergedReason; 349 350 EXTERN int KSPSetConvergenceTest(KSP,int (*)(KSP,int,PetscReal,KSPConvergedReason*,void*),void *); 351 EXTERN int KSPGetConvergenceContext(KSP,void **); 352 EXTERN int KSPDefaultConverged(KSP,int,PetscReal,KSPConvergedReason*,void *); 353 EXTERN int KSPSkipConverged(KSP,int,PetscReal,KSPConvergedReason*,void *); 354 EXTERN int KSPGetConvergedReason(KSP,KSPConvergedReason *); 355 356 EXTERN int KSPComputeExplicitOperator(KSP,Mat *); 357 358 /*E 359 KSPCGType - Determines what type of CG to use 360 361 Level: beginner 362 363 .seealso: KSPCGSetType() 364 E*/ 365 typedef enum {KSP_CG_SYMMETRIC=1,KSP_CG_HERMITIAN=2} KSPCGType; 366 367 EXTERN int KSPCGSetType(KSP,KSPCGType); 368 369 EXTERN int PCPreSolve(PC,KSP); 370 EXTERN int PCPostSolve(PC,KSP); 371 372 EXTERN int KSPLGMonitorCreate(const char[],const char[],int,int,int,int,PetscDrawLG*); 373 EXTERN int KSPLGMonitor(KSP,int,PetscReal,void*); 374 EXTERN int KSPLGMonitorDestroy(PetscDrawLG); 375 EXTERN int KSPLGTrueMonitorCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*); 376 EXTERN int KSPLGTrueMonitor(KSP,int,PetscReal,void*); 377 EXTERN int KSPLGTrueMonitorDestroy(PetscDrawLG); 378 379 PETSC_EXTERN_CXX_END 380 #endif 381