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





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


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

```none
            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

```none
            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
 `Mat`, `MatCreateSubMatrices()`, `MatCreateSubMatricesMPI()`, `MatCreateSubMatrixVirtual()`, `MatSubMatrixVirtualUpdate()`

## Level
advanced

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/interface/matrix.c.html#MatCreateSubMatrix">src/mat/interface/matrix.c</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex49.c.html">src/ksp/ksp/tutorials/ex49.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex59.c.html">src/ksp/ksp/tutorials/ex59.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/tutorials/ex64.c.html">src/ksp/ksp/tutorials/ex64.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/snes/tutorials/ex73f90t.F90.html">src/snes/tutorials/ex73f90t.F90.html</A><BR>

## Implementations

<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/aij/mpi/mpiaij.c.html#MatCreateSubMatrix_MPIAIJ">MatCreateSubMatrix_MPIAIJ in src/mat/impls/aij/mpi/mpiaij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/aij/seq/aij.c.html#MatCreateSubMatrix_SeqAIJ">MatCreateSubMatrix_SeqAIJ in src/mat/impls/aij/seq/aij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/baij/mpi/mpibaij.c.html#MatCreateSubMatrix_MPIBAIJ">MatCreateSubMatrix_MPIBAIJ in src/mat/impls/baij/mpi/mpibaij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/baij/seq/baij2.c.html#MatCreateSubMatrix_SeqBAIJ">MatCreateSubMatrix_SeqBAIJ in src/mat/impls/baij/seq/baij2.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/blockmat/seq/blockmat.c.html#MatCreateSubMatrix_BlockMat">MatCreateSubMatrix_BlockMat in src/mat/impls/blockmat/seq/blockmat.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/dense/mpi/mpidense.c.html#MatCreateSubMatrix_MPIDense">MatCreateSubMatrix_MPIDense in src/mat/impls/dense/mpi/mpidense.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/dense/seq/dense.c.html#MatCreateSubMatrix_SeqDense">MatCreateSubMatrix_SeqDense in src/mat/impls/dense/seq/dense.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/is/matis.c.html#MatCreateSubMatrix_IS">MatCreateSubMatrix_IS in src/mat/impls/is/matis.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/kaij/kaij.c.html#MatCreateSubMatrix_KAIJ">MatCreateSubMatrix_KAIJ in src/mat/impls/kaij/kaij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/maij/maij.c.html#MatCreateSubMatrix_MAIJ">MatCreateSubMatrix_MAIJ in src/mat/impls/maij/maij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/nest/matnest.c.html#MatCreateSubMatrix_Nest">MatCreateSubMatrix_Nest in src/mat/impls/nest/matnest.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/sbaij/mpi/mpisbaij.c.html#MatCreateSubMatrix_MPISBAIJ">MatCreateSubMatrix_MPISBAIJ in src/mat/impls/sbaij/mpi/mpisbaij.c</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/mat/impls/sbaij/seq/sbaij2.c.html#MatCreateSubMatrix_SeqSBAIJ">MatCreateSubMatrix_SeqSBAIJ in src/mat/impls/sbaij/seq/sbaij2.c</A><BR>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/mat/interface/matrix.c)


[Index of all Mat routines](index.md)  
[Table of Contents for all manual pages](/docs/manualpages/index.md)  
[Index of all manual pages](/docs/manualpages/singleindex.md)  
