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 */