Skip to main content
`Ctrl`+`K`

# MatCreateSubMatrix

Gets a single submatrix on the same number of processors as the original matrix.

## Synopsis

    #include "petscmat.h"
    PetscErrorCode MatCreateSubMatrix(Mat mat, IS isrow, IS iscol, MatReuse cll, Mat *newmat)

Collective

## Input Parameters

- mat - the original matrix

- isrow - parallel `IS` containing the rows this processor should obtain

- iscol - parallel `IS` containing all columns you wish to keep. Each process should list the columns that will be in IT’s “diagonal part” in the new matrix.

- cll - either `MAT_INITIAL_MATRIX` or `MAT_REUSE_MATRIX`

## Output Parameter

- newmat - the new submatrix, of the same type as the original matrix

## Notes

The submatrix will be able to be multiplied with vectors using the same layout as `iscol`.

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. For `MATBAIJ` and `MATSBAIJ` matrices the indices must include all rows/columns of a block; for example, if the block size is 3 one cannot select the 0 and 2 rows without selecting the 1 row.

The index sets may not have duplicate entries.

The first time this is called you should use a cll of `MAT_INITIAL_MATRIX`, the `MatCreateSubMatrix()` routine will create the newmat for you. Any additional calls to this routine with a mat of the same nonzero structure and with a call of `MAT_REUSE_MATRIX` will reuse the matrix generated the first time. You should call `MatDestroy()` on `newmat` when you are finished using it.

The communicator of the newly obtained matrix is ALWAYS the same as the communicator of the input matrix.

If `iscol` is `NULL` then all columns are obtained (not supported in Fortran).

If `isrow` and `iscol` have a nontrivial block-size, then the resulting matrix has this block-size as well. This feature is used by `PCFIELDSPLIT` to allow easy nesting of its use.

## Example usage

Consider the following 8x8 matrix with 34 non-zero values, that is assembled across 3 processors. Let’s assume that proc0 owns 3 rows, proc1 owns 3 rows, proc2 owns 2 rows. This division can be shown as follows

                1  2  0  |  0  3  0  |  0  4
        Proc0   0  5  6  |  7  0  0  |  8  0
                9  0 10  | 11  0  0  | 12  0
        -------------------------------------
               13  0 14  | 15 16 17  |  0  0
        Proc1   0 18  0  | 19 20 21  |  0  0
                0  0  0  | 22 23  0  | 24  0
        -------------------------------------
        Proc2  25 26 27  |  0  0 28  | 29  0
               30  0  0  | 31 32 33  |  0 34

Suppose `isrow` = [0 1 | 4 | 6 7] and `iscol` = [1 2 | 3 4 5 | 6]. The resulting submatrix is

                2  0  |  0  3  0  |  0
        Proc0   5  6  |  7  0  0  |  8
        -------------------------------
        Proc1  18  0  | 19 20 21  |  0
        -------------------------------
        Proc2  26 27  |  0  0 28  | 29
                0  0  | 31 32 33  |  0

## See Also

Matrices, `Mat`, `MatCreateSubMatrices()`, `MatCreateSubMatricesMPI()`, `MatCreateSubMatrixVirtual()`, `MatSubMatrixVirtualUpdate()`

## Level

advanced

## Location

src/mat/interface/matrix.c

## Examples

src/ksp/ksp/tutorials/ex59.c
src/ksp/ksp/tutorials/ex49.c
src/ksp/ksp/tutorials/ex19.c
src/ksp/ksp/tutorials/ex64.c
src/ksp/pc/tutorials/ex4.c
src/snes/tutorials/ex73f90t.F90

## Implementations

MatCreateSubMatrix_MPIAIJ() in src/mat/impls/aij/mpi/mpiaij.c
MatCreateSubMatrix_SeqAIJ() in src/mat/impls/aij/seq/aij.c
MatCreateSubMatrix_MPIBAIJ() in src/mat/impls/baij/mpi/mpibaij.c
MatCreateSubMatrix_SeqBAIJ() in src/mat/impls/baij/seq/baij2.c
MatCreateSubMatrix_BlockMat() in src/mat/impls/blockmat/seq/blockmat.c
MatCreateSubMatrix_MPIDense() in src/mat/impls/dense/mpi/mpidense.c
MatCreateSubMatrix_SeqDense() in src/mat/impls/dense/seq/dense.c
MatCreateSubMatrix_IS() in src/mat/impls/is/matis.c
MatCreateSubMatrix_KAIJ() in src/mat/impls/kaij/kaij.c
MatCreateSubMatrix_MAIJ() in src/mat/impls/maij/maij.c
MatCreateSubMatrix_Nest() in src/mat/impls/nest/matnest.c
MatCreateSubMatrix_MPISBAIJ() in src/mat/impls/sbaij/mpi/mpisbaij.c
MatCreateSubMatrix_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