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 for certain operations, such as MAT_SPD
, not collective for MAT_ROW_ORIENTED
, see MatOption
Input Parameters#
mat - the matrix
op - 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 definiteMAT_SYMMETRIC
- symmetric in terms of both structure and valueMAT_HERMITIAN
- transpose is the complex conjugationMAT_STRUCTURALLY_SYMMETRIC
- symmetric nonzero structureMAT_SYMMETRY_ETERNAL
- indicates the symmetry (or Hermitian structure) or its absence will persist through any changes to the matrixMAT_STRUCTURAL_SYMMETRY_ETERNAL
- indicates the structural symmetry or its absence will persist through any changes to the matrixMAT_SPD_ETERNAL
- indicates the value ofMAT_SPD
(true or false) will persist through any changes to the matrix
These are not really options of the matrix, they are knowledge about the structure of the matrix that users may provide so that they do not need to be computed (usually at a high cost)
Options For Use with MatSetValues()
#
Insert a logically dense subblock, which can be
MAT_ROW_ORIENTED
- row-oriented (default)
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_FORCE_DIAGONAL_ENTRIES
- forces diagonal entries to be allocatedMAT_IGNORE_OFF_PROC_ENTRIES
- drops off-processor entriesMAT_NEW_NONZERO_LOCATION_ERR
- generates an error for new matrix entryMAT_USE_HASH_TABLE
- uses a hash table to speed up matrix assemblyMAT_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 Fortran 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 already 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()
/MatAssemblyEnd()
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 MATAIJ
and MATBAIJ
formats only.) If this option is set, then the MatAssemblyBegin()
/MatAssemblyEnd()
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 MATAIJ
and MATBAIJ
formats
only.) This is a useful flag when debugging matrix memory preallocation.
If this option is set, then the MatAssemblyBegin()
/MatAssemblyEnd()
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 MatSetValues()
/MatSetValuesBlocked()
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. This flag is not used for MatZeroRowsColumns()
MAT_IGNORE_ZERO_ENTRIES
- for MATAIJ
and MATIS
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 MATAIJ
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 MATSBAIJ
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.
Developer Note#
MAT_SYMMETRY_ETERNAL
, MAT_STRUCTURAL_SYMMETRY_ETERNAL
, and MAT_SPD_ETERNAL
are used by MatAssemblyEnd()
and in other
places where otherwise the value of MAT_SYMMETRIC
, MAT_STRUCTURALLY_SYMMETRIC
or MAT_SPD
would need to be changed back
to PETSC_BOOL3_UNKNOWN
because the matrix values had changed so the code cannot be certain that the related property had
not changed.
See Also#
Matrices, MatOption
, Mat
, MatGetOption()
Level#
intermediate
Location#
Examples#
src/tao/unconstrained/tutorials/burgers_spectral.c
src/tao/bound/tutorials/jbearing2.c
src/tao/unconstrained/tutorials/spectraladjointassimilation.c
src/tao/complementarity/tutorials/blackscholes.c
src/tao/bound/tutorials/plate2f.F90
src/tao/unconstrained/tutorials/rosenbrock1f.F90
src/tao/unconstrained/tutorials/minsurf1.c
src/tao/unconstrained/tutorials/minsurf2.c
src/tao/complementarity/tutorials/minsurf1.c
src/tao/bound/tutorials/plate2.c
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_SeqAIJKokkos() in src/mat/impls/aij/seq/kokkos/aijkok.kokkos.cxx
MatSetOption_SeqAIJCUSPARSE() in src/mat/impls/aij/seq/seqcusparse/aijcusparse.cu
MatSetOption_SeqAIJHIPSPARSE() in src/mat/impls/aij/seq/seqhipsparse/aijhipsparse.hip.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_ScaLAPACK() in src/mat/impls/scalapack/matscalapack.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