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
178
179
180
181
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>KSPSetOperators</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>petsc-3.4.2 2013-07-02</b></div>
<A NAME="KSPSetOperators"><H1>KSPSetOperators</H1></A>
Sets the matrix associated with the linear system and a (possibly) different one associated with the preconditioner.
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscksp.h"
PetscErrorCode KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat,MatStructure flag)
</PRE>
Collective on <A HREF="../KSP/KSP.html#KSP">KSP</A> and <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>ksp </B></TD><TD>- the <A HREF="../KSP/KSP.html#KSP">KSP</A> context
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>Amat </B></TD><TD>- the matrix that defines the linear system
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>Pmat </B></TD><TD>- the matrix to be used in constructing the preconditioner, usually the same as Amat.
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>flag </B></TD><TD>- flag indicating information about the preconditioner matrix structure
during successive linear solves. This flag is ignored the first time a
linear system is solved, and thus is irrelevant when solving just one linear
system.
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
The flag can be used to eliminate unnecessary work in the preconditioner
during the repeated solution of linear systems of the same size. The
available options are
<pre>
SAME_PRECONDITIONER -
</pre>
<pre>
Pmat is identical during successive linear solves.
</pre>
<pre>
This option is intended for folks who are using
</pre>
<pre>
different Amat and Pmat matrices and want to reuse the
</pre>
<pre>
same preconditioner matrix. For example, this option
</pre>
<pre>
saves work by not recomputing incomplete factorization
</pre>
<pre>
for ILU/ICC preconditioners.
</pre>
<pre>
SAME_NONZERO_PATTERN -
</pre>
<pre>
Pmat has the same nonzero structure during
</pre>
<pre>
successive linear solves.
</pre>
<pre>
DIFFERENT_NONZERO_PATTERN -
</pre>
<pre>
Pmat does not have the same nonzero structure.
</pre>
<P>
All future calls to <A HREF="../KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</A>() must use the same size matrices!
<P>
Passing a NULL for Amat or Pmat removes the matrix that is currently used.
<P>
If you wish to replace either Amat or Pmat but leave the other one untouched then
first call <A HREF="../KSP/KSPGetOperators.html#KSPGetOperators">KSPGetOperators</A>() to get the one you wish to keep, call <A HREF="../Sys/PetscObjectReference.html#PetscObjectReference">PetscObjectReference</A>()
on it and then pass it back in in your call to <A HREF="../KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</A>().
<P>
<H3><FONT COLOR="#CC3333">Caution</FONT></H3>
If you specify SAME_NONZERO_PATTERN, PETSc believes your assertion
and does not check the structure of the matrix. If you erroneously
claim that the structure is the same when it actually is not, the new
preconditioner will not function correctly. Thus, use this optimization
feature carefully!
<P>
If in doubt about whether your preconditioner matrix has changed
structure or not, use the flag DIFFERENT_NONZERO_PATTERN.
<P>
<P>
Alternative usage: If the operators have NOT been set with <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>() then the operators
are created in <A HREF="../PC/PC.html#PC">PC</A> and returned to the user. In this case, if both operators
mat and pmat are requested, two DIFFERENT operators will be returned. If
only one is requested both operators in the <A HREF="../PC/PC.html#PC">PC</A> will be the same (i.e. as
if one had called <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>() with the same argument for both Mats).
The user must set the sizes of the returned matrices and their type etc just
as if the user created them with <A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(). For example,
<P>
<pre>
<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(ksp/pc,&mat,NULL,NULL); is equivalent to
</pre>
<pre>
set size, type, etc of mat
</pre>
<P>
<pre>
<A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&mat);
</pre>
<pre>
<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(ksp/pc,mat,mat,SAME_NONZERO_PATTERN);
</pre>
<pre>
<A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)mat);
</pre>
<pre>
set size, type, etc of mat
</pre>
<P>
and
<P>
<pre>
<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(ksp/pc,&mat,&pmat,NULL); is equivalent to
</pre>
<pre>
set size, type, etc of mat and pmat
</pre>
<P>
<pre>
<A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&mat);
</pre>
<pre>
<A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&pmat);
</pre>
<pre>
<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(ksp/pc,mat,pmat,SAME_NONZERO_PATTERN);
</pre>
<pre>
<A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)mat);
</pre>
<pre>
<A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)pmat);
</pre>
<pre>
set size, type, etc of mat and pmat
</pre>
<P>
The rational for this support is so that when creating a <A HREF="../TS/TS.html#TS">TS</A>, <A HREF="../SNES/SNES.html#SNES">SNES</A>, or <A HREF="../KSP/KSP.html#KSP">KSP</A> the hierarchy
of underlying objects (i.e. <A HREF="../SNES/SNES.html#SNES">SNES</A>, <A HREF="../KSP/KSP.html#KSP">KSP</A>, <A HREF="../PC/PC.html#PC">PC</A>, <A HREF="../Mat/Mat.html#Mat">Mat</A>) and their livespans can be completely
managed by the top most level object (i.e. the <A HREF="../TS/TS.html#TS">TS</A>, <A HREF="../SNES/SNES.html#SNES">SNES</A>, or <A HREF="../KSP/KSP.html#KSP">KSP</A>). Another way to look
at this is when you create a <A HREF="../SNES/SNES.html#SNES">SNES</A> you do not NEED to create a <A HREF="../KSP/KSP.html#KSP">KSP</A> and attach it to
the <A HREF="../SNES/SNES.html#SNES">SNES</A> object (the <A HREF="../SNES/SNES.html#SNES">SNES</A> object manages it for you). Similarly when you create a <A HREF="../KSP/KSP.html#KSP">KSP</A>
you do not need to attach a <A HREF="../PC/PC.html#PC">PC</A> to it (the <A HREF="../KSP/KSP.html#KSP">KSP</A> object manages the <A HREF="../PC/PC.html#PC">PC</A> object for you).
Thus, why should YOU have to create the <A HREF="../Mat/Mat.html#Mat">Mat</A> and attach it to the <A HREF="../SNES/SNES.html#SNES">SNES</A>/<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PC.html#PC">PC</A>, when
it can be created for you?
<P>
<H3><FONT COLOR="#CC3333">Keywords</FONT></H3>
<A HREF="../KSP/KSP.html#KSP">KSP</A>, set, operators, matrix, preconditioner, linear system
<BR>
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../KSP/KSPSolve.html#KSPSolve">KSPSolve</A>(), <A HREF="../KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</A>(), <A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(), <A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(), <A HREF="../KSP/KSPGetOperators.html#KSPGetOperators">KSPGetOperators</A>()
<BR><P><B><P><B><FONT COLOR="#CC3333">Level:</FONT></B>beginner
<BR><FONT COLOR="#CC3333">Location:</FONT></B><A HREF="../../../src/ksp/ksp/interface/itcreate.c.html#KSPSetOperators">src/ksp/ksp/interface/itcreate.c</A>
<BR><A HREF="./index.html">Index of all KSP 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/ksp/pc/examples/tutorials/ex1.c.html">src/ksp/pc/examples/tutorials/ex1.c.html</A><BR>
<A HREF="../../../src/ksp/pc/examples/tutorials/ex2.c.html">src/ksp/pc/examples/tutorials/ex2.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex1.c.html">src/ksp/ksp/examples/tutorials/ex1.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/ex3.c.html">src/ksp/ksp/examples/tutorials/ex3.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex4.c.html">src/ksp/ksp/examples/tutorials/ex4.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/ex7.c.html">src/ksp/ksp/examples/tutorials/ex7.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex8.c.html">src/ksp/ksp/examples/tutorials/ex8.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex8g.c.html">src/ksp/ksp/examples/tutorials/ex8g.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex9.c.html">src/ksp/ksp/examples/tutorials/ex9.c.html</A><BR>
</BODY></HTML>
|
