petsc-3.12.4 2020-02-04
Report Typos and Errors

# MatSetOption

Sets a parameter option for a matrix. Some options may be specific to certain storage formats. Some options determine how values will be inserted (or added). Sorted, row-oriented input will generally assemble the fastest. The default is row-oriented.

### Synopsis

    #include "petscmat.h"
    PetscErrorCode MatSetOption(Mat mat,MatOption op,PetscBool flg)

Logically Collective on Mat for certain operations, such as MAT_SPD, not collective for MAT_ROW_ORIENTED, see MatOption

### Input Parameters

| mat | - the matrix
| option | - the option, one of those listed below (and possibly others),
| flg | - turn the option on (PETSC_TRUE) or off (PETSC_FALSE)

### Options Describing Matrix Structure

| MAT_SPD | - symmetric positive definite
| MAT_SYMMETRIC | - symmetric in terms of both structure and value
| MAT_HERMITIAN | - transpose is the complex conjugation
| MAT_STRUCTURALLY_SYMMETRIC | - symmetric nonzero structure
| MAT_SYMMETRY_ETERNAL | - if you would like the symmetry/Hermitian flag you set to be kept with all future use of the matrix including after MatAssemblyBegin/End() which could potentially change the symmetry structure, i.e. you KNOW the matrix will ALWAYS have the property you set.

### Options For Use with MatSetValues()

Insert a logically dense subblock, which can be
MAT_ROW_ORIENTED -row-oriented (default)

Note these options reflect the data you pass in with MatSetValues(); it has nothing to do with how the data is stored internally in the matrix data structure.

When (re)assembling a matrix, we can restrict the input for

### efficiency/debugging purposes. These options include

| MAT_NEW_NONZERO_LOCATIONS | - additional insertions will be allowed if they generate a new nonzero (slow)
| MAT_NEW_DIAGONALS | - new diagonals will be allowed (for block diagonal format only)
| MAT_IGNORE_OFF_PROC_ENTRIES | - drops off-processor entries
| MAT_NEW_NONZERO_LOCATION_ERR | - generates an error for new matrix entry
| MAT_USE_HASH_TABLE | - uses a hash table to speed up matrix assembly
| MAT_NO_OFF_PROC_ENTRIES | - you know each process will only set values for its own rows, will generate an error if any process sets values for another process. This avoids all reductions in the MatAssembly routines and thus improves performance for very large process counts.
| MAT_SUBSET_OFF_PROC_ENTRIES | - you know that the first assembly after setting this flag will set a superset of the off-process entries required for all subsequent assemblies. This avoids a rendezvous step in the MatAssembly functions, instead sending only neighbor messages.

### Notes

Except for MAT_UNUSED_NONZERO_LOCATION_ERR and MAT_ROW_ORIENTED all processes that share the matrix must pass the same value in flg!

Some options are relevant only for particular matrix types and are thus ignored by others. Other options are not supported by certain matrix types and will generate an error message if set.

If using a Fortran 77 module to compute a matrix, one may need to use the column-oriented option (or convert to the row-oriented format).

MAT_NEW_NONZERO_LOCATIONS set to PETSC_FALSE indicates that any add or insertion that would generate a new entry in the nonzero structure is instead ignored. Thus, if memory has not alredy been allocated for this particular data, then the insertion is ignored. For dense matrices, in which the entire array is allocated, no entries are ever ignored. Set after the first MatAssemblyEnd(). If this option is set then the MatAssemblyBegin/End() processes has one less global reduction

MAT_NEW_NONZERO_LOCATION_ERR set to PETSC_TRUE indicates that any add or insertion that would generate a new entry in the nonzero structure instead produces an error. (Currently supported for AIJ and BAIJ formats only.) If this option is set then the MatAssemblyBegin/End() processes has one less global reduction

MAT_NEW_NONZERO_ALLOCATION_ERR set to PETSC_TRUE indicates that any add or insertion that would generate a new entry that has not been preallocated will instead produce an error. (Currently supported for AIJ and BAIJ formats only.) This is a useful flag when debugging matrix memory preallocation. If this option is set then the MatAssemblyBegin/End() processes has one less global reduction

