MatGetFactor

Returns a matrix suitable to calls to routines such as MatLUFactorSymbolic(), MatCholeskyFactorSymbolic(), MatILUFactorSymbolic(), MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactorNumeric(), MatILUFactorNumeric(), and MatICCFactorNumeric()

Synopsis

#include "petscmat.h" 
PetscErrorCode MatGetFactor(Mat mat, MatSolverType type, MatFactorType ftype, Mat *f)

Collective

Input Parameters

• mat - the matrix

• type - name of solver type, for example, superlu_dist, petsc (to use PETSc’s solver if it is available), if this is ‘NULL’, then the first result that satisfies the other criteria is returned

• ftype - factor type, MAT_FACTOR_LU, MAT_FACTOR_CHOLESKY, MAT_FACTOR_ICC, MAT_FACTOR_ILU, MAT_FACTOR_QR

Output Parameter

• f - the factor matrix used with MatXXFactorSymbolic,Numeric() calls. Can be NULL in some cases, see notes below.

Options Database Keys

• -pc_factor_mat_solver_type type - choose the type at run time. When using KSP solvers

• -pc_factor_mat_factor_on_host (true|false) - do matrix factorization on host (with device matrices). Default is doing it on device

• -pc_factor_mat_solve_on_host (true|false) - do matrix solve on host (with device matrices). Default is doing it on device

Notes

Some of the packages, such as MUMPS, have options for controlling the factorization, these are in the form -prefix_mat_packagename_packageoption (for example, -mat_mumps_icntl_6 1) where prefix is normally set automatically from the calling KSP/PC. If MatGetFactor() is called directly, without using a PC, one can set the prefix by calling MatSetOptionsPrefixFactor() on the originating matrix or MatSetOptionsPrefix() on the resulting factor matrix.

Some PETSc matrix formats have alternative solvers available that are provided by alternative packages such as PaStiX, SuperLU_DIST, MUMPS etc. PETSc must have been configured to use the external solver, using the corresponding ./configure option such as --download-package or --with-package-dir.

When type is NULL the available results are searched for based on the order of the calls to MatSolverTypeRegister() in MatInitializePackage(). Since different PETSc configurations may have different external solvers, seemingly identical runs with different PETSc configurations may use a different solver. For example if one configuration had --download-mumps while a different one had --download-superlu_dist.

The return matrix can be NULL if the requested factorization is not available, since some combinations of matrix types and factorization types registered with MatSolverTypeRegister() cannot be fully tested if not at runtime.

Developer Note

This should actually be called MatCreateFactor() since it creates a new factor object

The MatGetFactor() implementations should not be accessing the PETSc options database or making other decisions about solver options, that should be delayed until the later operations. This is to ensure the correct options prefix has been set in the factor matrix.

See Also

Matrices, Mat, Matrix Factorization, KSP, MatSolverType, MatFactorType, MatCopy(), MatDuplicate(), MatGetFactorAvailable(), MatFactorGetCanUseOrdering(), MatSolverTypeRegister(), MatSolverTypeGet(), MAT_FACTOR_LU, MAT_FACTOR_CHOLESKY, MAT_FACTOR_ICC, MAT_FACTOR_ILU, MAT_FACTOR_QR, MatInitializePackage(), MatLUFactorSymbolic(), MatCholeskyFactorSymbolic(), MatILUFactorSymbolic(), MatICCFactorSymbolic(), MatLUFactorNumeric(), MatCholeskyFactorNumeric(), MatILUFactorNumeric(), MatICCFactorNumeric()

Level

intermediate

Location

src/mat/interface/matrix.c

Implementations

MatGetFactor_pastix() in src/mat/impls/aij/mpi/pastix/pastix.c
MatGetFactor_HT() in src/mat/impls/transpose/htransm.c
MatGetFactor_Transpose() in src/mat/impls/transpose/transm.c

---

Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages