179351c6311d0e3f16c01099ffca7d730381540d
[scilab.git] / scilab / modules / sparse / help / ja_JP / iterativesolvers / pcg.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) XXXX-2008 - INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <refentry 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" xmlns:scilab="http://www.scilab.org" xml:id="pcg" xml:lang="ja">
14     <refnamediv>
15         <refname>pcg</refname>
16         <refpurpose>プリコンディショナ付き共役勾配法</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>呼び出し手順</title>
20         <synopsis>[x, flag, err, iter, res] = pcg(A, b [, tol [, maxIter [, M [, M2 [, x0 [, verbose]]]]]])
21             [x, flag, err, iter, res] = pcg(A, b [key=value,...])
22         </synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>パラメータ</title>
26         <variablelist>
27             <varlistentry>
28                 <term>A</term>
29                 <term/>
30                 <listitem>
31                     <para>
32                         行列, または指定した<literal>x</literal>について
33                         <literal>A*x</literal>を計算する関数またはリスト.
34                         以下にAの型に応じたA*xの計算に関する説明を示します.
35                     </para>
36                     <itemizedlist>
37                         <listitem>
38                             <para>
39                                 <literal>行列.</literal>Aが行列の場合, 通常の行列
40                                 または疎行列とすることができます
41                             </para>
42                         </listitem>
43                         <listitem>
44                             <para>
45                                 <literal>関数.</literal>Aが関数の場合, 
46                                 以下のヘッダーを有する必要があります :
47                             </para>
48                             <programlisting role=""><![CDATA[ 
49 function y = A ( x )
50  ]]></programlisting>
51                         </listitem>
52                         <listitem>
53                             <para>
54                                 <literal>list.</literal> Aがリストの場合, 
55                                 リストの最初の要素は関数で,リストのその他の
56                                 要素(インデックス2から末尾まで)は関数の引数となります.
57                                 関数がコールされる時,
58                                 xのカレントの値は関数に最初の引数として渡されます.
59                                 他の引数はリストに指定された値です.
60                             </para>
61                         </listitem>
62                     </itemizedlist>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>b</term>
67                 <listitem>
68                     <para>右辺ベクトルr (大きさ: nx1)</para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>tol</term>
73                 <listitem>
74                     <para>相対許容誤差 (デフォルト: 1e-8). 
75                         終了条件は残差r=b-Axの2次ノルムを
76                         右辺bの2次ノルムで割った値に基づきます.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>maxIter</term>
82                 <listitem>
83                     <para>反復最大回数 (デフォルト: n)</para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>M</term>
88                 <listitem>
89                     <para>プリコンディショナ: 通常の行列または疎行列または
90                         <literal>M\x</literal>を返す関数 (デフォルト: none)
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>M2</term>
96                 <listitem>
97                     <para>プリコンディショナ: 通常の行列または疎行列または
98                         <literal>x</literal>について<literal>M2\x</literal>を返す関数 (デフォルト:
99                         none)
100                     </para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>x0</term>
105                 <listitem>
106                     <para>初期推定ベクトル (デフォルト: zeros(n,1))</para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>verbose</term>
111                 <listitem>
112                     <para>冗長なログを有効にする場合は1に設定(デフォルト 0)</para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>x</term>
117                 <listitem>
118                     <para>解ベクトル</para>
119                 </listitem>
120             </varlistentry>
121             <varlistentry>
122                 <term>flag</term>
123                 <listitem>
124                     <para>
125                         <literal>maxi</literal>回の反復回数内に
126                         <literal>pcg</literal>が指定した
127                         許容誤差に収束する場合に 0, そうでない場合に 1
128                     </para>
129                 </listitem>
130             </varlistentry>
131             <varlistentry>
132                 <term>err</term>
133                 <listitem>
134                     <para>
135                         最終残差相対ノルム (右辺bの2次ノルムが使用されます)
136                     </para>
137                 </listitem>
138             </varlistentry>
139             <varlistentry>
140                 <term>iter</term>
141                 <listitem>
142                     <para>実行された反復回数</para>
143                 </listitem>
144             </varlistentry>
145             <varlistentry>
146                 <term>res</term>
147                 <listitem>
148                     <para>残差相対ノルムのベクトル</para>
149                 </listitem>
150             </varlistentry>
151         </variablelist>
152     </refsection>
153     <refsection>
154         <title>説明</title>
155         <para>
156             プリコンディショナ有りまたは無しの
157             共役勾配法により線形システム<literal>Ax=b</literal>を解きます.
158             プリコンディショナは,
159             対称正定行列<literal>M</literal>
160             または<literal>M=M1*M2</literal>となるような
161             2つの行列<literal>M1</literal> および<literal>M2</literal>
162             により定義されます.
163             この場合,関数は<literal>inv(M)*A*x = inv(M)*b</literal>を
164             <literal>x</literal>について解きます.
165             <literal>M</literal>, <literal>M1</literal>および
166             <literal>M2</literal> は,対応する左除算
167             <literal>y=Mi\x</literal>を計算する
168             呼び出し手順<literal>y=Milx(x)</literal>を有する
169             Scilab関数とすることができます.
170         </para>
171         <para>
172             <literal>A</literal>行列は対称正定行列
173             (通常の行列または疎行列)または
174             <literal>y=A*x</literal>を計算する
175             呼び出し手順<literal>y=Ax(x)</literal>を有する関数と
176             する必要があります.
177         </para>
178     </refsection>
179     <refsection>
180         <title>良好な条件または悪い条件の問題の例</title>
181         <para>
182             以下の例では,2つの線形システムを解きます.
183             最初の行列の条件数は ~0.02 に等しくなり,
184             アルゴリズムはちょうど10回の反復で収束します.
185             これが行列の大きさの場合,共役勾配法で指定される動作となります.
186             後者は,条件数1.d-6に等しくなり,22回の反復で収束します.
187             これは,パラメータ maxIterを30に設定する理由です.
188             "key=value" 構文のその他の例については以下を参照ください. 
189         </para>
190         <programlisting role="example"><![CDATA[ 
191 //良い条件の例
192 A=[ 94  0   0   0    0   28  0   0   32  0  
193      0   59  13  5    0   0   0   10  0   0  
194      0   13  72  34   2   0   0   0   0   65 
195      0   5   34  114  0   0   0   0   0   55 
196      0   0   2   0    70  0   28  32  12  0  
197      28  0   0   0    0   87  20  0   33  0  
198      0   0   0   0    28  20  71  39  0   0  
199      0   10  0   0    32  0   39  46  8   0  
200      32  0   0   0    12  33  0   8   82  11 
201      0   0   65  55   0   0   0   0   11  100];
202 b=ones(10,1);
203 [x, fail, err, iter, res]=pcg(A,b,1d-12,15);
204 mprintf("      fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
205 //悪い条件の例
206 A=[ 894     0   0     0   0   28  0   0   1000  70000
207       0      5   13    5   0   0   0   0   0     0    
208       0      13  72    34  0   0   0   0   0     6500 
209       0      5   34    1   0   0   0   0   0     55   
210       0      0   0     0   70  0   28  32  12    0    
211       28     0   0     0   0   87  20  0   33    0    
212       0      0   0     0   28  20  71  39  0     0    
213       0      0   0     0   32  0   39  46  8     0    
214       1000   0   0     0   12  33  0   8   82    11   
215       70000  0   6500  55  0   0   0   0   11    100];
216 [x, fail, err, iter, res]=pcg(A,b,maxIter=30,tol=1d-12);
217 mprintf("      fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
218  ]]></programlisting>
219     </refsection>
220     <refsection>
221         <title>Aを疎行列または関数またはリストとして指定する例</title>
222         <para>以下の例では,疎行列を同時に処理する方法を示します.
223             右辺を計算する関数が "pcg" プリミティブに指定される
224             場合も示します.
225             この例における最後のケースでは,
226             リストがプリミティブに指定される場合です.
227         </para>
228         <programlisting role="example"><![CDATA[ 
229 //良い条件の例
230 A=[ 94  0   0   0    0   28  0   0   32  0  
231      0   59  13  5    0   0   0   10  0   0  
232      0   13  72  34   2   0   0   0   0   65 
233      0   5   34  114  0   0   0   0   0   55 
234      0   0   2   0    70  0   28  32  12  0  
235      28  0   0   0    0   87  20  0   33  0  
236      0   0   0   0    28  20  71  39  0   0  
237      0   10  0   0    32  0   39  46  8   0  
238      32  0   0   0    12  33  0   8   82  11 
239      0   0   65  55   0   0   0   0   11  100];
240 b=ones(10,1);
241 // Aを疎行列に変換
242 Asparse=sparse(A);
243 [x, fail, err, iter, res]=pcg(Asparse,b,maxIter=30,tol=1d-12);
244 mprintf("      fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
245 // 右辺を計算する関数を定義.
246 function y=Atimesx(x)
247   A=[ 94  0   0   0    0   28  0   0   32  0  
248        0   59  13  5    0   0   0   10  0   0  
249        0   13  72  34   2   0   0   0   0   65
250        0   5   34  114  0   0   0   0   0   55
251        0   0   2   0    70  0   28  32  12  0
252        28  0   0   0    0   87  20  0   33  0
253        0   0   0   0    28  20  71  39  0   0
254        0   10  0   0    32  0   39  46  8   0
255        32  0   0   0    12  33  0   8   82  11
256        0   0   65  55   0   0   0   0   11  100];
257   y=A*x
258 endfunction
259 // スクリプトAtimesx をプリミティブに指定
260 [x, fail, err, iter, res]=pcg(Atimesx,b,maxIter=30,tol=1d-12);
261 mprintf("      fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
262 // 右辺を計算する関数を定義.
263 function y=Atimesxbis(x,A)
264   y=A*x
265 endfunction
266 // リストをプリミティブに指定
267 Alist = list(Atimesxbis,Asparse);
268 [x, fail, err, iter, res]=pcg(Alist,b,maxIter=30,tol=1d-12);
269 mprintf("      fail=%d, iter=%d, errrel=%e\n",fail,iter,err)
270  ]]></programlisting>
271     </refsection>
272     <refsection>
273         <title>key=value構文の例</title>
274         <para>
275             以下の例ではkey=value"構文により引数を指定する方法を示します.
276             これにより,位置を固定せずに引数を設定できるようになり,
277             引数のリストにおいてその順番に依存せずに引数を設定できます.
278             利用可能なキーはオプションの引数の名前で,以下に示します:
279             tol, maxIter, %M, %M2, x0, verbose. 
280             以下の例では,
281             maxIterオプションの前にverboseオプションを指定します.
282             "key=value" 構文ではなく,
283             位置を指定する引数の場合は,
284             maxIterを最初にverboseを後に指定する必要があります.
285         </para>
286         <programlisting role="example"><![CDATA[ 
287 // 引数をkey=value構文で指定する例
288 A=[100,1;1,10];
289 b=[101;11];
290 [xcomputed, flag, err, iter, res]=pcg(A,b,verbose=1);
291 // key=value構文では, 順番は関係ありません
292 [xcomputed, flag, err, iter, res]=pcg(A,b,verbose=1,maxIter=0);
293  ]]></programlisting>
294     </refsection>
295     <refsection role="see also">
296         <title>参照</title>
297         <simplelist type="inline">
298             <member>
299                 <link linkend="backslash">backslash</link>
300             </member>
301             <member>
302                 <link linkend="qmr">qmr</link>
303             </member>
304             <member>
305                 <link linkend="gmres">gmres</link>
306             </member>
307         </simplelist>
308     </refsection>
309     <refsection>
310         <title>参考文献</title>
311         <para>"Templates for the Solution of Linear Systems: Building Blocks for
312             Iterative Methods", Barrett, Berry, Chan, Demmel, Donato, Dongarra,
313             Eijkhout, Pozo, Romine, and Van der Vorst, SIAM Publications, 1993, ftp
314             netlib2.cs.utk.edu/linalg/templates.ps
315         </para>
316         <para>"Iterative Methods for Sparse Linear Systems, Second Edition", Saad,
317             SIAM Publications, 2003, ftp
318             ftp.cs.umn.edu/dept/users/saad/PS/all_ps.zip
319         </para>
320     </refsection>
321 </refentry>