Actual source code: factor.c
1: #define PETSCKSP_DLL
3: #include ../src/ksp/pc/impls/factor/factor.h
7: /*@
8: PCFactorSetZeroPivot - Sets the size at which smaller pivots are declared to be zero
10: Collective on PC
11:
12: Input Parameters:
13: + pc - the preconditioner context
14: - zero - all pivots smaller than this will be considered zero
16: Options Database Key:
17: . -pc_factor_zeropivot <zero> - Sets tolerance for what is considered a zero pivot
19: Level: intermediate
21: .keywords: PC, set, factorization, direct, fill
23: .seealso: PCFactorSetShiftNonzero(), PCFactorSetShiftType(), PCFactorSetShiftAmount()
24: @*/
25: PetscErrorCode PCFactorSetZeroPivot(PC pc,PetscReal zero)
26: {
27: PetscErrorCode ierr,(*f)(PC,PetscReal);
31: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetZeroPivot_C",(void (**)(void))&f);
32: if (f) {
33: (*f)(pc,zero);
34: }
35: return(0);
36: }
40: /*@
41: PCFactorSetShiftType - adds a particular type of quantity to the diagonal of the matrix during
42: numerical factorization, thus the matrix has nonzero pivots
44: Collective on PC
45:
46: Input Parameters:
47: + pc - the preconditioner context
48: - shifttype - type of shift; one of MAT_SHIFT_NONE, MAT_SHIFT_NONZERO, MAT_SHIFT_POSITIVE_DEFINITE, MAT_SHIFT_INBLOCKS
50: Options Database Key:
51: . -pc_factor_shift_type <shifttype> - Sets shift type or PETSC_DECIDE for the default; use '-help' for a list of available types
53: Level: intermediate
55: .keywords: PC, set, factorization,
57: .seealso: PCFactorSetZeroPivot(), PCFactorSetShiftAmount()
58: @*/
59: PetscErrorCode PCFactorSetShiftType(PC pc,MatFactorShiftType shifttype)
60: {
61: PetscErrorCode ierr,(*f)(PC,MatFactorShiftType);
65: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetShiftType_C",(void (**)(void))&f);
66: if (f) {
67: (*f)(pc,shifttype);
68: }
69: return(0);
70: }
74: /*@
75: PCFactorSetShiftAmount - adds a quantity to the diagonal of the matrix during
76: numerical factorization, thus the matrix has nonzero pivots
78: Collective on PC
79:
80: Input Parameters:
81: + pc - the preconditioner context
82: - shiftamount - amount of shift
84: Options Database Key:
85: . -pc_factor_shift_amount <shiftamount> - Sets shift amount or PETSC_DECIDE for the default
87: Level: intermediate
89: .keywords: PC, set, factorization,
91: .seealso: PCFactorSetZeroPivot(), PCFactorSetShiftType()
92: @*/
93: PetscErrorCode PCFactorSetShiftAmount(PC pc,PetscReal shiftamount)
94: {
95: PetscErrorCode ierr,(*f)(PC,PetscReal);
99: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetShiftAmount_C",(void (**)(void))&f);
100: if (f) {
101: (*f)(pc,shiftamount);
102: }
103: return(0);
104: }
108: /*
109: PCFactorSetDropTolerance - The preconditioner will use an ILU
110: based on a drop tolerance. (Under development)
112: Collective on PC
114: Input Parameters:
115: + pc - the preconditioner context
116: . dt - the drop tolerance, try from 1.e-10 to .1
117: . dtcol - tolerance for column pivot, good values [0.1 to 0.01]
118: - maxrowcount - the max number of nonzeros allowed in a row, best value
119: depends on the number of nonzeros in row of original matrix
121: Options Database Key:
122: . -pc_factor_drop_tolerance <dt,dtcol,maxrowcount> - Sets drop tolerance
124: Level: intermediate
126: There are NO default values for the 3 parameters, you must set them with reasonable values for your
127: matrix. We don't know how to compute reasonable values.
129: .keywords: PC, levels, reordering, factorization, incomplete, ILU
130: */
131: PetscErrorCode PCFactorSetDropTolerance(PC pc,PetscReal dt,PetscReal dtcol,PetscInt maxrowcount)
132: {
133: PetscErrorCode ierr,(*f)(PC,PetscReal,PetscReal,PetscInt);
137: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetDropTolerance_C",(void (**)(void))&f);
138: if (f) {
139: (*f)(pc,dt,dtcol,maxrowcount);
140: }
141: return(0);
142: }
146: /*@
147: PCFactorSetLevels - Sets the number of levels of fill to use.
149: Collective on PC
151: Input Parameters:
152: + pc - the preconditioner context
153: - levels - number of levels of fill
155: Options Database Key:
156: . -pc_factor_levels <levels> - Sets fill level
158: Level: intermediate
160: .keywords: PC, levels, fill, factorization, incomplete, ILU
161: @*/
162: PetscErrorCode PCFactorSetLevels(PC pc,PetscInt levels)
163: {
164: PetscErrorCode ierr,(*f)(PC,PetscInt);
168: if (levels < 0) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"negative levels");
169: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetLevels_C",(void (**)(void))&f);
170: if (f) {
171: (*f)(pc,levels);
172: }
173: return(0);
174: }
178: /*@
179: PCFactorSetAllowDiagonalFill - Causes all diagonal matrix entries to be
180: treated as level 0 fill even if there is no non-zero location.
182: Collective on PC
184: Input Parameters:
185: + pc - the preconditioner context
187: Options Database Key:
188: . -pc_factor_diagonal_fill
190: Notes:
191: Does not apply with 0 fill.
193: Level: intermediate
195: .keywords: PC, levels, fill, factorization, incomplete, ILU
196: @*/
197: PetscErrorCode PCFactorSetAllowDiagonalFill(PC pc)
198: {
199: PetscErrorCode ierr,(*f)(PC);
203: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetAllowDiagonalFill_C",(void (**)(void))&f);
204: if (f) {
205: (*f)(pc);
206: }
207: return(0);
208: }
212: /*@
213: PCFactorReorderForNonzeroDiagonal - reorders rows/columns of matrix to remove zeros from diagonal
215: Collective on PC
216:
217: Input Parameters:
218: + pc - the preconditioner context
219: - tol - diagonal entries smaller than this in absolute value are considered zero
221: Options Database Key:
222: . -pc_factor_nonzeros_along_diagonal
224: Level: intermediate
226: .keywords: PC, set, factorization, direct, fill
228: .seealso: PCFactorSetFill(), PCFactorSetShiftNonzero(), PCFactorSetZeroPivot(), MatReorderForNonzeroDiagonal()
229: @*/
230: PetscErrorCode PCFactorReorderForNonzeroDiagonal(PC pc,PetscReal rtol)
231: {
232: PetscErrorCode ierr,(*f)(PC,PetscReal);
236: PetscObjectQueryFunction((PetscObject)pc,"PCFactorReorderForNonzeroDiagonal_C",(void (**)(void))&f);
237: if (f) {
238: (*f)(pc,rtol);
239: }
240: return(0);
241: }
245: /*@C
246: PCFactorSetMatSolverPackage - sets the software that is used to perform the factorization
248: Collective on PC
249:
250: Input Parameters:
251: + pc - the preconditioner context
252: - stype - for example, spooles, superlu, superlu_dist
254: Options Database Key:
255: . -pc_factor_mat_solver_package <stype> - spooles, petsc, superlu, superlu_dist, mumps
257: Level: intermediate
259: Note:
260: By default this will use the PETSc factorization if it exists
261:
263: .keywords: PC, set, factorization, direct, fill
265: .seealso: MatGetFactor(), MatSolverPackage, PCFactorGetMatSolverPackage()
267: @*/
268: PetscErrorCode PCFactorSetMatSolverPackage(PC pc,const MatSolverPackage stype)
269: {
270: PetscErrorCode ierr,(*f)(PC,const MatSolverPackage);
274: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetMatSolverPackage_C",(void (**)(void))&f);
275: if (f) {
276: (*f)(pc,stype);
277: }
278: return(0);
279: }
283: /*@C
284: PCFactorGetMatSolverPackage - gets the software that is used to perform the factorization
286: Collective on PC
287:
288: Input Parameter:
289: . pc - the preconditioner context
291: Output Parameter:
292: . stype - for example, spooles, superlu, superlu_dist
294: Level: intermediate
297: .keywords: PC, set, factorization, direct, fill
299: .seealso: MatGetFactor(), MatSolverPackage, PCFactorGetMatSolverPackage()
301: @*/
302: PetscErrorCode PCFactorGetMatSolverPackage(PC pc,const MatSolverPackage *stype)
303: {
304: PetscErrorCode ierr,(*f)(PC,const MatSolverPackage*);
308: PetscObjectQueryFunction((PetscObject)pc,"PCFactorGetMatSolverPackage_C",(void (**)(void))&f);
309: if (f) {
310: (*f)(pc,stype);
311: }
312: return(0);
313: }
317: /*@
318: PCFactorSetFill - Indicate the amount of fill you expect in the factored matrix,
319: fill = number nonzeros in factor/number nonzeros in original matrix.
321: Collective on PC
322:
323: Input Parameters:
324: + pc - the preconditioner context
325: - fill - amount of expected fill
327: Options Database Key:
328: . -pc_factor_fill <fill> - Sets fill amount
330: Level: intermediate
332: Note:
333: For sparse matrix factorizations it is difficult to predict how much
334: fill to expect. By running with the option -info PETSc will print the
335: actual amount of fill used; allowing you to set the value accurately for
336: future runs. Default PETSc uses a value of 5.0
338: .keywords: PC, set, factorization, direct, fill
340: @*/
341: PetscErrorCode PCFactorSetFill(PC pc,PetscReal fill)
342: {
343: PetscErrorCode ierr,(*f)(PC,PetscReal);
347: if (fill < 1.0) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Fill factor cannot be less then 1.0");
348: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetFill_C",(void (**)(void))&f);
349: if (f) {
350: (*f)(pc,fill);
351: }
352: return(0);
353: }
357: /*@
358: PCFactorSetUseInPlace - Tells the system to do an in-place factorization.
359: For dense matrices, this enables the solution of much larger problems.
360: For sparse matrices the factorization cannot be done truly in-place
361: so this does not save memory during the factorization, but after the matrix
362: is factored, the original unfactored matrix is freed, thus recovering that
363: space.
365: Collective on PC
367: Input Parameters:
368: . pc - the preconditioner context
370: Options Database Key:
371: . -pc_factor_in_place - Activates in-place factorization
373: Notes:
374: PCFactorSetUseInplace() can only be used with the KSP method KSPPREONLY or when
375: a different matrix is provided for the multiply and the preconditioner in
376: a call to KSPSetOperators().
377: This is because the Krylov space methods require an application of the
378: matrix multiplication, which is not possible here because the matrix has
379: been factored in-place, replacing the original matrix.
381: Level: intermediate
383: .keywords: PC, set, factorization, direct, inplace, in-place, LU
385: .seealso: PCILUSetUseInPlace()
386: @*/
387: PetscErrorCode PCFactorSetUseInPlace(PC pc)
388: {
389: PetscErrorCode ierr,(*f)(PC);
393: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetUseInPlace_C",(void (**)(void))&f);
394: if (f) {
395: (*f)(pc);
396: }
397: return(0);
398: }
402: /*@C
403: PCFactorSetMatOrderingType - Sets the ordering routine (to reduce fill) to
404: be used in the LU factorization.
406: Collective on PC
408: Input Parameters:
409: + pc - the preconditioner context
410: - ordering - the matrix ordering name, for example, MATORDERING_ND or MATORDERING_RCM
412: Options Database Key:
413: . -pc_factor_mat_ordering_type <nd,rcm,...> - Sets ordering routine
415: Level: intermediate
417: Notes: nested dissection is used by default
419: For Cholesky and ICC and the SBAIJ format reorderings are not available,
420: since only the upper triangular part of the matrix is stored. You can use the
421: SeqAIJ format in this case to get reorderings.
423: @*/
424: PetscErrorCode PCFactorSetMatOrderingType(PC pc,const MatOrderingType ordering)
425: {
426: PetscErrorCode ierr,(*f)(PC,const MatOrderingType);
429: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetMatOrderingType_C",(void (**)(void))&f);
430: if (f) {
431: (*f)(pc,ordering);
432: }
433: return(0);
434: }
438: /*@
439: PCFactorSetColumnPivot - Determines when column pivoting is done during matrix factorization.
440: For PETSc dense matrices column pivoting is always done, for PETSc sparse matrices
441: it is never done. For the Matlab and SuperLU factorization this is used.
443: Collective on PC
445: Input Parameters:
446: + pc - the preconditioner context
447: - dtcol - 0.0 implies no pivoting, 1.0 complete pivoting (slower, requires more memory but more stable)
449: Options Database Key:
450: . -pc_factor_pivoting <dtcol>
452: Level: intermediate
454: .seealso: PCILUSetMatOrdering(), PCFactorSetPivotInBlocks()
455: @*/
456: PetscErrorCode PCFactorSetColumnPivot(PC pc,PetscReal dtcol)
457: {
458: PetscErrorCode ierr,(*f)(PC,PetscReal);
461: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetColumnPivot_C",(void (**)(void))&f);
462: if (f) {
463: (*f)(pc,dtcol);
464: }
465: return(0);
466: }
470: /*@
471: PCFactorSetPivotInBlocks - Determines if pivoting is done while factoring each block
472: with BAIJ or SBAIJ matrices
474: Collective on PC
476: Input Parameters:
477: + pc - the preconditioner context
478: - pivot - PETSC_TRUE or PETSC_FALSE
480: Options Database Key:
481: . -pc_factor_pivot_in_blocks <true,false>
483: Level: intermediate
485: .seealso: PCILUSetMatOrdering(), PCFactorSetColumnPivot()
486: @*/
487: PetscErrorCode PCFactorSetPivotInBlocks(PC pc,PetscTruth pivot)
488: {
489: PetscErrorCode ierr,(*f)(PC,PetscTruth);
492: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetPivotInBlocks_C",(void (**)(void))&f);
493: if (f) {
494: (*f)(pc,pivot);
495: }
496: return(0);
497: }
501: /*@
502: PCFactorSetReuseFill - When matrices with same different nonzero structure are factored,
503: this causes later ones to use the fill ratio computed in the initial factorization.
505: Collective on PC
507: Input Parameters:
508: + pc - the preconditioner context
509: - flag - PETSC_TRUE to reuse else PETSC_FALSE
511: Options Database Key:
512: . -pc_factor_reuse_fill - Activates PCFactorSetReuseFill()
514: Level: intermediate
516: .keywords: PC, levels, reordering, factorization, incomplete, Cholesky
518: .seealso: PCFactorSetReuseOrdering()
519: @*/
520: PetscErrorCode PCFactorSetReuseFill(PC pc,PetscTruth flag)
521: {
522: PetscErrorCode ierr,(*f)(PC,PetscTruth);
526: PetscObjectQueryFunction((PetscObject)pc,"PCFactorSetReuseFill_C",(void (**)(void))&f);
527: if (f) {
528: (*f)(pc,flag);
529: }
530: return(0);
531: }