Actual source code: factor.c
petsc-3.14.6 2021-03-30
2: #include <../src/ksp/pc/impls/factor/factor.h>
4: static PetscErrorCode PCFactorSetReuseOrdering_Factor(PC pc,PetscBool flag)
5: {
6: PC_Factor *lu = (PC_Factor*)pc->data;
9: lu->reuseordering = flag;
10: return(0);
11: }
13: static PetscErrorCode PCFactorSetReuseFill_Factor(PC pc,PetscBool flag)
14: {
15: PC_Factor *lu = (PC_Factor*)pc->data;
18: lu->reusefill = flag;
19: return(0);
20: }
22: static PetscErrorCode PCFactorSetUseInPlace_Factor(PC pc,PetscBool flg)
23: {
24: PC_Factor *dir = (PC_Factor*)pc->data;
27: dir->inplace = flg;
28: return(0);
29: }
31: static PetscErrorCode PCFactorGetUseInPlace_Factor(PC pc,PetscBool *flg)
32: {
33: PC_Factor *dir = (PC_Factor*)pc->data;
36: *flg = dir->inplace;
37: return(0);
38: }
40: /*@
41: PCFactorSetUpMatSolverType - Can be called after KSPSetOperators() or PCSetOperators(), causes MatGetFactor() to be called so then one may
42: set the options for that particular factorization object.
44: Input Parameter:
45: . pc - the preconditioner context
47: Notes:
48: After you have called this function (which has to be after the KSPSetOperators() or PCSetOperators()) you can call PCFactorGetMatrix() and then set factor options on that matrix.
50: Level: intermediate
52: .seealso: PCFactorSetMatSolverType(), PCFactorGetMatrix()
53: @*/
54: PetscErrorCode PCFactorSetUpMatSolverType(PC pc)
55: {
60: PetscTryMethod(pc,"PCFactorSetUpMatSolverType_C",(PC),(pc));
61: return(0);
62: }
64: /*@
65: PCFactorSetZeroPivot - Sets the size at which smaller pivots are declared to be zero
67: Logically Collective on PC
69: Input Parameters:
70: + pc - the preconditioner context
71: - zero - all pivots smaller than this will be considered zero
73: Options Database Key:
74: . -pc_factor_zeropivot <zero> - Sets tolerance for what is considered a zero pivot
76: Level: intermediate
78: .seealso: PCFactorSetShiftType(), PCFactorSetShiftAmount()
79: @*/
80: PetscErrorCode PCFactorSetZeroPivot(PC pc,PetscReal zero)
81: {
87: PetscTryMethod(pc,"PCFactorSetZeroPivot_C",(PC,PetscReal),(pc,zero));
88: return(0);
89: }
91: /*@
92: PCFactorSetShiftType - adds a particular type of quantity to the diagonal of the matrix during
93: numerical factorization, thus the matrix has nonzero pivots
95: Logically Collective on PC
97: Input Parameters:
98: + pc - the preconditioner context
99: - shifttype - type of shift; one of MAT_SHIFT_NONE, MAT_SHIFT_NONZERO, MAT_SHIFT_POSITIVE_DEFINITE, MAT_SHIFT_INBLOCKS
101: Options Database Key:
102: . -pc_factor_shift_type <shifttype> - Sets shift type; use '-help' for a list of available types
104: Level: intermediate
106: .seealso: PCFactorSetZeroPivot(), PCFactorSetShiftAmount()
107: @*/
108: PetscErrorCode PCFactorSetShiftType(PC pc,MatFactorShiftType shifttype)
109: {
115: PetscTryMethod(pc,"PCFactorSetShiftType_C",(PC,MatFactorShiftType),(pc,shifttype));
116: return(0);
117: }
119: /*@
120: PCFactorSetShiftAmount - adds a quantity to the diagonal of the matrix during
121: numerical factorization, thus the matrix has nonzero pivots
123: Logically Collective on PC
125: Input Parameters:
126: + pc - the preconditioner context
127: - shiftamount - amount of shift
129: Options Database Key:
130: . -pc_factor_shift_amount <shiftamount> - Sets shift amount or PETSC_DECIDE for the default
132: Level: intermediate
134: .seealso: PCFactorSetZeroPivot(), PCFactorSetShiftType()
135: @*/
136: PetscErrorCode PCFactorSetShiftAmount(PC pc,PetscReal shiftamount)
137: {
143: PetscTryMethod(pc,"PCFactorSetShiftAmount_C",(PC,PetscReal),(pc,shiftamount));
144: return(0);
145: }
147: /*@
148: PCFactorSetDropTolerance - The preconditioner will use an ILU
149: based on a drop tolerance. (Under development)
151: Logically Collective on PC
153: Input Parameters:
154: + pc - the preconditioner context
155: . dt - the drop tolerance, try from 1.e-10 to .1
156: . dtcol - tolerance for column pivot, good values [0.1 to 0.01]
157: - maxrowcount - the max number of nonzeros allowed in a row, best value
158: depends on the number of nonzeros in row of original matrix
160: Options Database Key:
161: . -pc_factor_drop_tolerance <dt,dtcol,maxrowcount> - Sets drop tolerance
163: Level: intermediate
165: There are NO default values for the 3 parameters, you must set them with reasonable values for your
166: matrix. We don't know how to compute reasonable values.
168: @*/
169: PetscErrorCode PCFactorSetDropTolerance(PC pc,PetscReal dt,PetscReal dtcol,PetscInt maxrowcount)
170: {
177: PetscTryMethod(pc,"PCFactorSetDropTolerance_C",(PC,PetscReal,PetscReal,PetscInt),(pc,dt,dtcol,maxrowcount));
178: return(0);
179: }
181: /*@
182: PCFactorGetZeroPivot - Gets the tolerance used to define a zero privot
184: Not Collective
186: Input Parameters:
187: . pc - the preconditioner context
189: Output Parameter:
190: . pivot - the tolerance
192: Level: intermediate
194: .seealso: PCFactorSetZeroPivot()
195: @*/
196: PetscErrorCode PCFactorGetZeroPivot(PC pc,PetscReal *pivot)
197: {
202: PetscUseMethod(pc,"PCFactorGetZeroPivot_C",(PC,PetscReal*),(pc,pivot));
203: return(0);
204: }
206: /*@
207: PCFactorGetShiftAmount - Gets the tolerance used to define a zero privot
209: Not Collective
211: Input Parameters:
212: . pc - the preconditioner context
214: Output Parameter:
215: . shift - how much to shift the diagonal entry
217: Level: intermediate
219: .seealso: PCFactorSetShiftAmount(), PCFactorSetShiftType(), PCFactorGetShiftType()
220: @*/
221: PetscErrorCode PCFactorGetShiftAmount(PC pc,PetscReal *shift)
222: {
227: PetscUseMethod(pc,"PCFactorGetShiftAmount_C",(PC,PetscReal*),(pc,shift));
228: return(0);
229: }
231: /*@
232: PCFactorGetShiftType - Gets the type of shift, if any, done when a zero pivot is detected
234: Not Collective
236: Input Parameters:
237: . pc - the preconditioner context
239: Output Parameter:
240: . type - one of MAT_SHIFT_NONE, MAT_SHIFT_NONZERO, MAT_SHIFT_POSITIVE_DEFINITE, or MAT_SHIFT_INBLOCKS
242: Level: intermediate
244: .seealso: PCFactorSetShiftType(), MatFactorShiftType, PCFactorSetShiftAmount(), PCFactorGetShiftAmount()
245: @*/
246: PetscErrorCode PCFactorGetShiftType(PC pc,MatFactorShiftType *type)
247: {
252: PetscUseMethod(pc,"PCFactorGetShiftType_C",(PC,MatFactorShiftType*),(pc,type));
253: return(0);
254: }
256: /*@
257: PCFactorGetLevels - Gets the number of levels of fill to use.
259: Logically Collective on PC
261: Input Parameters:
262: . pc - the preconditioner context
264: Output Parameter:
265: . levels - number of levels of fill
267: Level: intermediate
269: @*/
270: PetscErrorCode PCFactorGetLevels(PC pc,PetscInt *levels)
271: {
276: PetscUseMethod(pc,"PCFactorGetLevels_C",(PC,PetscInt*),(pc,levels));
277: return(0);
278: }
280: /*@
281: PCFactorSetLevels - Sets the number of levels of fill to use.
283: Logically Collective on PC
285: Input Parameters:
286: + pc - the preconditioner context
287: - levels - number of levels of fill
289: Options Database Key:
290: . -pc_factor_levels <levels> - Sets fill level
292: Level: intermediate
294: @*/
295: PetscErrorCode PCFactorSetLevels(PC pc,PetscInt levels)
296: {
301: if (levels < 0) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_OUTOFRANGE,"negative levels");
303: PetscTryMethod(pc,"PCFactorSetLevels_C",(PC,PetscInt),(pc,levels));
304: return(0);
305: }
307: /*@
308: PCFactorSetAllowDiagonalFill - Causes all diagonal matrix entries to be
309: treated as level 0 fill even if there is no non-zero location.
311: Logically Collective on PC
313: Input Parameters:
314: + pc - the preconditioner context
315: - flg - PETSC_TRUE to turn on, PETSC_FALSE to turn off
317: Options Database Key:
318: . -pc_factor_diagonal_fill
320: Notes:
321: Does not apply with 0 fill.
323: Level: intermediate
325: .seealso: PCFactorGetAllowDiagonalFill()
326: @*/
327: PetscErrorCode PCFactorSetAllowDiagonalFill(PC pc,PetscBool flg)
328: {
333: PetscTryMethod(pc,"PCFactorSetAllowDiagonalFill_C",(PC,PetscBool),(pc,flg));
334: return(0);
335: }
337: /*@
338: PCFactorGetAllowDiagonalFill - Determines if all diagonal matrix entries are
339: treated as level 0 fill even if there is no non-zero location.
341: Logically Collective on PC
343: Input Parameter:
344: . pc - the preconditioner context
346: Output Parameter:
347: . flg - PETSC_TRUE to turn on, PETSC_FALSE to turn off
349: Options Database Key:
350: . -pc_factor_diagonal_fill
352: Notes:
353: Does not apply with 0 fill.
355: Level: intermediate
357: .seealso: PCFactorSetAllowDiagonalFill()
358: @*/
359: PetscErrorCode PCFactorGetAllowDiagonalFill(PC pc,PetscBool *flg)
360: {
365: PetscUseMethod(pc,"PCFactorGetAllowDiagonalFill_C",(PC,PetscBool*),(pc,flg));
366: return(0);
367: }
369: /*@
370: PCFactorReorderForNonzeroDiagonal - reorders rows/columns of matrix to remove zeros from diagonal
372: Logically Collective on PC
374: Input Parameters:
375: + pc - the preconditioner context
376: - tol - diagonal entries smaller than this in absolute value are considered zero
378: Options Database Key:
379: . -pc_factor_nonzeros_along_diagonal <tol>
381: Level: intermediate
383: .seealso: PCFactorSetFill(), PCFactorSetShiftNonzero(), PCFactorSetZeroPivot(), MatReorderForNonzeroDiagonal()
384: @*/
385: PetscErrorCode PCFactorReorderForNonzeroDiagonal(PC pc,PetscReal rtol)
386: {
392: PetscTryMethod(pc,"PCFactorReorderForNonzeroDiagonal_C",(PC,PetscReal),(pc,rtol));
393: return(0);
394: }
396: /*@C
397: PCFactorSetMatSolverType - sets the software that is used to perform the factorization
399: Logically Collective on PC
401: Input Parameters:
402: + pc - the preconditioner context
403: - stype - for example, superlu, superlu_dist
405: Options Database Key:
406: . -pc_factor_mat_solver_type <stype> - petsc, superlu, superlu_dist, mumps, cusparse
408: Level: intermediate
410: Note:
411: By default this will use the PETSc factorization if it exists
413: .seealso: MatGetFactor(), MatSolverType, PCFactorGetMatSolverType()
414: @*/
415: PetscErrorCode PCFactorSetMatSolverType(PC pc,MatSolverType stype)
416: {
421: PetscTryMethod(pc,"PCFactorSetMatSolverType_C",(PC,MatSolverType),(pc,stype));
422: return(0);
423: }
425: /*@C
426: PCFactorGetMatSolverType - gets the software that is used to perform the factorization
428: Not Collective
430: Input Parameter:
431: . pc - the preconditioner context
433: Output Parameter:
434: . stype - for example, superlu, superlu_dist (NULL if the PC does not have a solver package)
436: Level: intermediate
438: .seealso: MatGetFactor(), MatSolverType, PCFactorGetMatSolverType()
439: @*/
440: PetscErrorCode PCFactorGetMatSolverType(PC pc,MatSolverType *stype)
441: {
442: PetscErrorCode ierr,(*f)(PC,MatSolverType*);
446: PetscObjectQueryFunction((PetscObject)pc,"PCFactorGetMatSolverType_C",&f);
447: if (f) {
448: (*f)(pc,stype);
449: } else {
450: *stype = NULL;
451: }
452: return(0);
453: }
455: /*@
456: PCFactorSetFill - Indicate the amount of fill you expect in the factored matrix,
457: fill = number nonzeros in factor/number nonzeros in original matrix.
459: Not Collective, each process can expect a different amount of fill
461: Input Parameters:
462: + pc - the preconditioner context
463: - fill - amount of expected fill
465: Options Database Key:
466: . -pc_factor_fill <fill> - Sets fill amount
468: Level: intermediate
470: Note:
471: For sparse matrix factorizations it is difficult to predict how much
472: fill to expect. By running with the option -info PETSc will print the
473: actual amount of fill used; allowing you to set the value accurately for
474: future runs. Default PETSc uses a value of 5.0
476: This parameter has NOTHING to do with the levels-of-fill of ILU(). That is set with PCFactorSetLevels() or -pc_factor_levels.
478: @*/
479: PetscErrorCode PCFactorSetFill(PC pc,PetscReal fill)
480: {
485: if (fill < 1.0) SETERRQ(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_OUTOFRANGE,"Fill factor cannot be less then 1.0");
486: PetscTryMethod(pc,"PCFactorSetFill_C",(PC,PetscReal),(pc,fill));
487: return(0);
488: }
490: /*@
491: PCFactorSetUseInPlace - Tells the system to do an in-place factorization.
492: For dense matrices, this enables the solution of much larger problems.
493: For sparse matrices the factorization cannot be done truly in-place
494: so this does not save memory during the factorization, but after the matrix
495: is factored, the original unfactored matrix is freed, thus recovering that
496: space. For ICC(0) and ILU(0) with the default natural ordering the factorization is done efficiently in-place.
498: Logically Collective on PC
500: Input Parameters:
501: + pc - the preconditioner context
502: - flg - PETSC_TRUE to enable, PETSC_FALSE to disable
504: Options Database Key:
505: . -pc_factor_in_place <true,false>- Activate/deactivate in-place factorization
507: Notes:
508: PCFactorSetUseInplace() can only be used with the KSP method KSPPREONLY or when
509: a different matrix is provided for the multiply and the preconditioner in
510: a call to KSPSetOperators().
511: This is because the Krylov space methods require an application of the
512: matrix multiplication, which is not possible here because the matrix has
513: been factored in-place, replacing the original matrix.
515: Level: intermediate
517: .seealso: PCFactorGetUseInPlace()
518: @*/
519: PetscErrorCode PCFactorSetUseInPlace(PC pc,PetscBool flg)
520: {
525: PetscTryMethod(pc,"PCFactorSetUseInPlace_C",(PC,PetscBool),(pc,flg));
526: return(0);
527: }
529: /*@
530: PCFactorGetUseInPlace - Determines if an in-place factorization is being used.
532: Logically Collective on PC
534: Input Parameter:
535: . pc - the preconditioner context
537: Output Parameter:
538: . flg - PETSC_TRUE to enable, PETSC_FALSE to disable
540: Level: intermediate
542: .seealso: PCFactorSetUseInPlace()
543: @*/
544: PetscErrorCode PCFactorGetUseInPlace(PC pc,PetscBool *flg)
545: {
550: PetscUseMethod(pc,"PCFactorGetUseInPlace_C",(PC,PetscBool*),(pc,flg));
551: return(0);
552: }
554: /*@C
555: PCFactorSetMatOrderingType - Sets the ordering routine (to reduce fill) to
556: be used in the LU, ILU, Cholesky, and ICC factorizations.
558: Logically Collective on PC
560: Input Parameters:
561: + pc - the preconditioner context
562: - ordering - the matrix ordering name, for example, MATORDERINGND or MATORDERINGRCM
564: Options Database Key:
565: . -pc_factor_mat_ordering_type <nd,rcm,...,external> - Sets ordering routine
567: Level: intermediate
569: Notes:
570: nested dissection is used by default
572: For Cholesky and ICC and the SBAIJ format the only reordering available is natural since only the upper half of the matrix is stored
573: and reordering this matrix is very expensive.
575: You can use SeqAIJ matrix with Cholesky and ICC and use any ordering
577: external means PETSc will not compute an ordering and the package will use its own ordering, for MATSOLVERCHOLMOD and MATSOLVERUMFPACK
579: .seealso: MatOrderingType
581: @*/
582: PetscErrorCode PCFactorSetMatOrderingType(PC pc,MatOrderingType ordering)
583: {
588: PetscTryMethod(pc,"PCFactorSetMatOrderingType_C",(PC,MatOrderingType),(pc,ordering));
589: return(0);
590: }
592: /*@
593: PCFactorSetColumnPivot - Determines when column pivoting is done during matrix factorization.
594: For PETSc dense matrices column pivoting is always done, for PETSc sparse matrices
595: it is never done. For the MATLAB and SuperLU factorization this is used.
597: Logically Collective on PC
599: Input Parameters:
600: + pc - the preconditioner context
601: - dtcol - 0.0 implies no pivoting, 1.0 complete pivoting (slower, requires more memory but more stable)
603: Options Database Key:
604: . -pc_factor_pivoting <dtcol>
606: Level: intermediate
608: .seealso: PCILUSetMatOrdering(), PCFactorSetPivotInBlocks()
609: @*/
610: PetscErrorCode PCFactorSetColumnPivot(PC pc,PetscReal dtcol)
611: {
617: PetscTryMethod(pc,"PCFactorSetColumnPivot_C",(PC,PetscReal),(pc,dtcol));
618: return(0);
619: }
621: /*@
622: PCFactorSetPivotInBlocks - Determines if pivoting is done while factoring each block
623: with BAIJ or SBAIJ matrices
625: Logically Collective on PC
627: Input Parameters:
628: + pc - the preconditioner context
629: - pivot - PETSC_TRUE or PETSC_FALSE
631: Options Database Key:
632: . -pc_factor_pivot_in_blocks <true,false>
634: Level: intermediate
636: .seealso: PCILUSetMatOrdering(), PCFactorSetColumnPivot()
637: @*/
638: PetscErrorCode PCFactorSetPivotInBlocks(PC pc,PetscBool pivot)
639: {
645: PetscTryMethod(pc,"PCFactorSetPivotInBlocks_C",(PC,PetscBool),(pc,pivot));
646: return(0);
647: }
649: /*@
650: PCFactorSetReuseFill - When matrices with different nonzero structure are factored,
651: this causes later ones to use the fill ratio computed in the initial factorization.
653: Logically Collective on PC
655: Input Parameters:
656: + pc - the preconditioner context
657: - flag - PETSC_TRUE to reuse else PETSC_FALSE
659: Options Database Key:
660: . -pc_factor_reuse_fill - Activates PCFactorSetReuseFill()
662: Level: intermediate
664: .seealso: PCFactorSetReuseOrdering()
665: @*/
666: PetscErrorCode PCFactorSetReuseFill(PC pc,PetscBool flag)
667: {
673: PetscTryMethod(pc,"PCFactorSetReuseFill_C",(PC,PetscBool),(pc,flag));
674: return(0);
675: }
677: PetscErrorCode PCFactorInitialize(PC pc)
678: {
680: PC_Factor *fact = (PC_Factor*)pc->data;
683: MatFactorInfoInitialize(&fact->info);
684: fact->info.shifttype = (PetscReal)MAT_SHIFT_NONE;
685: fact->info.shiftamount = 100.0*PETSC_MACHINE_EPSILON;
686: fact->info.zeropivot = 100.0*PETSC_MACHINE_EPSILON;
687: fact->info.pivotinblocks = 1.0;
688: pc->ops->getfactoredmatrix = PCFactorGetMatrix_Factor;
690: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetZeroPivot_C",PCFactorSetZeroPivot_Factor);
691: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetZeroPivot_C",PCFactorGetZeroPivot_Factor);
692: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetShiftType_C",PCFactorSetShiftType_Factor);
693: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetShiftType_C",PCFactorGetShiftType_Factor);
694: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetShiftAmount_C",PCFactorSetShiftAmount_Factor);
695: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetShiftAmount_C",PCFactorGetShiftAmount_Factor);
696: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetMatSolverType_C",PCFactorGetMatSolverType_Factor);
697: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetMatSolverType_C",PCFactorSetMatSolverType_Factor);
698: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetUpMatSolverType_C",PCFactorSetUpMatSolverType_Factor);
699: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetFill_C",PCFactorSetFill_Factor);
700: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetMatOrderingType_C",PCFactorSetMatOrderingType_Factor);
701: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetLevels_C",PCFactorSetLevels_Factor);
702: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetLevels_C",PCFactorGetLevels_Factor);
703: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetAllowDiagonalFill_C",PCFactorSetAllowDiagonalFill_Factor);
704: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetAllowDiagonalFill_C",PCFactorGetAllowDiagonalFill_Factor);
705: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetPivotInBlocks_C",PCFactorSetPivotInBlocks_Factor);
706: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetUseInPlace_C",PCFactorSetUseInPlace_Factor);
707: PetscObjectComposeFunction((PetscObject)pc,"PCFactorGetUseInPlace_C",PCFactorGetUseInPlace_Factor);
708: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetReuseOrdering_C",PCFactorSetReuseOrdering_Factor);
709: PetscObjectComposeFunction((PetscObject)pc,"PCFactorSetReuseFill_C",PCFactorSetReuseFill_Factor);
710: return(0);
711: }