Actual source code: petscpc.h
1: /* $Id: petscpc.h,v 1.122 2001/08/21 21:03:12 bsmith Exp $ */
3: /*
4: Preconditioner module.
5: */
8: #include petscmat.h
9: PETSC_EXTERN_CXX_BEGIN
11: EXTERN int PCInitializePackage(const char[]);
13: /*
14: PCList contains the list of preconditioners currently registered
15: These are added with the PCRegisterDynamic() macro
16: */
17: extern PetscFList PCList;
18: #define PCType char*
20: /*S
21: PC - Abstract PETSc object that manages all preconditioners
23: Level: beginner
25: Concepts: preconditioners
27: .seealso: PCCreate(), PCSetType(), PCType (for list of available types)
28: S*/
29: typedef struct _p_PC* PC;
31: /*E
32: PCType - String with the name of a PETSc preconditioner method or the creation function
33: with an optional dynamic library name, for example
34: http://www.mcs.anl.gov/petsc/lib.a:mypccreate()
36: Level: beginner
38: Notes: Click on the links below to see details on a particular solver
40: .seealso: PCSetType(), PC, PCCreate()
41: E*/
42: #define PCNONE "none"
43: #define PCJACOBI "jacobi"
44: #define PCSOR "sor"
45: #define PCLU "lu"
46: #define PCSHELL "shell"
47: #define PCBJACOBI "bjacobi"
48: #define PCMG "mg"
49: #define PCEISENSTAT "eisenstat"
50: #define PCILU "ilu"
51: #define PCICC "icc"
52: #define PCASM "asm"
53: #define PCKSP "ksp"
54: #define PCCOMPOSITE "composite"
55: #define PCREDUNDANT "redundant"
56: #define PCSPAI "spai"
57: #define PCNN "nn"
58: #define PCCHOLESKY "cholesky"
59: #define PCRAMG "ramg"
60: #define PCSAMG "samg"
61: #define PCPBJACOBI "pbjacobi"
62: #define PCESI "esi"
63: #define PCPETSCESI "petscesi"
64: #define PCMAT "mat"
65: #define PCHYPRE "hypre"
67: /* Logging support */
68: extern int PC_COOKIE;
69: extern int PC_SetUp, PC_SetUpOnBlocks, PC_Apply, PC_ApplyCoarse, PC_ApplyMultiple, PC_ApplySymmetricLeft;
70: extern int PC_ApplySymmetricRight, PC_ModifySubMatrices;
72: /*E
73: PCSide - If the preconditioner is to be applied to the left, right
74: or symmetrically around the operator.
76: Level: beginner
78: .seealso:
79: E*/
80: typedef enum { PC_LEFT,PC_RIGHT,PC_SYMMETRIC } PCSide;
82: EXTERN int PCCreate(MPI_Comm,PC*);
83: EXTERN int PCSetType(PC,const PCType);
84: EXTERN int PCSetUp(PC);
85: EXTERN int PCSetUpOnBlocks(PC);
86: EXTERN int PCApply(PC,Vec,Vec,PCSide);
87: EXTERN int PCApplySymmetricLeft(PC,Vec,Vec);
88: EXTERN int PCApplySymmetricRight(PC,Vec,Vec);
89: EXTERN int PCApplyBAorAB(PC,PCSide,Vec,Vec,Vec);
90: EXTERN int PCApplyTranspose(PC,Vec,Vec);
91: EXTERN int PCHasApplyTranspose(PC,PetscTruth*);
92: EXTERN int PCApplyBAorABTranspose(PC,PCSide,Vec,Vec,Vec);
93: EXTERN int PCApplyRichardson(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int);
94: EXTERN int PCApplyRichardsonExists(PC,PetscTruth*);
96: EXTERN int PCRegisterDestroy(void);
97: EXTERN int PCRegisterAll(const char[]);
98: extern PetscTruth PCRegisterAllCalled;
100: EXTERN int PCRegister(const char[],const char[],const char[],int(*)(PC));
102: /*MC
103: PCRegisterDynamic - Adds a method to the preconditioner package.
105: Synopsis:
106: int PCRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(PC))
108: Not collective
110: Input Parameters:
111: + name_solver - name of a new user-defined solver
112: . path - path (either absolute or relative) the library containing this solver
113: . name_create - name of routine to create method context
114: - routine_create - routine to create method context
116: Notes:
117: PCRegisterDynamic() may be called multiple times to add several user-defined preconditioners.
119: If dynamic libraries are used, then the fourth input argument (routine_create)
120: is ignored.
122: Sample usage:
123: .vb
124: PCRegisterDynamic("my_solver","/home/username/my_lib/lib/libO/solaris/mylib",
125: "MySolverCreate",MySolverCreate);
126: .ve
128: Then, your solver can be chosen with the procedural interface via
129: $ PCSetType(pc,"my_solver")
130: or at runtime via the option
131: $ -pc_type my_solver
133: Level: advanced
135: Notes: ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT}, or ${any environmental variable}
136: occuring in pathname will be replaced with appropriate values.
137: If your function is not being put into a shared library then use PCRegister() instead
139: .keywords: PC, register
141: .seealso: PCRegisterAll(), PCRegisterDestroy()
142: M*/
143: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
144: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,0)
145: #else
146: #define PCRegisterDynamic(a,b,c,d) PCRegister(a,b,c,d)
147: #endif
149: EXTERN int PCDestroy(PC);
150: EXTERN int PCSetFromOptions(PC);
151: EXTERN int PCESISetFromOptions(PC);
152: EXTERN int PCGetType(PC,PCType*);
154: EXTERN int PCGetFactoredMatrix(PC,Mat*);
155: EXTERN int PCSetModifySubMatrices(PC,int(*)(PC,int,const IS[],const IS[],Mat[],void*),void*);
156: EXTERN int PCModifySubMatrices(PC,int,const IS[],const IS[],Mat[],void*);
158: EXTERN int PCSetOperators(PC,Mat,Mat,MatStructure);
159: EXTERN int PCGetOperators(PC,Mat*,Mat*,MatStructure*);
161: EXTERN int PCSetVector(PC,Vec);
162: EXTERN int PCGetVector(PC,Vec*);
163: EXTERN int PCView(PC,PetscViewer);
165: EXTERN int PCSetOptionsPrefix(PC,const char[]);
166: EXTERN int PCAppendOptionsPrefix(PC,const char[]);
167: EXTERN int PCGetOptionsPrefix(PC,char*[]);
169: EXTERN int PCNullSpaceAttach(PC,MatNullSpace);
171: EXTERN int PCComputeExplicitOperator(PC,Mat*);
173: /*
174: These are used to provide extra scaling of preconditioned
175: operator for time-stepping schemes like in PVODE
176: */
177: EXTERN int PCDiagonalScale(PC,PetscTruth*);
178: EXTERN int PCDiagonalScaleLeft(PC,Vec,Vec);
179: EXTERN int PCDiagonalScaleRight(PC,Vec,Vec);
180: EXTERN int PCDiagonalScaleSet(PC,Vec);
182: /* ------------- options specific to particular preconditioners --------- */
184: EXTERN int PCJacobiSetUseRowMax(PC);
185: EXTERN int PCSORSetSymmetric(PC,MatSORType);
186: EXTERN int PCSORSetOmega(PC,PetscReal);
187: EXTERN int PCSORSetIterations(PC,int,int);
189: EXTERN int PCEisenstatSetOmega(PC,PetscReal);
190: EXTERN int PCEisenstatNoDiagonalScaling(PC);
192: #define USE_PRECONDITIONER_MATRIX 0
193: #define USE_TRUE_MATRIX 1
194: EXTERN int PCBJacobiSetUseTrueLocal(PC);
195: EXTERN int PCBJacobiSetTotalBlocks(PC,int,const int[]);
196: EXTERN int PCBJacobiSetLocalBlocks(PC,int,const int[]);
198: EXTERN int PCKSPSetUseTrue(PC);
200: EXTERN int PCShellSetApply(PC,int (*)(void*,Vec,Vec),void*);
201: EXTERN int PCShellSetApplyTranspose(PC,int (*)(void*,Vec,Vec));
202: EXTERN int PCShellSetSetUp(PC,int (*)(void*));
203: EXTERN int PCShellSetApplyRichardson(PC,int (*)(void*,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int),void*);
204: EXTERN int PCShellSetView(PC,int (*)(void*,PetscViewer));
205: EXTERN int PCShellSetName(PC,const char[]);
206: EXTERN int PCShellGetName(PC,char*[]);
208: EXTERN int PCLUSetMatOrdering(PC,MatOrderingType);
209: EXTERN int PCLUSetReuseOrdering(PC,PetscTruth);
210: EXTERN int PCLUSetReuseFill(PC,PetscTruth);
211: EXTERN int PCLUSetUseInPlace(PC);
212: EXTERN int PCLUSetFill(PC,PetscReal);
213: EXTERN int PCLUSetDamping(PC,PetscReal);
214: EXTERN int PCLUSetShift(PC,PetscTruth);
215: EXTERN int PCLUSetPivoting(PC,PetscReal);
216: EXTERN int PCLUSetPivotInBlocks(PC,PetscTruth);
217: EXTERN int PCLUSetZeroPivot(PC,PetscReal);
219: EXTERN int PCCholeskySetMatOrdering(PC,MatOrderingType);
220: EXTERN int PCCholeskySetReuseOrdering(PC,PetscTruth);
221: EXTERN int PCCholeskySetReuseFill(PC,PetscTruth);
222: EXTERN int PCCholeskySetUseInPlace(PC);
223: EXTERN int PCCholeskySetFill(PC,PetscReal);
224: EXTERN int PCCholeskySetDamping(PC,PetscReal);
225: EXTERN int PCCholeskySetShift(PC,PetscTruth);
226: EXTERN int PCCholeskySetPivotInBlocks(PC,PetscTruth);
228: EXTERN int PCILUSetMatOrdering(PC,MatOrderingType);
229: EXTERN int PCILUSetUseInPlace(PC);
230: EXTERN int PCILUSetFill(PC,PetscReal);
231: EXTERN int PCILUSetLevels(PC,int);
232: EXTERN int PCILUSetReuseOrdering(PC,PetscTruth);
233: EXTERN int PCILUSetUseDropTolerance(PC,PetscReal,PetscReal,int);
234: EXTERN int PCILUDTSetReuseFill(PC,PetscTruth);
235: EXTERN int PCILUSetAllowDiagonalFill(PC);
236: EXTERN int PCILUSetDamping(PC,PetscReal);
237: EXTERN int PCILUSetShift(PC,PetscTruth);
238: EXTERN int PCILUSetPivotInBlocks(PC,PetscTruth);
239: EXTERN int PCILUSetZeroPivot(PC,PetscReal);
241: EXTERN int PCICCSetMatOrdering(PC,MatOrderingType);
242: EXTERN int PCICCSetFill(PC,PetscReal);
243: EXTERN int PCICCSetLevels(PC,int);
244: EXTERN int PCICCSetDamping(PC,PetscReal);
245: EXTERN int PCICCSetShift(PC,PetscTruth);
246: EXTERN int PCICCSetPivotInBlocks(PC,PetscTruth);
247: EXTERN int PCICCSetZeroPivot(PC,PetscReal);
249: EXTERN int PCASMSetLocalSubdomains(PC,int,IS[]);
250: EXTERN int PCASMSetTotalSubdomains(PC,int,IS[]);
251: EXTERN int PCASMSetOverlap(PC,int);
252: /*E
253: PCASMType - Type of additive Schwarz method to use
255: $ PC_ASM_BASIC - symmetric version where residuals from the ghost points are used
256: $ and computed values in ghost regions are added together. Classical
257: $ standard additive Schwarz
258: $ PC_ASM_RESTRICT - residuals from ghost points are used but computed values in ghost
259: $ region are discarded. Default
260: $ PC_ASM_INTERPOLATE - residuals from ghost points are not used, computed values in ghost
261: $ region are added back in
262: $ PC_ASM_NONE - ghost point residuals are not used, computed ghost values are discarded
263: $ not very good.
265: Level: beginner
267: .seealso: PCASMSetType()
268: E*/
269: typedef enum {PC_ASM_BASIC = 3,PC_ASM_RESTRICT = 1,PC_ASM_INTERPOLATE = 2,PC_ASM_NONE = 0} PCASMType;
270: EXTERN int PCASMSetType(PC,PCASMType);
271: EXTERN int PCASMCreateSubdomains2D(int,int,int,int,int,int,int *,IS **);
272: EXTERN int PCASMSetUseInPlace(PC);
273: EXTERN int PCASMGetLocalSubdomains(PC,int*,IS*[]);
274: EXTERN int PCASMGetLocalSubmatrices(PC,int*,Mat*[]);
276: /*E
277: PCCompositeType - Determines how two or more preconditioner are composed
279: $ PC_COMPOSITE_ADDITIVE - results from application of all preconditioners are added together
280: $ PC_COMPOSITE_MULTIPLICATIVE - preconditioners are applied sequentially to the residual freshly
281: $ computed after the previous preconditioner application
282: $ PC_COMPOSITE_SPECIAL - This is very special for a matrix of the form alpha I + R + S
283: $ where first preconditioner is built from alpha I + S and second from
284: $ alpha I + R
286: Level: beginner
288: .seealso: PCCompositeSetType()
289: E*/
290: typedef enum {PC_COMPOSITE_ADDITIVE,PC_COMPOSITE_MULTIPLICATIVE,PC_COMPOSITE_SPECIAL} PCCompositeType;
291: EXTERN int PCCompositeSetUseTrue(PC);
292: EXTERN int PCCompositeSetType(PC,PCCompositeType);
293: EXTERN int PCCompositeAddPC(PC,PCType);
294: EXTERN int PCCompositeGetPC(PC pc,int n,PC *);
295: EXTERN int PCCompositeSpecialSetAlpha(PC,PetscScalar);
297: EXTERN int PCRedundantSetScatter(PC,VecScatter,VecScatter);
298: EXTERN int PCRedundantGetOperators(PC,Mat*,Mat*);
299: EXTERN int PCRedundantGetPC(PC,PC*);
300: EXTERN int MatGetOrderingList(PetscFList *list);
302: EXTERN int PCSPAISetEpsilon(PC,double);
303: EXTERN int PCSPAISetNBSteps(PC,int);
304: EXTERN int PCSPAISetMax(PC,int);
305: EXTERN int PCSPAISetMaxNew(PC,int);
306: EXTERN int PCSPAISetBlockSize(PC,int);
307: EXTERN int PCSPAISetCacheSize(PC,int);
308: EXTERN int PCSPAISetVerbose(PC,int);
309: EXTERN int PCSPAISetSp(PC,int);
311: EXTERN int PCHYPRESetType(PC,const char[]);
312: EXTERN int PCBJacobiGetLocalBlocks(PC,int*,const int*[]);
313: EXTERN int PCBJacobiGetTotalBlocks(PC,int*,const int*[]);
315: PETSC_EXTERN_CXX_END
316: #endif /* __PETSCPC_H */