Actual source code: petscpc.h

  1: /*
  2:       Preconditioner module. 
  3: */
 6:  #include petscmat.h

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

 11: /*
 12:     PCList contains the list of preconditioners currently registered
 13:    These are added with the PCRegisterDynamic() macro
 14: */

 17: /*S
 18:      PC - Abstract PETSc object that manages all preconditioners

 20:    Level: beginner

 22:   Concepts: preconditioners

 24: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types)
 25: S*/
 26: typedef struct _p_PC* PC;

 28: /*E
 29:     PCType - String with the name of a PETSc preconditioner method or the creation function
 30:        with an optional dynamic library name, for example
 31:        http://www.mcs.anl.gov/petsc/lib.a:mypccreate()

 33:    Level: beginner

 35:    Notes: Click on the links below to see details on a particular solver

 37: .seealso: PCSetType(), PC, PCCreate()
 38: E*/
 39: #define PCType char*
 40: #define PCNONE            "none"
 41: #define PCJACOBI          "jacobi"
 42: #define PCSOR             "sor"
 43: #define PCLU              "lu"
 44: #define PCSHELL           "shell"
 45: #define PCBJACOBI         "bjacobi"
 46: #define PCMG              "mg"
 47: #define PCEISENSTAT       "eisenstat"
 48: #define PCILU             "ilu"
 49: #define PCICC             "icc"
 50: #define PCASM             "asm"
 51: #define PCKSP             "ksp"
 52: #define PCCOMPOSITE       "composite"
 53: #define PCREDUNDANT       "redundant"
 54: #define PCSPAI            "spai"
 55: #define PCNN              "nn"
 56: #define PCCHOLESKY        "cholesky"
 57: #define PCPBJACOBI        "pbjacobi"
 58: #define PCMAT             "mat"
 59: #define PCHYPRE           "hypre"
 60: #define PCFIELDSPLIT      "fieldsplit"
 61: #define PCTFS             "tfs"
 62: #define PCML              "ml"
 63: #define PCPROMETHEUS      "prometheus"
 64: #define PCGALERKIN        "galerkin"
 65: #define PCEXOTIC          "exotic"
 66: #define PCOPENMP          "openmp"
 67: #define PCSUPPORTGRAPH    "supportgraph"
 68: #define PCASA             "asa"
 69: #define PCCP              "cp"
 70: #define PCBFBT            "bfbt"
 71: #define PCLSC             "lsc"
 72: #define PCPYTHON          "python"
 73: #define PCPFMG            "pfmg"
 74: #define PCSYSPFMG         "syspfmg"
 75: #define PCREDISTRIBUTE    "redistribute"

 77: /* Logging support */

 80: /*E
 81:     PCSide - If the preconditioner is to be applied to the left, right
 82:      or symmetrically around the operator.

 84:    Level: beginner

 86: .seealso: 
 87: E*/
 88: typedef enum { PC_LEFT,PC_RIGHT,PC_SYMMETRIC } PCSide;

 91: EXTERN PetscErrorCode  PCCreate(MPI_Comm,PC*);
 92: EXTERN PetscErrorCode  PCSetType(PC,const PCType);
 93: EXTERN PetscErrorCode  PCSetUp(PC);
 94: EXTERN PetscErrorCode  PCSetUpOnBlocks(PC);
 95: EXTERN PetscErrorCode  PCApply(PC,Vec,Vec);
 96: EXTERN PetscErrorCode  PCApplySymmetricLeft(PC,Vec,Vec);
 97: EXTERN PetscErrorCode  PCApplySymmetricRight(PC,Vec,Vec);
 98: EXTERN PetscErrorCode  PCApplyBAorAB(PC,PCSide,Vec,Vec,Vec);
 99: EXTERN PetscErrorCode  PCApplyTranspose(PC,Vec,Vec);
100: EXTERN PetscErrorCode  PCApplyTransposeExists(PC,PetscTruth*);
101: EXTERN PetscErrorCode  PCApplyBAorABTranspose(PC,PCSide,Vec,Vec,Vec);

