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: }