petsc-3.14.5 2021-03-03
Report Typos and Errors

# 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 the row
| cols | - if not NULL, the column numbers
| vals | - if not NULL, the 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.

### Fortran Notes

The calling sequence from Fortran 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.

### Caution

Do not try to change the contents of the output arrays (cols and vals). In some cases, this may corrupt the matrix.

### See Also

MatRestoreRow(), MatSetValues(), MatGetValues(), MatCreateSubMatrices(), MatGetDiagonal()

### Level

advanced

### Location

src/mat/interface/matrix.c

### Examples

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

### 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_private in src/mat/impls/baij/seq/baij.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_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