1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatSetOption.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>MatSetOption</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>petsc-3.10.3 2018-12-18</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.10.3 v3.10.3 docs/manualpages/Mat/MatSetOption.html "><small>Report Typos and Errors</small></a></div>
<A NAME="MatSetOption"><H1>MatSetOption</H1></A>
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.
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscmat.h"
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../Mat/MatSetOption.html#MatSetOption">MatSetOption</A>(<A HREF="../Mat/Mat.html#Mat">Mat</A> mat,<A HREF="../Mat/MatOption.html#MatOption">MatOption</A> op,<A HREF="../Sys/PetscBool.html#PetscBool">PetscBool</A> flg)
</PRE>
Logically Collective on <A HREF="../Mat/Mat.html#Mat">Mat</A> for certain operations, such as <A HREF="../Mat/MatOption.html#MatOption">MAT_SPD</A>, not collective for <A HREF="../Mat/MatOption.html#MatOption">MAT_ROW_ORIENTED</A>, see <A HREF="../Mat/MatOption.html#MatOption">MatOption</A>
<P>
<H3><FONT COLOR="#CC3333">Input Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>mat </B></TD><TD>- the matrix
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>option </B></TD><TD>- the option, one of those listed below (and possibly others),
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>flg </B></TD><TD>- turn the option on (<A HREF="../Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</A>) or off (<A HREF="../Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</A>)
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Options Describing Matrix Structure</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_SPD</A> </B></TD><TD>- symmetric positive definite
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_SYMMETRIC</A> </B></TD><TD>- symmetric in terms of both structure and value
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_HERMITIAN</A> </B></TD><TD>- transpose is the complex conjugation
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_STRUCTURALLY_SYMMETRIC</A> </B></TD><TD>- symmetric nonzero structure
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_SYMMETRY_ETERNAL</A> </B></TD><TD>- if you would like the symmetry/Hermitian flag
you set to be kept with all future use of the matrix
including after <A HREF="../Mat/MatAssemblyBegin.html#MatAssemblyBegin">MatAssemblyBegin</A>/End() which could
potentially change the symmetry structure, i.e. you
KNOW the matrix will ALWAYS have the property you set.
</TD></TR></TABLE>
<P>
<P>
<H3><FONT COLOR="#CC3333">Options For Use with MatSetValues()</FONT></H3>
Insert a logically dense subblock, which can be
<DT><B><A HREF="../Mat/MatOption.html#MatOption">MAT_ROW_ORIENTED</A> </B> -row-oriented (default)
<br>
<P>
Note these options reflect the data you pass in with <A HREF="../Mat/MatSetValues.html#MatSetValues">MatSetValues</A>(); it has
nothing to do with how the data is stored internally in the matrix
data structure.
<P>
When (re)assembling a matrix, we can restrict the input for
<H3><FONT COLOR="#CC3333">efficiency/debugging purposes. These options include</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_LOCATIONS</A> </B></TD><TD>- additional insertions will be allowed if they generate a new nonzero (slow)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_DIAGONALS</A> </B></TD><TD>- new diagonals will be allowed (for block diagonal format only)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_IGNORE_OFF_PROC_ENTRIES</A> </B></TD><TD>- drops off-processor entries
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_LOCATION_ERR</A> </B></TD><TD>- generates an error for new matrix entry
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_USE_HASH_TABLE</A> </B></TD><TD>- uses a hash table to speed up matrix assembly
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_NO_OFF_PROC_ENTRIES</A> </B></TD><TD>- 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.
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B><A HREF="../Mat/MatOption.html#MatOption">MAT_SUBSET_OFF_PROC_ENTRIES</A> </B></TD><TD>- 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.
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
Except for <A HREF="../Mat/MatOption.html#MatOption">MAT_UNUSED_NONZERO_LOCATION_ERR</A> and <A HREF="../Mat/MatOption.html#MatOption">MAT_ROW_ORIENTED</A> all processes that share the matrix must pass the same value in flg!
<P>
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.
<P>
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).
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_LOCATIONS</A> set to <A HREF="../Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</A> 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 <A HREF="../Mat/MatAssemblyEnd.html#MatAssemblyEnd">MatAssemblyEnd</A>(). If this option is set then the <A HREF="../Mat/MatAssemblyBegin.html#MatAssemblyBegin">MatAssemblyBegin</A>/End() processes has one less global reduction
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_LOCATION_ERR</A> set to <A HREF="../Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</A> 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 <A HREF="../Mat/MatAssemblyBegin.html#MatAssemblyBegin">MatAssemblyBegin</A>/End() processes has one less global reduction
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_ALLOCATION_ERR</A> set to <A HREF="../Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</A> 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 <A HREF="../Mat/MatAssemblyBegin.html#MatAssemblyBegin">MatAssemblyBegin</A>/End() processes has one less global reduction
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_IGNORE_OFF_PROC_ENTRIES</A> set to <A HREF="../Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</A> 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.
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_USE_HASH_TABLE</A> 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. <A HREF="../Mat/MatOption.html#MatOption">MAT_NEW_NONZERO_LOCATIONS</A> flag
should be used with <A HREF="../Mat/MatOption.html#MatOption">MAT_USE_HASH_TABLE</A> flag. This option is currently
supported by <A HREF="../Mat/MATMPIBAIJ.html#MATMPIBAIJ">MATMPIBAIJ</A> format only.
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_KEEP_NONZERO_PATTERN</A> indicates when <A HREF="../Mat/MatZeroRows.html#MatZeroRows">MatZeroRows</A>() is called the zeroed entries
are kept in the nonzero structure
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_IGNORE_ZERO_ENTRIES</A> - for AIJ/<A HREF="../IS/IS.html#IS">IS</A> matrices this will stop zero values from creating
a zero location in the matrix
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_USE_INODES</A> - indicates using inode version of the code - works with AIJ matrix types
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_NO_OFF_PROC_ZERO_ROWS</A> - 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.
<P>
<A HREF="../Mat/MatOption.html#MatOption">MAT_IGNORE_LOWER_TRIANGULAR</A> - 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).
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
Can only be called after <A HREF="../Mat/MatSetSizes.html#MatSetSizes">MatSetSizes</A>() and <A HREF="../Mat/MatSetType.html#MatSetType">MatSetType</A>() have been set.
<P>
<P>
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../Mat/MatOption.html#MatOption">MatOption</A>, <A HREF="../Mat/Mat.html#Mat">Mat</A>
<BR>
<P>
<P><B></B><H3><FONT COLOR="#CC3333">Level</FONT></H3>intermediate<BR>
<H3><FONT COLOR="#CC3333">Location</FONT></H3>
</B><A HREF="../../../src/mat/interface/matrix.c.html#MatSetOption">src/mat/interface/matrix.c</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/mat/examples/tutorials/ex4.c.html">src/mat/examples/tutorials/ex4.c.html</A><BR>
<A HREF="../../../src/mat/examples/tutorials/ex12.c.html">src/mat/examples/tutorials/ex12.c.html</A><BR>
<A HREF="../../../src/mat/examples/tutorials/ex16.c.html">src/mat/examples/tutorials/ex16.c.html</A><BR>
<A HREF="../../../src/ksp/pc/examples/tutorials/ex3.c.html">src/ksp/pc/examples/tutorials/ex3.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex2.c.html">src/ksp/ksp/examples/tutorials/ex2.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex5.c.html">src/ksp/ksp/examples/tutorials/ex5.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex9.c.html">src/ksp/ksp/examples/tutorials/ex9.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex18.c.html">src/ksp/ksp/examples/tutorials/ex18.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex52.c.html">src/ksp/ksp/examples/tutorials/ex52.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex62.c.html">src/ksp/ksp/examples/tutorials/ex62.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex67.c.html">src/ksp/ksp/examples/tutorials/ex67.c.html</A><BR>
<P><H3><FONT COLOR="CC3333">Implementations</FONT></H3><A HREF="../../../src/mat/impls/adj/mpi/mpiadj.c.html#MatSetOption_MPIAdj">MatSetOption_MPIAdj in src/mat/impls/adj/mpi/mpiadj.c</A><BR>
<A HREF="../../../src/mat/impls/aij/mpi/mpiaij.c.html#MatSetOption_MPIAIJ">MatSetOption_MPIAIJ in src/mat/impls/aij/mpi/mpiaij.c</A><BR>
<A HREF="../../../src/mat/impls/aij/seq/aij.c.html#MatSetOption_SeqAIJ">MatSetOption_SeqAIJ in src/mat/impls/aij/seq/aij.c</A><BR>
<A HREF="../../../src/mat/impls/aij/seq/inode2.c.html#MatSetOption_SeqAIJ_Inode">MatSetOption_SeqAIJ_Inode in src/mat/impls/aij/seq/inode2.c</A><BR>
<A HREF="../../../src/mat/impls/baij/mpi/mpibaij.c.html#MatSetOption_MPIBAIJ">MatSetOption_MPIBAIJ in src/mat/impls/baij/mpi/mpibaij.c</A><BR>
<A HREF="../../../src/mat/impls/baij/seq/baij.c.html#MatSetOption_SeqBAIJ">MatSetOption_SeqBAIJ in src/mat/impls/baij/seq/baij.c</A><BR>
<A HREF="../../../src/mat/impls/blockmat/seq/blockmat.c.html#MatSetOption_BlockMat">MatSetOption_BlockMat in src/mat/impls/blockmat/seq/blockmat.c</A><BR>
<A HREF="../../../src/mat/impls/dense/mpi/mpidense.c.html#MatSetOption_MPIDense">MatSetOption_MPIDense in src/mat/impls/dense/mpi/mpidense.c</A><BR>
<A HREF="../../../src/mat/impls/dense/seq/dense.c.html#MatSetOption_SeqDense">MatSetOption_SeqDense in src/mat/impls/dense/seq/dense.c</A><BR>
<A HREF="../../../src/mat/impls/elemental/matelem.cxx.html#MatSetOption_Elemental">MatSetOption_Elemental in src/mat/impls/elemental/matelem.cxx</A><BR>
<A HREF="../../../src/mat/impls/is/matis.c.html#MatSetOption_IS">MatSetOption_IS in src/mat/impls/is/matis.c</A><BR>
<A HREF="../../../src/mat/impls/preallocator/matpreallocator.c.html#MatSetOption_Preallocator">MatSetOption_Preallocator in src/mat/impls/preallocator/matpreallocator.c</A><BR>
<A HREF="../../../src/mat/impls/sbaij/mpi/mpisbaij.c.html#MatSetOption_MPISBAIJ">MatSetOption_MPISBAIJ in src/mat/impls/sbaij/mpi/mpisbaij.c</A><BR>
<A HREF="../../../src/mat/impls/sbaij/seq/sbaij.c.html#MatSetOption_SeqSBAIJ">MatSetOption_SeqSBAIJ in src/mat/impls/sbaij/seq/sbaij.c</A><BR>
<A HREF="../../../src/mat/impls/sell/mpi/mpisell.c.html#MatSetOption_MPISELL">MatSetOption_MPISELL in src/mat/impls/sell/mpi/mpisell.c</A><BR>
<A HREF="../../../src/mat/impls/sell/seq/sell.c.html#MatSetOption_SeqSELL">MatSetOption_SeqSELL in src/mat/impls/sell/seq/sell.c</A><BR>
<BR><A HREF="./index.html">Index of all Mat routines</A>
<BR><A HREF="../../index.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
</BODY></HTML>
|