103: /*E
104:     PCRichardsonConvergedReason - reason a PCApplyRichardson method terminates

106:    Level: advanced

108:    Notes: this must match finclude/petscpc.h and the KSPConvergedReason values in petscksp.h

110: .seealso: PCApplyRichardson()
111: E*/
112: typedef enum {
113:               PCRICHARDSON_CONVERGED_RTOL               =  2,
114:               PCRICHARDSON_CONVERGED_ATOL               =  3,
115:               PCRICHARDSON_CONVERGED_ITS                =  4,
116:               PCRICHARDSON_DIVERGED_DTOL                = -4} PCRichardsonConvergedReason;

118: EXTERN PetscErrorCode  PCApplyRichardson(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt,PetscTruth,PetscInt*,PCRichardsonConvergedReason*);
119: EXTERN PetscErrorCode  PCApplyRichardsonExists(PC,PetscTruth*);
120: EXTERN PetscErrorCode  PCSetInitialGuessNonzero(PC,PetscTruth);

122: EXTERN PetscErrorCode  PCRegisterDestroy(void);
123: EXTERN PetscErrorCode  PCRegisterAll(const char[]);

126: EXTERN PetscErrorCode  PCRegister(const char[],const char[],const char[],PetscErrorCode(*)(PC));

128: /*MC
129:    PCRegisterDynamic - Adds a method to the preconditioner package.

131:    Synopsis:
132:    PetscErrorCode PCRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(PC))

134:    Not collective

136:    Input Parameters:
137: +  name_solver - name of a new user-defined solver
138: .  path - path (either absolute or relative) the library containing this solver
139: .  name_create - name of routine to create method context
140: -  routine_create - routine to create method context

142:    Notes:
143:    PCRegisterDynamic() may be called multiple times to add several user-defined preconditioners.

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

148:    Sample usage:
149: .vb
150:    PCRegisterDynamic("my_solver","/home/username/my_lib/lib/libO/solaris/mylib",
151:               "MySolverCreate",MySolverCreate);
152: .ve

154:    Then, your solver can be chosen with the procedural interface via
155: $     PCSetType(pc,"my_solver")
156:    or at runtime via the option
157: $     -pc_type my_solver

159:    Level: advanced

161:    Notes: ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},  or ${any environmental variable}
162:            occuring in pathname will be replaced with appropriate values.
163:          If your function is not being put into a shared library then use PCRegister() instead

165: .keywords: PC, register

167: .seealso: PCRegisterAll(), PCRegisterDestroy()
168: M*/
169: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
170: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,0)
171: #else
172: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,d)
173: #endif

175: EXTERN PetscErrorCode  PCDestroy(PC);
176: EXTERN PetscErrorCode  PCSetFromOptions(PC);
177: EXTERN PetscErrorCode  PCGetType(PC,const PCType*);

179: EXTERN PetscErrorCode  PCFactorGetMatrix(PC,Mat*);
180: EXTERN PetscErrorCode  PCSetModifySubMatrices(PC,PetscErrorCode(*)(PC,PetscInt,const IS[],const IS[],Mat[],void*),void*);
181: EXTERN PetscErrorCode  PCModifySubMatrices(PC,PetscInt,const IS[],const IS[],Mat[],void*);

183: EXTERN PetscErrorCode  PCSetOperators(PC,Mat,Mat,MatStructure);
184: EXTERN PetscErrorCode  PCGetOperators(PC,Mat*,Mat*,MatStructure*);
185: EXTERN PetscErrorCode  PCGetOperatorsSet(PC,PetscTruth*,PetscTruth*);

187: EXTERN PetscErrorCode  PCView(PC,PetscViewer);

189: EXTERN PetscErrorCode  PCSetOptionsPrefix(PC,const char[]);
190: EXTERN PetscErrorCode  PCAppendOptionsPrefix(PC,const char[]);
191: EXTERN PetscErrorCode  PCGetOptionsPrefix(PC,const char*[]);

