petsc-3.7.1 2016-05-15
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 Many br

Input Parameters

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

Options Describing Matrix Structure

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

Options For Use with MatSetValues()

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

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

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

efficiency/debugging purposes. These options include

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

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! Many br

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

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

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

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

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

MAT_IGNORE_OFF_PROC_ENTRIES set to PETSC_TRUE indicates entries destined for Many brother processors should be dropped, rather than stashed. Many brThis is useful if you know that the "owning" processor is also Many bralways generating the correct matrix entries, so that PETSc need Many brnot transfer duplicate entries generated on another processor. Many br

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

MAT_KEEP_NONZERO_PATTERN indicates when MatZeroRows() is called the zeroed entries Many brare kept in the nonzero structure Many br

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

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

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

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

Notes: Can only be called after MatSetSizes() and MatSetType() have been set. Many br

Many br

See Also

MatOption, Mat

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/mat/examples/tutorials/ex12.c.html
src/mat/examples/tutorials/ex16.c.html
src/ksp/ksp/examples/tutorials/ex2.c.html
src/ksp/ksp/examples/tutorials/ex5.c.html
src/ksp/ksp/examples/tutorials/ex9.c.html
src/ksp/ksp/examples/tutorials/ex10.c.html
src/ksp/ksp/examples/tutorials/ex18.c.html
src/ksp/ksp/examples/tutorials/ex31.c.html
src/ksp/ksp/examples/tutorials/ex52.c.html
src/snes/examples/tutorials/ex5.c.html
src/snes/examples/tutorials/ex7.c.html