MAT_IGNORE_OFF_PROC_ENTRIES set to PETSC_TRUE indicates entries destined for other processors should be dropped, rather than stashed. This is useful if you know that the "owning" processor is also always generating the correct matrix entries, so that PETSc need not transfer duplicate entries generated on another processor.

MAT_USE_HASH_TABLE indicates that a hash table be used to improve the searches during matrix assembly. When this flag is set, the hash table is created during the first Matrix Assembly. This hash table is used the next time through, during MatSetVaules()/MatSetVaulesBlocked() to improve the searching of indices. MAT_NEW_NONZERO_LOCATIONS flag should be used with MAT_USE_HASH_TABLE flag. This option is currently supported by MATMPIBAIJ format only.

MAT_KEEP_NONZERO_PATTERN indicates when MatZeroRows() is called the zeroed entries are kept in the nonzero structure

MAT_IGNORE_ZERO_ENTRIES - for AIJ/IS matrices this will stop zero values from creating a zero location in the matrix

MAT_USE_INODES - indicates using inode version of the code - works with AIJ matrix types

MAT_NO_OFF_PROC_ZERO_ROWS - you know each process will only zero its own rows. This avoids all reductions in the zero row routines and thus improves performance for very large process counts.

MAT_IGNORE_LOWER_TRIANGULAR - For SBAIJ matrices will ignore any insertions you make in the lower triangular part of the matrix (since they should match the upper triangular part).

MAT_SORTED_FULL - each process provides exactly its local rows; all column indices for a given row are passed in a single call to MatSetValues(), preallocation is perfect, row oriented, INSERT_VALUES is used. Common with finite difference schemes with non-periodic boundary conditions.

### Notes

Can only be called after MatSetSizes() and MatSetType() have been set.

### See Also

MatOption, Mat

### Level

intermediate

### Location

src/mat/interface/matrix.c

### Examples

src/mat/examples/tutorials/ex4.c.html
src/mat/examples/tutorials/ex12.c.html
src/mat/examples/tutorials/ex16.c.html
src/mat/examples/tutorials/ex4f.F90.html
src/ksp/pc/examples/tutorials/ex3.c.html
src/ksp/ksp/examples/tutorials/ex2.c.html
src/ksp/ksp/examples/tutorials/ex4.c.html
src/ksp/ksp/examples/tutorials/ex5.c.html
src/ksp/ksp/examples/tutorials/ex6.c.html
src/ksp/ksp/examples/tutorials/ex9.c.html
src/ksp/ksp/examples/tutorials/ex18.c.html

### Implementations

MatSetOption_MPIAdj in src/mat/impls/adj/mpi/mpiadj.c
MatSetOption_MPIAIJ in src/mat/impls/aij/mpi/mpiaij.c
MatSetOption_SeqAIJ in src/mat/impls/aij/seq/aij.c
MatSetOption_SeqAIJ_Inode in src/mat/impls/aij/seq/inode2.c
MatSetOption_MPIBAIJ in src/mat/impls/baij/mpi/mpibaij.c
MatSetOption_SeqBAIJ in src/mat/impls/baij/seq/baij.c
MatSetOption_BlockMat in src/mat/impls/blockmat/seq/blockmat.c
MatSetOption_MPIDense in src/mat/impls/dense/mpi/mpidense.c
MatSetOption_SeqDense in src/mat/impls/dense/seq/dense.c
MatSetOption_Elemental in src/mat/impls/elemental/matelem.cxx
MatSetOption_HYPRE in src/mat/impls/hypre/mhypre.c
MatSetOption_IS in src/mat/impls/is/matis.c
MatSetOption_Preallocator in src/mat/impls/preallocator/matpreallocator.c
MatSetOption_MPISBAIJ in src/mat/impls/sbaij/mpi/mpisbaij.c
MatSetOption_SeqSBAIJ in src/mat/impls/sbaij/seq/sbaij.c
MatSetOption_MPISELL in src/mat/impls/sell/mpi/mpisell.c
MatSetOption_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