193: EXTERN PetscErrorCode  PCComputeExplicitOperator(PC,Mat*);

195: /*
196:       These are used to provide extra scaling of preconditioned 
197:    operator for time-stepping schemes like in SUNDIALS 
198: */
199: EXTERN PetscErrorCode  PCDiagonalScale(PC,PetscTruth*);
200: EXTERN PetscErrorCode  PCDiagonalScaleLeft(PC,Vec,Vec);
201: EXTERN PetscErrorCode  PCDiagonalScaleRight(PC,Vec,Vec);
202: EXTERN PetscErrorCode  PCDiagonalScaleSet(PC,Vec);

204: /* ------------- options specific to particular preconditioners --------- */

206: EXTERN PetscErrorCode  PCJacobiSetUseRowMax(PC);
207: EXTERN PetscErrorCode  PCJacobiSetUseRowSum(PC);
208: EXTERN PetscErrorCode  PCJacobiSetUseAbs(PC);
209: EXTERN PetscErrorCode  PCSORSetSymmetric(PC,MatSORType);
210: EXTERN PetscErrorCode  PCSORSetOmega(PC,PetscReal);
211: EXTERN PetscErrorCode  PCSORSetIterations(PC,PetscInt,PetscInt);

213: EXTERN PetscErrorCode  PCEisenstatSetOmega(PC,PetscReal);
214: EXTERN PetscErrorCode  PCEisenstatNoDiagonalScaling(PC);

216: #define USE_PRECONDITIONER_MATRIX 0
217: #define USE_TRUE_MATRIX           1
218: EXTERN PetscErrorCode  PCBJacobiSetUseTrueLocal(PC);
219: EXTERN PetscErrorCode  PCBJacobiSetTotalBlocks(PC,PetscInt,const PetscInt[]);
220: EXTERN PetscErrorCode  PCBJacobiSetLocalBlocks(PC,PetscInt,const PetscInt[]);

222: EXTERN PetscErrorCode  PCKSPSetUseTrue(PC);

224: EXTERN PetscErrorCode  PCShellSetApply(PC,PetscErrorCode (*)(PC,Vec,Vec));
225: EXTERN PetscErrorCode  PCShellSetApplyBA(PC,PetscErrorCode (*)(PC,PCSide,Vec,Vec,Vec));
226: EXTERN PetscErrorCode  PCShellSetApplyTranspose(PC,PetscErrorCode (*)(PC,Vec,Vec));
227: EXTERN PetscErrorCode  PCShellSetSetUp(PC,PetscErrorCode (*)(PC));
228: EXTERN PetscErrorCode  PCShellSetApplyRichardson(PC,PetscErrorCode (*)(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt,PetscTruth,PetscInt*,PCRichardsonConvergedReason*));
229: EXTERN PetscErrorCode  PCShellSetView(PC,PetscErrorCode (*)(PC,PetscViewer));
230: EXTERN PetscErrorCode  PCShellSetDestroy(PC,PetscErrorCode (*)(PC));
231: EXTERN PetscErrorCode  PCShellGetContext(PC,void**);
232: EXTERN PetscErrorCode  PCShellSetContext(PC,void*);
233: EXTERN PetscErrorCode  PCShellSetName(PC,const char[]);
234: EXTERN PetscErrorCode  PCShellGetName(PC,char*[]);

236: EXTERN PetscErrorCode  PCFactorSetZeroPivot(PC,PetscReal);

238: EXTERN PetscErrorCode  PCFactorSetShiftType(PC,MatFactorShiftType);
239: EXTERN PetscErrorCode  PCFactorSetShiftAmount(PC,PetscReal);

241: EXTERN PetscErrorCode  PCFactorSetMatSolverPackage(PC,const MatSolverPackage);
242: EXTERN PetscErrorCode  PCFactorGetMatSolverPackage(PC,const MatSolverPackage*);

