MatCreateSubMatrices — PETSc 3.21.4 documentation

Skip to main content
`Ctrl`+`K`

# MatCreateSubMatrices

Extracts several submatrices from a matrix. If submat points to an array of valid matrices, they may be reused to store the new submatrices.

## Synopsis

    #include "petscmat.h"
    PetscErrorCode MatCreateSubMatrices(Mat mat, PetscInt n, const IS irow[], const IS icol[], MatReuse scall, Mat *submat[])

Collective

## Input Parameters

- mat - the matrix

- n - the number of submatrixes to be extracted (on this processor, may be zero)

- irow - index set of rows to extract

- icol - index set of columns to extract

- scall - either `MAT_INITIAL_MATRIX` or `MAT_REUSE_MATRIX`

## Output Parameter

- submat - the array of submatrices

## Notes

`MatCreateSubMatrices()` can extract ONLY sequential submatrices (from both sequential and parallel matrices). Use `MatCreateSubMatrix()` to extract a parallel submatrix.

Some matrix types place restrictions on the row and column indices, such as that they be sorted or that they be equal to each other.

The index sets may not have duplicate entries.

When extracting submatrices from a parallel matrix, each processor can form a different submatrix by setting the rows and columns of its individual index sets according to the local submatrix desired.

When finished using the submatrices, the user should destroy them with `MatDestroySubMatrices()`.

`MAT_REUSE_MATRIX` can only be used when the nonzero structure of the original matrix has not changed from that last call to `MatCreateSubMatrices()`.

This routine creates the matrices in submat; you should NOT create them before calling it. It also allocates the array of matrix pointers submat.

For `MATBAIJ` matrices the index sets must respect the block structure, that is if they request one row/column in a block, they must request all rows/columns that are in that block. For example, if the block size is 2 you cannot request just row 0 and column 0.

## Fortran Note

One must pass in as `submat` a `Mat` array of size at least `n`+1.

## See Also

Matrices, `Mat`, `MatDestroySubMatrices()`, `MatCreateSubMatrix()`, `MatGetRow()`, `MatGetDiagonal()`, `MatReuse`

## Level

advanced

## Location

src/mat/interface/matrix.c

## Implementations

MatCreateSubMatrices_MPIAdj() in src/mat/impls/adj/mpi/mpiadj.c
MatCreateSubMatrices_MPIAIJ() in src/mat/impls/aij/mpi/mpiov.c
MatCreateSubMatrices_SeqAIJ() in src/mat/impls/aij/seq/aij.c
MatCreateSubMatrices_MPIBAIJ() in src/mat/impls/baij/mpi/baijov.c
MatCreateSubMatrices_SeqBAIJ() in src/mat/impls/baij/seq/baij2.c
MatCreateSubMatrices_ConstantDiagonal() in src/mat/impls/cdiagonal/cdiagonal.c
MatCreateSubMatrices_MPIDense() in src/mat/impls/dense/mpi/mmdense.c
MatCreateSubMatrices_SeqDense() in src/mat/impls/dense/seq/dense.c
MatCreateSubMatrices_Htool() in src/mat/impls/htool/htool.cxx
MatCreateSubMatrices_IS() in src/mat/impls/is/matis.c
MatCreateSubMatrices_MAIJ() in src/mat/impls/maij/maij.c
MatCreateSubMatrices_Normal() in src/mat/impls/normal/normm.c
MatCreateSubMatrices_NormalHermitian() in src/mat/impls/normal/normmh.c
MatCreateSubMatrices_MPISBAIJ() in src/mat/impls/sbaij/mpi/mpisbaij.c
MatCreateSubMatrices_SeqSBAIJ() in src/mat/impls/sbaij/seq/sbaij2.c

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