Skip to main content
`Ctrl`+`K`

# 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