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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
* Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
* Copyright (C) XXXX-2008 - INRIA
*
* This file must be used under the terms of the CeCILL.
* This source file is licensed as described in the file COPYING, which
* you should have received as part of this distribution. The terms
* are also available at
* http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
*
-->
<refentry version="5.0-subset Scilab" xml:id="pcg" xml:lang="en"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:ns4="http://www.w3.org/1999/xhtml"
xmlns:mml="http://www.w3.org/1998/Math/MathML"
xmlns:db="http://docbook.org/ns/docbook">
<info>
<pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (mer, 26 mar 2008)
$</pubdate>
</info>
<refnamediv>
<refname>pcg</refname>
<refpurpose>precondioned conjugate gradient</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Calling Sequence</title>
<synopsis>[x, flag, err, iter, res] = pcg(A, b [, tol [, maxIter [, M [, M2 [, x0 [, verbose]]]]]])
[x, flag, err, iter, res] = pcg(A, b [key=value,...])
</synopsis>
</refsynopsisdiv>
<refsection>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>A</term>
<term></term>
<listitem>
<para>a matrix, or a function, or a list computing
<literal>A*x</literal> for each given <literal>x</literal>. The
following is a description of the computation of A*x depending on
the type of A.
</para>
<itemizedlist>
<listitem>
<para><literal>matrix.</literal>If A is a matrix, it can be
dense or sparse</para>
</listitem>
<listitem>
<para><literal>function.</literal>If A is a function, it must
have the following header :</para>
<programlisting role = ""><![CDATA[
function y = A ( x )
]]></programlisting>
</listitem>
<listitem>
<para><literal>list.</literal>If A is a list, the first element
of the list is expected to be a function and the other elements
in the list are the arguments of the function, from index 2 to
the end. When the function is called, the current value of x is
passed to the function as the first argument. The other
arguments passed are the one given in the list.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>b</term>
<listitem>
<para>right hand side vector (size: nx1)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tol</term>
<listitem>
<para>error relative tolerance (default: 1e-8).
The termination criteria is based on the 2-norm of the
residual r=b-Ax, divided by the 2-norm of the right hand side b.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>maxIter</term>
<listitem>
<para>maximum number of iterations (default: n)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>M</term>
<listitem>
<para>preconditioner: full or sparse matrix or function returning
<literal>M\x</literal> (default: none)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>M2</term>
<listitem>
<para>preconditioner: full or sparse matrix or function returning
<literal>M2\x</literal> for each <literal>x</literal> (default:
none)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>x0</term>
<listitem>
<para>initial guess vector (default: zeros(n,1))</para>
</listitem>
</varlistentry>
<varlistentry>
<term>verbose</term>
<listitem>
<para>set to 1 to enable verbose logging (default 0)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>x</term>
<listitem>
<para>solution vector</para>
</listitem>
</varlistentry>
<varlistentry>
<term>flag</term>
<listitem>
<para>0 if <literal>pcg</literal> converged to the desired tolerance
within <literal>maxi</literal> iterations, 1 else</para>
</listitem>
</varlistentry>
<varlistentry>
<term>err</term>
<listitem>
<para>final relative norm of the residual (the 2-norm of the right-hand side b is used)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>iter</term>
<listitem>
<para>number of iterations performed</para>
</listitem>
</varlistentry>
<varlistentry>
<term>res</term>
<listitem>
<para>vector of the residual relative norms</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Description</title>
<para>Solves the linear system <literal>Ax=b</literal> using the conjugate
gradient method with or without preconditioning. The preconditionning
should be defined by a symmetric positive definite matrix
<literal>M</literal>, or two matrices <literal>M1</literal> and
<literal>M2</literal> such that <literal>M=M1*M2</literal>. in the case
the function solves <literal>inv(M)*A*x = inv(M)*b</literal> for
<literal>x</literal>. <literal>M</literal>, <literal>M1</literal> and
<literal>M2</literal> can be Scilab functions with calling sequence
<literal>y=Milx(x)</literal> which computes the corresponding left
division <literal>y=Mi\x</literal>.</para>
<para>The <literal>A</literal> matrix must be a symmetric positive
definite matrix (full or sparse) or a function with calling sequence
<literal>y=Ax(x)</literal> which computes <literal>y=A*x</literal></para>
</refsection>
<refsection>
<title>Example with well conditionned and ill conditionned
problems</title>
<para>In the following example, two linear systems are solved. The first
maxtrix has a condition number equals to ~0.02, which makes the algorithm
converge in exactly 10 iterations. Since this is the size of the matrix,
it is an expected behaviour for a gradient conjugate method. The second
one has a low condition number equals to 1.d-6, which makes the algorithm
converge in a larger 22 iterations. This is why the parameter maxIter is
set to 30. See below for other examples of the "key=value" syntax. </para>
<programlisting role="example"><![CDATA[
//Well conditionned problem
A=[ 94 0 0 0 0 28 0 0 32 0
0 59 13 5 0 0 0 10 0 0
0 13 72 34 2 0 0 0 0 65
0 5 34 114 0 0 0 0 0 55
0 0 2 0 70 0 28 32 12 0
28 0 0 0 0 87 20 0 33 0
0 0 0 0 28 20 71 39 0 0
0 10 0 0 32 0 39 46 8 0
32 0 0 0 12 33 0 8 82 11
0 0 65 55 0 0 0 0 11 100];
b=ones(10,1);
[x, fail, err, iter, res]=pcg(A,b,1d-12,15);
mprintf(" fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
//Ill contionned one
A=[ 894 0 0 0 0 28 0 0 1000 70000
0 5 13 5 0 0 0 0 0 0
0 13 72 34 0 0 0 0 0 6500
0 5 34 1 0 0 0 0 0 55
0 0 0 0 70 0 28 32 12 0
28 0 0 0 0 87 20 0 33 0
0 0 0 0 28 20 71 39 0 0
0 0 0 0 32 0 39 46 8 0
1000 0 0 0 12 33 0 8 82 11
70000 0 6500 55 0 0 0 0 11 100];
[x, fail, err, iter, res]=pcg(A,b,maxIter=30,tol=1d-12);
mprintf(" fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
]]></programlisting>
</refsection>
<refsection>
<title>Examples with A given as a sparse matrix, or function, or
list</title>
<para>The following example shows that the method can handle sparse
matrices as well. It also shows the case where a function, computing the
right-hand side, is given to the "pcg" primitive. The final case shown by
this example, is when a list is passed to the primitive.</para>
<programlisting role="example"><![CDATA[
//Well conditionned problem
A=[ 94 0 0 0 0 28 0 0 32 0
0 59 13 5 0 0 0 10 0 0
0 13 72 34 2 0 0 0 0 65
0 5 34 114 0 0 0 0 0 55
0 0 2 0 70 0 28 32 12 0
28 0 0 0 0 87 20 0 33 0
0 0 0 0 28 20 71 39 0 0
0 10 0 0 32 0 39 46 8 0
32 0 0 0 12 33 0 8 82 11
0 0 65 55 0 0 0 0 11 100];
b=ones(10,1);
// Convert A into a sparse matrix
Asparse=sparse(A);
[x, fail, err, iter, res]=pcg(Asparse,b,maxIter=30,tol=1d-12);
mprintf(" fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
// Define a function which computes the right-hand side.
function y=Atimesx(x)
A=[ 94 0 0 0 0 28 0 0 32 0
0 59 13 5 0 0 0 10 0 0
0 13 72 34 2 0 0 0 0 65
0 5 34 114 0 0 0 0 0 55
0 0 2 0 70 0 28 32 12 0
28 0 0 0 0 87 20 0 33 0
0 0 0 0 28 20 71 39 0 0
0 10 0 0 32 0 39 46 8 0
32 0 0 0 12 33 0 8 82 11
0 0 65 55 0 0 0 0 11 100];
y=A*x
endfunction
// Pass the script Atimesx to the primitive
[x, fail, err, iter, res]=pcg(Atimesx,b,maxIter=30,tol=1d-12);
mprintf(" fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
// Define a function which computes the right-hand side.
function y=Atimesxbis(x,A)
y=A*x
endfunction
// Pass a list to the primitive
Alist = list(Atimesxbis,Asparse);
[x, fail, err, iter, res]=pcg(Alist,b,maxIter=30,tol=1d-12);
mprintf(" fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
]]></programlisting>
</refsection>
<refsection>
<title>Examples with key=value syntax</title>
<para>The following example shows how to pass arguments with the
"key=value" syntax. This allows to set non-positionnal arguments, that is,
to set arguments which are not depending on their order in the list of
arguments. The available keys are the names of the optional arguments,
that is : tol, maxIter, %M, %M2, x0, verbose. Notice that, in the
following example, the verbose option is given before the maxIter option.
Without the "key=value" syntax, the positionnal arguments would require
that maxIter come first and verbose after.</para>
<programlisting role="example"><![CDATA[
// Example of an argument passed with key=value syntax
A=[100,1;1,10];
b=[101;11];
[xcomputed, flag, err, iter, res]=pcg(A,b,verbose=1);
// With key=value syntax, the order does not matter
[xcomputed, flag, err, iter, res]=pcg(A,b,verbose=1,maxIter=0);
]]></programlisting>
</refsection>
<refsection>
<title>See Also</title>
<simplelist type="inline">
<member><link linkend="backslash">backslash</link></member>
<member><link linkend="qmr">qmr</link></member>
<member><link linkend="gmres">gmres</link></member>
</simplelist>
</refsection>
<refsection>
<title>Authors</title>
<para>Sage Group, IRISA, 2004</para>
<para>Serge Steer, INRIA, 2006</para>
<para>Michael Baudin, INRIA, 2008-2009</para>
</refsection>
<refsection>
<title>References</title>
<para>"Templates for the Solution of Linear Systems: Building Blocks for
Iterative Methods", Barrett, Berry, Chan, Demmel, Donato, Dongarra,
Eijkhout, Pozo, Romine, and Van der Vorst, SIAM Publications, 1993, ftp
netlib2.cs.utk.edu/linalg/templates.ps</para>
<para>"Iterative Methods for Sparse Linear Systems, Second Edition", Saad,
SIAM Publications, 2003, ftp
ftp.cs.umn.edu/dept/users/saad/PS/all_ps.zip</para>
</refsection>
</refentry>
|
