* Bug 15028 fixed: assert_checkalmostequal() did not accept polynomials
[scilab.git] / scilab / modules / development_tools / help / ja_JP / assert / assert_checkalmostequal.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  *
4  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5  * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="assert_checkalmostequal" xml:lang="ja">
21     <refnamediv>
22         <refname>assert_checkalmostequal</refname>
23         <refpurpose>計算値と予測値が数値的に近いことを調べる.</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>呼び出し手順</title>
27         <synopsis>
28             flag = assert_checkalmostequal ( computed , expected )
29             flag = assert_checkalmostequal ( computed , expected , reltol )
30             flag = assert_checkalmostequal ( computed , expected , reltol , abstol )
31             flag = assert_checkalmostequal ( computed , expected , reltol , abstol , comptype )
32             [flag,errmsg] = assert_checkalmostequal ( ... )
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>パラメータ</title>
37         <variablelist>
38             <varlistentry>
39                 <term>computed:</term>
40                 <listitem>
41                     <para>
42                       matrix or hypermatrix or sparse matrix of decimal real or complex numbers;
43                       or matrix or hypermatrix of polynomials with real or complex coefficients:
44                       the computed result.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>expected :</term>
50                 <listitem>
51                     <para>
52                       matrix or hypermatrix or sparse matrix of decimal real or complex numbers;
53                       or matrix or hypermatrix of polynomials with real or complex coefficients:
54                       the expected result.
55                     </para>
56                   <para>
57                     If <literal>computed</literal> are polynomials, <literal>expected</literal>
58                     must be polynomials as well.
59                   </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>reltol :</term>
64                 <listitem>
65                     <para> doubleの1行1列行列, 相対許容誤差
66                         (デフォルト: reltol=sqrt(%eps)).
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>abstol :</term>
72                 <listitem>
73                     <para>
74                         doubleの1行1列行列, 絶対許容誤差
75                         (デフォルト: abstol=0).
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>comptype :</term>
81                 <listitem>
82                     <para>
83                         文字列の1行1列行列, "matrix" または "element"
84                         (デフォルト: comptype="element").
85                         比較の型.
86                     </para>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>flag :</term>
91                 <listitem>
92                     <para>
93                         論理値の1行1列行列,
94                         computed が expected に近い場合に %t,
95                         そうでない場合に %f
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>errmsg :</term>
101                 <listitem>
102                     <para>
103                         文字列の1行1列行列, エラーメッセージ.
104                         flag==%t の場合は errmsg="",
105                         flag==%f の場合 errmsg にはエラーメッセージが
106                         代入されます.
107                     </para>
108                 </listitem>
109             </varlistentry>
110         </variablelist>
111     </refsection>
112     <refsection>
113         <title>説明</title>
114         <para>
115             Performs silently if the two arrays of doubles or complex doubles, or the two arrays
116             of real or complex polynomials computed and expected are close.
117             The variables computed and expected can be exchanged without changing the result.
118         </para>
119         <para>
120           In case of polynomials, the size of both arrays, the degrees, and finally the
121           matrices of their coefficients are compared within the given or default tolerances.
122         </para>
123         <para>
124             オプションの入力引数に空の行列w指定するとデフォルト値で
125             置換されます.
126         </para>
127         <para>
128             以下のようなアルゴリズムを使用します.
129             まず実部を比較します.実部が等しい場合,虚部を比較します.
130         </para>
131         <para>
132             使用される条件は相対および絶対許容誤差を組み合わせたものです:
133             <programlisting>
134                 ( |e-c| &lt;= reltol * max(|e|,|c|) + abstol )
135             </programlisting>
136             comptype="matrix" の場合, ノルムが使用されます.
137             comptype="element" の場合,
138             絶対値が使用され, 全ての条件が true の場合に2つの行列が
139             ほぼ等しいとみなされます.
140         </para>
141         <para>
142             デフォルトの comptype="matrix" オプションでは
143             行列全体についての比較が行われ,
144             行列の差のノルムが使用されます.
145             comptype="element"オプションは要素毎の比較,
146             すなわち,行列の全ての要素がほぼ等しいこと,を行います.
147             これら2つの比較方法の選択は注意して行う必要があります.
148             例えば,基本関数の出力を要素毎に確認する際には,
149             行列の要素を順番に比較する必要があるため,
150             "element" 比較型を選ぶ必要があります.
151         </para>
152         <para>
153             IEEE値 %inf, -%inf または %nan が行列の中に存在する場合,
154             そのIEEE値が行列の同じ添字にある場合にのみほぼ等しいと
155             みなされます.
156         </para>
157         <para>
158             デフォルトの比較は相対誤差にもとづいており,
159             8桁が共通であることを保障します.
160             これにより,計算結果の上位桁の数値をアサーションすることができます.
161         </para>
162         <para>
163             この処理は,変数computedとexpectedがdoubleの行列である場合にのみ
164             動作します.
165             その他の場合にはエラーが発生します.
166         </para>
167         <para>
168             比較がcomputedがexpectedにほぼ等しくないことを示す場合,
169             <itemizedlist>
170                 <listitem>
171                     <para>
172                         errmsg出力変数が使用されない場合,
173                         エラーが生成され,
174                     </para>
175                 </listitem>
176                 <listitem>
177                     <para>
178                         errmsg出力変数が使用される場合,
179                         エラーは生成されません.
180                     </para>
181                 </listitem>
182             </itemizedlist>
183         </para>
184         <para>
185             値を比較する過程において,
186             %nan, +%inf, -%inf と残りの値を分割します.
187             nan値の比較はできません.
188             これが %nan 値がある場所の添字を比較する理由です.
189             無限大の値の差をとった場合,
190             %nan 値が生成されます.
191             これが +%inf 値がある場所の添字を比較する理由です.
192             -%inf 値の場合も同様です.
193             よって, nanおよび無限大を除く値が実際に比較されます.
194         </para>
195         <para>
196             デフォルトの comptype="element" オプションは
197             要素毎の比較,すなわち,
198             行列の全ての要素がほぼ等しいこと,を行います.
199             comptype="matrix" オプションは行列全体を比較し,
200             行列の差のノルムが使用されます.
201         </para>
202         <para>
203             一般に,相対許容誤差を機械イプシロン %eps の倍数に設定する
204             必要があります.
205             相対許容誤差は可能な範囲で最も小さい大きさとする必要が
206             あります.
207             つまり, 可能な限り許容誤差を精度良く設定する必要があります.
208             相対許容誤差を設定する手順では,
209             以下の値を順番に使用することを推奨します :
210             0 (全ての桁が正しい), %eps, 10*%eps, 100*%eps, 1.e3*%eps, 1.e4*%eps, ...,
211             1.e17*%eps (全ての桁が正しくない).
212             この例としては以下を参照ください.
213         </para>
214         <para>
215             この関数は複素数を処理します.
216             まず入力引数の実部を比較します.
217             これが失敗した場合,ただちにリターンします.
218             成功した場合,入力引数の虚部が比較されます.
219         </para>
220         <para>
221         </para>
222     </refsection>
223     <refsection>
224         <title>例</title>
225         <programlisting role="example"><![CDATA[
226 // 成功する比較.
227 // 相対誤差 :
228 assert_checkalmostequal ( 1 , 1 );
229 assert_checkalmostequal ( 1 , 1 , %eps );
230 assert_checkalmostequal ( ones(10,1) , ones(10,1) , %eps );
231 // 絶対誤差 :
232 assert_checkalmostequal ( 1.23456789123456789e-30 , 0 , 0 , 1.e-10 );
233 assert_checkalmostequal ( [1 %nan], [1 %nan] , 0 , %eps );
234 // 失敗する比較.
235 // エラーメッセージを出力 :
236 assert_checkalmostequal ( 1 , 2 , %eps );
237 // エラーメッセージを出力 :
238 flag = assert_checkalmostequal ( 1 , 2 , %eps )
239 // エラーメッセージは出力されない :
240 [flag,errmsg] = assert_checkalmostequal ( 1 , 2 , %eps )
241 assert_checkalmostequal ( 1 , [2 3] , %eps );
242 assert_checkalmostequal ( [%nan 1], [1 %nan] , %eps );
243 assert_checkalmostequal ( 1 + 5 * %eps , 1 , %eps );
244 assert_checkalmostequal ( 1.23456789123456789e-30 , 1.3e-30 , %eps );
245 // expectedがゼロでない場合,
246 // 相対誤差の許容値を %eps の倍数とする必要があります.
247 // 以下のテストは成功し, 最大実現可能な精度に対して
248 // 11桁以下が失われたことが示されます.
249 assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e11*%eps );
250 // 相対および絶対許容誤差を交換できません.
251 // 以下のテストはパスします: 予測値が0であるため,
252 // 絶対許容誤差を使用します.
253 assert_checkalmostequal ( 1.23456789e-30 , 0 , 0 , 1.e-10 );
254 // 以下のテストは失敗します: 相対許容誤差を使用します.
255 assert_checkalmostequal ( 0 , 1.23456789e-30 , 1.e-10 );
256 // 許容誤差を可能な限りタイトに設定する必要があります.
257 // 許容誤差が指定した数に対して小さすぎるため,以下のテストは失敗します.
258 assert_checkalmostequal ( 1.23456 , 1.23457 , %eps );
259 // 共通の桁数を取得します:
260 assert_computedigits(1.23456 , 1.23457)
261 // 5.09を返します...
262 // 精度の判定を行い, 受け入れ可能であると結論付けます:
263 assert_checkalmostequal ( 1.23456 , 1.23457 , 1.e-5 );
264 // assert_checkalmostequalの実用的な使用例を示します.
265 // ヒルバート行列に基づく,平均的に悪条件の線形方程式の
266 // システムを解きます.
267 n = 6;
268 // 予測値を設定します.
269 expected = ones(n,1);
270 A = testmatrix("hilb",n);
271 // 行列の条件数を計算します : ~10^8
272 ceil(log10(cond(A)))
273 // これは,理論的に失われる桁数が 8 であることを意味します,
274 // 指定した A と expected から右辺が計算されます.
275 b = A * expected;
276 // この場合, 部分ピボット選択付きのガウスアルゴリズムが
277 // 使用されます.
278 computed = A\b;
279 // 以下のテストは失敗します: いくつかの桁が失われます.
280 assert_checkalmostequal(computed,expected,%eps)
281 // 共通する実際の桁数を計算します: 10から12桁
282 assert_computedigits(computed, expected)
283 // この計算を受け入れます.
284 // 以下のテストはパスします.
285 assert_checkalmostequal(computed,expected,1.e5*%eps);
286 // 以下の例は comptype="element" と "matrix" の差異を示します.
287 // 以下のテストはパスしません.
288 assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 )
289 // 以下のテストは行列に基づく比較ではパスします.
290 assert_checkalmostequal ( [1 1.e5] , [2 1.e5] , 1.e-3 , [] , "matrix" )
291 // 以下のテストはパスします.
292 // IEEE値を考慮することは容易ではありません.
293 [flag,errmsg] = assert_checkalmostequal ( [1.2345 %inf -%inf %nan] , [1.2346 %inf -%inf %nan] , 1.e-4 )
294 // この関数は複素数を考慮します.
295 // 以下のテストはパスします.
296 assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-3 , [], "element" );
297 // 以下のテストは失敗します.
298 assert_checkalmostequal ( 1+%i , 1+(1+1.e-4)*%i , 1.e-5 , [], "element" );
299    ]]></programlisting>
300     </refsection>
301     <refsection>
302         <title>履歴</title>
303         <revhistory>
304             <revision>
305                 <revnumber>5.4.0</revnumber>
306                 <revdescription>関数が導入されました
307                 </revdescription>
308             </revision>
309             <revision>
310                 <revnumber>6.0.1</revnumber>
311                 <revdescription>
312                     Extension to polynomials.
313                 </revdescription>
314             </revision>
315         </revhistory>
316     </refsection>
317 </refentry>