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, nonsorted input.

Synopsis

#include "petscmat.h" 
int MatSetOption(Mat mat,MatOption op)
Collective on Mat

Input Parameters

mat - the matrix
option - the option, one of those listed below (and possibly others), e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR

Options Describing Matrix Structure

MAT_SYMMETRIC - symmetric in terms of both structure and value
MAT_STRUCTURALLY_SYMMETRIC - symmetric nonzero structure

Options For Use with MatSetValues()

Insert a logically dense subblock, which can be
MAT_ROW_ORIENTED - row-oriented (default)
MAT_COLUMN_ORIENTED - column-oriented
MAT_ROWS_SORTED - sorted by row
MAT_ROWS_UNSORTED - not sorted by row (default)
MAT_COLUMNS_SORTED - sorted by column
MAT_COLUMNS_UNSORTED - not sorted by column (default)

Not 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_NO_NEW_NONZERO_LOCATIONS - additional insertions will not be allowed if they generate a new nonzero
MAT_YES_NEW_NONZERO_LOCATIONS - additional insertions will be allowed
MAT_NO_NEW_DIAGONALS - additional insertions will not be allowed if they generate a nonzero in a new diagonal (for block diagonal format only)
MAT_YES_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

Notes

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_NO_NEW_NONZERO_LOCATIONS 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()

MAT_NEW_NONZERO_LOCATION_ERR 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.) This is a useful flag when using SAME_NONZERO_PATTERN in calling SLESSetOperators() to ensure that the nonzero pattern truely does remain unchanged. Set after the first MatAssemblyEnd()

MAT_NEW_NONZERO_ALLOCATION_ERR 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.

MAT_IGNORE_OFF_PROC_ENTRIES 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_NO_NEW_NONZERO_LOCATIONS flag should be used with MAT_USE_HASH_TABLE flag. This option is currently supported by MATMPIBAIJ format only.

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

MAT_IGNORE_ZERO_ENTRIES - when using ADD_VALUES for AIJ 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 and ROWBS matrix types

MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works with AIJ and ROWBS matrix types

Level:intermediate
Location:
src/mat/interface/matrix.c
Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages

Examples

src/sles/examples/tutorials/ex5.c.html
src/sles/examples/tutorials/ex9.c.html
src/snes/examples/tutorials/ex5.c.html
src/snes/examples/tutorials/ex14.c.html
src/snes/examples/tutorials/ex5f90.F.html
src/ts/examples/tutorials/ex2.c.html
src/ts/examples/tutorials/ex3.c.html
src/ts/examples/tutorials/ex4.c.html
src/ts/examples/tutorials/ex5.c.html
src/ts/examples/tutorials/ex2f.F.html