petsc-master 2020-10-26
Report Typos and Errors

# MatStoreValues

Stashes a copy of the matrix values; this allows, for example, reuse of the linear part of a Jacobian, while recomputing the nonlinear portion.

### Synopsis

```#include "petscmat.h"
PetscErrorCode  MatStoreValues(Mat mat)
```
Collect on Mat

### Input Parameters

 mat - the matrix (currently only AIJ matrices support this option)

### Common Usage, with SNESSolve()

```   Create Jacobian matrix
```
```   Set linear terms into matrix
```
```   Apply boundary conditions to matrix, at this time matrix must have
```
```     final nonzero structure (i.e. setting the nonlinear terms and applying
```
```     boundary conditions again will not change the nonzero structure
```
```   ierr = MatSetOption(mat,MAT_NEW_NONZERO_LOCATIONS,PETSC_FALSE);
```
```   ierr = MatStoreValues(mat);
```
```   Call SNESSetJacobian() with matrix
```
```   In your Jacobian routine
```
```     ierr = MatRetrieveValues(mat);
```
```     Set nonlinear terms in matrix
```

### Common Usage without SNESSolve(), i.e. when you handle nonlinear solve yourself

```   // build linear portion of Jacobian
```
```   ierr = MatSetOption(mat,MAT_NEW_NONZERO_LOCATIONS,PETSC_FALSE);
```
```   ierr = MatStoreValues(mat);
```
```   loop over nonlinear iterations
```
```      ierr = MatRetrieveValues(mat);
```
```      // call MatSetValues(mat,...) to set nonliner portion of Jacobian
```
```      // call MatAssemblyBegin/End() on matrix
```
```      Solve linear system with Jacobian
```
```   endloop
```

### Notes

Matrix must already be assemblied before calling this routine Must set the matrix option MatSetOption(mat,MAT_NEW_NONZERO_LOCATIONS,PETSC_FALSE); before calling this routine.

When this is called multiple times it overwrites the previous set of stored values and does not allocated additional space.

MatRetrieveValues()

### Location

src/mat/impls/aij/seq/aij.c

### Implementations

MatStoreValues_MPIAIJ in src/mat/impls/aij/mpi/mpiaij.c
MatStoreValues_SeqAIJ in src/mat/impls/aij/seq/aij.c
MatStoreValues_MPIBAIJ in src/mat/impls/baij/mpi/mpibaij.c
MatStoreValues_SeqBAIJ in src/mat/impls/baij/seq/baij.c
MatStoreValues_MPISBAIJ in src/mat/impls/sbaij/mpi/mpisbaij.c
MatStoreValues_SeqSBAIJ in src/mat/impls/sbaij/seq/sbaij.c
MatStoreValues_MPISELL in src/mat/impls/sell/mpi/mpisell.c
MatStoreValues_SeqSELL in src/mat/impls/sell/seq/sell.c

Index of all Mat routines