Skip to main content
`Ctrl`+`K`

# MatGetFactor

Returns a matrix suitable to calls to MatXXFactorSymbolic,Numeric()

## 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`, `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 <bool> - do mat factorization on host (with device matrices). Default is doing it on device

- -pc_factor_mat_solve_on_host <bool> - do mat solve on host (with device matrices). Default is doing it on device

## Notes

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.

Users usually access the factorization solvers via `KSP`

Some PETSc matrix formats have alternative solvers available that are contained in alternative packages such as pastix, superlu, mumps etc. PETSc must have been ./configure to use the external solver, using the option –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.

Some of the packages have options for controlling the factorization, these are in the form -prefix_mat_packagename_packageoption where prefix is normally obtained from the calling `KSP`/`PC`. If `MatGetFactor()` is called directly one can set call `MatSetOptionsPrefixFactor()` on the originating matrix or `MatSetOptionsPrefix()` on the resulting factor matrix.

## Developer Note

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

## 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()`

## 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