MatGetRow — PETSc 3.21.4 documentation

Skip to main content
`Ctrl`+`K`

# MatGetRow

Gets a row of a matrix. You MUST call `MatRestoreRow()` for each row that you get to ensure that your application does not bleed memory.

## Synopsis

    #include "petscmat.h"
    PetscErrorCode MatGetRow(Mat mat, PetscInt row, PetscInt *ncols, const PetscInt *cols[], const PetscScalar *vals[])

Not Collective

## Input Parameters

- mat - the matrix

- row - the row to get

## Output Parameters

- ncols - if not `NULL`, the number of nonzeros in `row`

- cols - if not `NULL`, the column numbers

- vals - if not `NULL`, the numerical values

## Notes

This routine is provided for people who need to have direct access to the structure of a matrix. We hope that we provide enough high-level matrix routines that few users will need it.

`MatGetRow()` always returns 0-based column indices, regardless of whether the internal representation is 0-based (default) or 1-based.

For better efficiency, set `cols` and/or `vals` to `NULL` if you do not wish to extract these quantities.

The user can only examine the values extracted with `MatGetRow()`; the values CANNOT be altered. To change the matrix entries, one must use `MatSetValues()`.

You can only have one call to `MatGetRow()` outstanding for a particular matrix at a time, per processor. `MatGetRow()` can only obtain rows associated with the given processor, it cannot get rows from the other processors; for that we suggest using `MatCreateSubMatrices()`, then `MatGetRow()` on the submatrix. The row index passed to `MatGetRow()` is in the global number of rows.

Use `MatGetRowIJ()` and `MatRestoreRowIJ()` to access all the local indices of the sparse matrix.

Use `MatSeqAIJGetArray()` and similar functions to access the numerical values for certain matrix types directly.

## Fortran Note

The calling sequence is

       MatGetRow(matrix,row,ncols,cols,values,ierr)
             Mat     matrix (input)
             integer row    (input)
             integer ncols  (output)
             integer cols(maxcols) (output)
             double precision (or double complex) values(maxcols) output

where maxcols >= maximum nonzeros in any row of the matrix.

## See Also

Matrices, `Mat`, `MatRestoreRow()`, `MatSetValues()`, `MatGetValues()`, `MatCreateSubMatrices()`, `MatGetDiagonal()`, `MatGetRowIJ()`, `MatRestoreRowIJ()`

## Level

advanced

## Location

src/mat/interface/matrix.c

## Examples

src/mat/tutorials/ex12.c
src/mat/tutorials/ex16.c
src/ksp/ksp/tutorials/ex59.c

## Implementations

MatGetRow_MPIAdj() in src/mat/impls/adj/mpi/mpiadj.c
MatGetRow_MPIAIJ() in src/mat/impls/aij/mpi/mpiaij.c
MatGetRow_SeqAIJ() in src/mat/impls/aij/seq/aij.c
MatGetRow_MPIBAIJ() in src/mat/impls/baij/mpi/mpibaij.c
MatGetRow_SeqBAIJ() in src/mat/impls/baij/seq/baij.c
MatGetRow_ConstantDiagonal() in src/mat/impls/cdiagonal/cdiagonal.c
MatGetRow_MPIDense() in src/mat/impls/dense/mpi/mpidense.c
MatGetRow_SeqDense() in src/mat/impls/dense/seq/dense.c
MatGetRow_Diagonal() in src/mat/impls/diagonal/diagonal.c
MatGetRow_Htool() in src/mat/impls/htool/htool.cxx
MatGetRow_HYPRE() in src/mat/impls/hypre/mhypre.c
MatGetRow_SeqKAIJ() in src/mat/impls/kaij/kaij.c
MatGetRow_MPIKAIJ() in src/mat/impls/kaij/kaij.c
MatGetRow_MPISBAIJ() in src/mat/impls/sbaij/mpi/mpisbaij.c
MatGetRow_SeqSBAIJ() in src/mat/impls/sbaij/seq/sbaij.c
MatGetRow_SeqSELL() in src/mat/impls/sell/seq/sell.c

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