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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>MatSetOption</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<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, nonsorted input.
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscmat.h"
PetscErrorCode MatSetOption(Mat mat,MatOption op)
</PRE>
Collective on <A HREF="../Mat/Mat.html#Mat">Mat</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),
e.g., MAT_ROWS_SORTED, MAT_NEW_NONZERO_LOCATION_ERR
</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>MAT_SYMMETRIC </B></TD><TD>- symmetric in terms of both structure and value
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_HERMITIAN </B></TD><TD>- transpose is the complex conjugation
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_STRUCTURALLY_SYMMETRIC </B></TD><TD>- symmetric nonzero structure
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NOT_SYMMETRIC </B></TD><TD>- not symmetric in value
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NOT_HERMITIAN </B></TD><TD>- transpose is not the complex conjugation
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NOT_STRUCTURALLY_SYMMETRIC </B></TD><TD>- not symmetric nonzero structure
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_SYMMETRY_ETERNAL </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>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NOT_SYMMETRY_ETERNAL </B></TD><TD>- if <A HREF="../Mat/MatAssemblyBegin.html#MatAssemblyBegin">MatAssemblyBegin</A>/End() is called then the
flags you set will be dropped (in case potentially
the symmetry etc was lost).
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Options For Use with MatSetValues()</FONT></H3>
Insert a logically dense subblock, which can be
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_ROW_ORIENTED </B></TD><TD>- row-oriented (default)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_COLUMN_ORIENTED </B></TD><TD>- column-oriented
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_ROWS_SORTED </B></TD><TD>- sorted by row
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_ROWS_UNSORTED </B></TD><TD>- not sorted by row (default)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_COLUMNS_SORTED </B></TD><TD>- sorted by column
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_COLUMNS_UNSORTED </B></TD><TD>- not sorted by column (default)
</TD></TR></TABLE>
<P>
Not 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
efficiency/debugging purposes. These options include
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NO_NEW_NONZERO_LOCATIONS </B></TD><TD>- additional insertions will not be
allowed if they generate a new nonzero
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_YES_NEW_NONZERO_LOCATIONS </B></TD><TD>- additional insertions will be allowed
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NO_NEW_DIAGONALS </B></TD><TD>- additional insertions will not be allowed if
they generate a nonzero in a new diagonal (for block diagonal format only)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_YES_NEW_DIAGONALS </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>MAT_IGNORE_OFF_PROC_ENTRIES </B></TD><TD>- drops off-processor entries
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_NEW_NONZERO_LOCATION_ERR </B></TD><TD>- generates an error for new matrix entry
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>MAT_USE_HASH_TABLE </B></TD><TD>- uses a hash table to speed up matrix assembly
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
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>
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 <A HREF="../Mat/MatAssemblyEnd.html#MatAssemblyEnd">MatAssemblyEnd</A>()
<P>
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
<A HREF="../KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</A>() to ensure that the nonzero pattern truely does
remain unchanged. Set after the first <A HREF="../Mat/MatAssemblyEnd.html#MatAssemblyEnd">MatAssemblyEnd</A>()
<P>
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.
<P>
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.
<P>
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 <A HREF="../Mat/MATMPIBAIJ.html#MATMPIBAIJ">MATMPIBAIJ</A> format only.
<P>
MAT_KEEP_ZEROED_ROWS indicates when <A HREF="../Mat/MatZeroRows.html#MatZeroRows">MatZeroRows</A>() is called the zeroed entries
are kept in the nonzero structure
<P>
MAT_IGNORE_ZERO_ENTRIES - 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>
MAT_USE_INODES - indicates using inode version of the code - works with AIJ and
ROWBS matrix types
<P>
MAT_DO_NOT_USE_INODES - indicates not using inode version of the code - works
with AIJ and ROWBS matrix types (database option "-mat_no_inode")
<P>
<P>
<P>
<P><B><P><B><FONT COLOR="#CC3333">Level:</FONT></B>intermediate
<BR><FONT COLOR="#CC3333">Location:</FONT></B><A HREF="../../../src/mat/interface/matrix.c.html#MatSetOption">src/mat/interface/matrix.c</A>
<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>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/mat/examples/tutorials/ex5.c.html">src/mat/examples/tutorials/ex5.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/snes/examples/tutorials/ex5.c.html">src/snes/examples/tutorials/ex5.c.html</A><BR>
<A HREF="../../../src/snes/examples/tutorials/ex14.c.html">src/snes/examples/tutorials/ex14.c.html</A><BR>
<A HREF="../../../src/snes/examples/tutorials/ex5f90.F.html">src/snes/examples/tutorials/ex5f90.F.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex2.c.html">src/ts/examples/tutorials/ex2.c.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex3.c.html">src/ts/examples/tutorials/ex3.c.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex4.c.html">src/ts/examples/tutorials/ex4.c.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex5.c.html">src/ts/examples/tutorials/ex5.c.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex6.c.html">src/ts/examples/tutorials/ex6.c.html</A><BR>
</BODY></HTML>
|