244: EXTERN PetscErrorCode  PCFactorSetFill(PC,PetscReal);
245: EXTERN PetscErrorCode  PCFactorSetColumnPivot(PC,PetscReal);
246: EXTERN PetscErrorCode  PCFactorReorderForNonzeroDiagonal(PC,PetscReal);

248: EXTERN PetscErrorCode  PCFactorSetMatOrderingType(PC,const MatOrderingType);
249: EXTERN PetscErrorCode  PCFactorSetReuseOrdering(PC,PetscTruth);
250: EXTERN PetscErrorCode  PCFactorSetReuseFill(PC,PetscTruth);
251: EXTERN PetscErrorCode  PCFactorSetUseInPlace(PC);
252: EXTERN PetscErrorCode  PCFactorSetAllowDiagonalFill(PC);
253: EXTERN PetscErrorCode  PCFactorSetPivotInBlocks(PC,PetscTruth);

255: EXTERN PetscErrorCode  PCFactorSetLevels(PC,PetscInt);
256: EXTERN PetscErrorCode  PCFactorSetDropTolerance(PC,PetscReal,PetscReal,PetscInt);

258: EXTERN PetscErrorCode  PCASMSetLocalSubdomains(PC,PetscInt,IS[],IS[]);
259: EXTERN PetscErrorCode  PCASMSetTotalSubdomains(PC,PetscInt,IS[],IS[]);
260: EXTERN PetscErrorCode  PCASMSetOverlap(PC,PetscInt);
261: EXTERN PetscErrorCode  PCASMSetSortIndices(PC,PetscTruth);
262: /*E
263:     PCASMType - Type of additive Schwarz method to use

265: $  PC_ASM_BASIC - symmetric version where residuals from the ghost points are used
266: $                 and computed values in ghost regions are added together. Classical
267: $                 standard additive Schwarz
268: $  PC_ASM_RESTRICT - residuals from ghost points are used but computed values in ghost
269: $                    region are discarded. Default
270: $  PC_ASM_INTERPOLATE - residuals from ghost points are not used, computed values in ghost
271: $                       region are added back in
272: $  PC_ASM_NONE - ghost point residuals are not used, computed ghost values are discarded
273: $                not very good.                

275:    Level: beginner

277: .seealso: PCASMSetType()
278: E*/
279: typedef enum {PC_ASM_BASIC = 3,PC_ASM_RESTRICT = 1,PC_ASM_INTERPOLATE = 2,PC_ASM_NONE = 0} PCASMType;

282: EXTERN PetscErrorCode  PCASMSetType(PC,PCASMType);
283: EXTERN PetscErrorCode  PCASMCreateSubdomains(Mat,PetscInt,IS*[]);
284: EXTERN PetscErrorCode  PCASMDestroySubdomains(PetscInt,IS[],IS[]);
285: EXTERN PetscErrorCode  PCASMCreateSubdomains2D(PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt *,IS **);
286: EXTERN PetscErrorCode  PCASMGetLocalSubdomains(PC,PetscInt*,IS*[],IS*[]);
287: EXTERN PetscErrorCode  PCASMGetLocalSubmatrices(PC,PetscInt*,Mat*[]);

289: /*E
290:     PCCompositeType - Determines how two or more preconditioner are composed

292: $  PC_COMPOSITE_ADDITIVE - results from application of all preconditioners are added together
293: $  PC_COMPOSITE_MULTIPLICATIVE - preconditioners are applied sequentially to the residual freshly
294: $                                computed after the previous preconditioner application
295: $  PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE - preconditioners are applied sequentially to the residual freshly 
296: $                                computed from first preconditioner to last and then back (Use only for symmetric matrices and preconditions)
297: $  PC_COMPOSITE_SPECIAL - This is very special for a matrix of the form alpha I + R + S
298: $                         where first preconditioner is built from alpha I + S and second from
299: $                         alpha I + R

301:    Level: beginner

303: .seealso: PCCompositeSetType()
304: E*/
305: typedef enum {PC_COMPOSITE_ADDITIVE,PC_COMPOSITE_MULTIPLICATIVE,PC_COMPOSITE_SYMMETRIC_MULTIPLICATIVE,PC_COMPOSITE_SPECIAL,PC_COMPOSITE_SCHUR} PCCompositeType;

308: EXTERN PetscErrorCode  PCCompositeSetUseTrue(PC);
309: EXTERN PetscErrorCode  PCCompositeSetType(PC,PCCompositeType);
310: EXTERN PetscErrorCode  PCCompositeAddPC(PC,PCType);
311: EXTERN PetscErrorCode  PCCompositeGetPC(PC,PetscInt,PC *);
312: EXTERN PetscErrorCode  PCCompositeSpecialSetAlpha(PC,PetscScalar);

314: EXTERN PetscErrorCode  PCRedundantSetNumber(PC,PetscInt);
315: EXTERN PetscErrorCode  PCRedundantSetScatter(PC,VecScatter,VecScatter);
316: EXTERN PetscErrorCode  PCRedundantGetOperators(PC,Mat*,Mat*);
317: EXTERN PetscErrorCode  PCRedundantGetPC(PC,PC*);

319: EXTERN PetscErrorCode  PCSPAISetEpsilon(PC,double);
320: EXTERN PetscErrorCode  PCSPAISetNBSteps(PC,PetscInt);
321: EXTERN PetscErrorCode  PCSPAISetMax(PC,PetscInt);
322: EXTERN PetscErrorCode  PCSPAISetMaxNew(PC,PetscInt);
323: EXTERN PetscErrorCode  PCSPAISetBlockSize(PC,PetscInt);
324: EXTERN PetscErrorCode  PCSPAISetCacheSize(PC,PetscInt);
325: EXTERN PetscErrorCode  PCSPAISetVerbose(PC,PetscInt);
326: EXTERN PetscErrorCode  PCSPAISetSp(PC,PetscInt);

328: EXTERN PetscErrorCode  PCHYPRESetType(PC,const char[]);
329: EXTERN PetscErrorCode  PCHYPREGetType(PC,const char*[]);
330: EXTERN PetscErrorCode  PCBJacobiGetLocalBlocks(PC,PetscInt*,const PetscInt*[]);
331: EXTERN PetscErrorCode  PCBJacobiGetTotalBlocks(PC,PetscInt*,const PetscInt*[]);

333: EXTERN PetscErrorCode  PCFieldSplitSetFields(PC,PetscInt,PetscInt*);
334: EXTERN PetscErrorCode  PCFieldSplitSetType(PC,PCCompositeType);
335: EXTERN PetscErrorCode  PCFieldSplitSetBlockSize(PC,PetscInt);
336: EXTERN PetscErrorCode  PCFieldSplitSetIS(PC,IS);

338: /*E
339:     PCFieldSplitSchurPreType - Determines how to precondition Schur complement

341:     Level: intermediate

343: .seealso: PCFieldSplitSchurPrecondition()
344: E*/
345: typedef enum {PC_FIELDSPLIT_SCHUR_PRE_SELF,PC_FIELDSPLIT_SCHUR_PRE_DIAG,PC_FIELDSPLIT_SCHUR_PRE_USER} PCFieldSplitSchurPreType;

348: EXTERN PetscErrorCode  PCFieldSplitSchurPrecondition(PC,PCFieldSplitSchurPreType,Mat);
349: EXTERN PetscErrorCode  PCFieldSplitGetSchurBlocks(PC,Mat*,Mat*,Mat*,Mat*);

351: EXTERN PetscErrorCode  PCGalerkinSetRestriction(PC,Mat);
352: EXTERN PetscErrorCode  PCGalerkinSetInterpolation(PC,Mat);

354: EXTERN PetscErrorCode  PCSetCoordinates(PC,PetscInt,PetscReal*);
355: EXTERN PetscErrorCode  PCSASetVectors(PC,PetscInt,PetscReal *);

357: EXTERN PetscErrorCode  PCPythonSetType(PC,const char[]);


361: #endif /* __PETSCPC_H */