[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / development_tools / help / ja_JP / bench_run.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) INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="bench_run" xml:lang="ja">
17     <refnamediv>
18         <refname>bench_run</refname>
19         <refpurpose>ベンチマークテストを実行</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>呼び出し手順</title>
23         <synopsis>
24             [modutests_names, elapsed_time, nb_iterations] = bench_run()
25             [modutests_names, elapsed_time, nb_iterations] = bench_run(module[, test_name[, options, [exportToFile]])
26             [modutests_names, elapsed_time, nb_iterations] = bench_run(path_to_module[, test_name[, options, [exportToFile]])
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>引数</title>
31         <variablelist>
32             <varlistentry>
33                 <term>module</term>
34                 <listitem>
35                     <para>文字列ベクトル. モジュール名またはツールボックスの絶対パスを指定します.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>path_to_module</term>
40                 <listitem>
41                     <para>
42                         a vector of string. Contains the paths to directories of modules to test. If <literal>"/path/to/directory"</literal> is given as input parameter, tests are retrieved in the subdirectory
43                         <literal>
44                             /path/to/directory/<emphasis role="bold">tests/benchmarks</emphasis>
45                         </literal>
46                         .Used for homemade benchmarks.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>test_name</term>
52                 <listitem>
53                     <para>a vector of string. Contains the names of the tests to perform.</para>
54                     <para>
55                         The name of a test is its filename without <literal>.tst</literal>. If several modules or directory are given as first input parameter, scans for tests in each of these modules or directory.
56                     </para>
57                     <note>
58                         Partial test names are allowed to run a subset
59                         of benchmarks dedicated to the same function/feature.
60                         For instance, specifying <literal>"ascii"</literal>
61                         will select all tests (in given module(s)) whose names
62                         contain <literal>"ascii"</literal> (See examples).
63                     </note>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>options</term>
68                 <listitem>
69                     <para>文字列ベクトル</para>
70                     <itemizedlist>
71                         <listitem>
72                             <para>"list" : モジュールで利用可能なベンチマークテストのリスト</para>
73                         </listitem>
74                         <listitem>
75                             <para>"help" : Scilabコンソールにいくつかの使用例を表示</para>
76                         </listitem>
77                         <listitem>
78                             <para>
79                                 <literal>"nb_run=value"</literal>: runs each benchmark <literal>value</literal> times ; by default <function>bench_run</function> runs 10000 times the code between BENCH START and BENCH END tags (see below). Overrides any <literal>BENCH NB RUN</literal> specified in the benchmark test files.
80                             </para>
81                         </listitem>
82                     </itemizedlist>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>exportToFile</term>
87                 <listitem>
88                     <para>a single string</para>
89                     <para>
90                         File path to the result of the <function>bench_run</function> in xml format. By default, or if <literal>"", "[]"</literal> or <literal>[]</literal> is given, the output directory is <literal>TMPDIR/benchmarks/</literal>.
91                     </para>
92                     <para>
93                         If <literal>exportToFile</literal> is a directory, creates a timestamped output file is the directory, otherwize creates the file <literal>exportToFile</literal>. If the file could not be created a warning is issued and the file is created under <literal>TMPDIR/benchmarks/</literal> instead.
94                     </para>
95                 </listitem>
96             </varlistentry>
97             <varlistentry>
98                 <term>modutests_names</term>
99                 <listitem>
100                     <para>a N-by-2 matrix of strings</para>
101                     <para>
102                         the first column lists the modules tested by <function>bench_run</function>, the second column lists the names of the benchmarks
103                     </para>
104                 </listitem>
105             </varlistentry>
106             <varlistentry>
107                 <term>elapsed_time</term>
108                 <listitem>
109                     <para>a vector of doubles</para>
110                     <para>the execution time for each benchmark</para>
111                 </listitem>
112             </varlistentry>
113             <varlistentry>
114                 <term>nb_iterations</term>
115                 <listitem>
116                     <para>a vector of doubles of size N</para>
117                     <para>the number of iterations of respective test</para>
118                 </listitem>
119             </varlistentry>
120         </variablelist>
121     </refsection>
122     <refsection>
123         <title>説明</title>
124         <para>
125             Performs benchmark tests, measures execution time and produces a report about benchmark tests.
126         </para>
127         <para>
128             Searches for .tst files in benchmark test library or input parameter path under <literal>tests/benchmark</literal> subdirectory,
129             executes them 10000 times and displays a report about execution time.
130         </para>
131         <para>
132             Special tags may be inserted in the .tst file, which help to
133             control the processing of the corresponding test. These tags
134             are expected to be found in Scilab comments.
135         </para>
136         <para>These are the available tags :</para>
137         <itemizedlist>
138             <listitem>
139                 <para>
140                     <literal>&lt;-- BENCH NB RUN : 10 --&gt;</literal>
141                 </para>
142                 <para>
143                     By default, this test will be repeated 10 times, unless the "nb_run=###"<literal>bench_run(..)</literal> option is used. The value given for the flag can be set to any integer value.
144                 </para>
145             </listitem>
146             <listitem>
147                 <programlisting role="no-scilab-exec"><![CDATA[
148 //    <-- BENCH START -->
149 [code to be executed]
150 //    <-- BENCH END -->
151 ]]></programlisting>
152                 <para>
153                     Code between these tags will be repeated.
154                     Any code written before/after will be executed only once
155                     before/after the repetition, without being timed.
156                     If these tags are missing, the entire code will be repeated.
157                 </para>
158             </listitem>
159         </itemizedlist>
160     </refsection>
161     <refsection>
162         <title>Examples</title>
163         <para>Some simple examples of invocation of bench_run</para>
164         <programlisting role="example"><![CDATA[
165 // Launch all tests
166 // This may take some time...
167 // bench_run();
168 // bench_run([]);
169 // bench_run([],[]);
170
171 // Test one or several module
172 bench_run('core');
173 bench_run('core',[]);
174 bench_run(['core','string']);
175
176 // Launch one or several test in a specified module
177 bench_run('core',['trycatch','opcode']);
178
179 // With options
180 bench_run([],[],'list');
181 bench_run([],[],'help');
182 bench_run("string", [], 'nb_run=100');
183 // results in an output file in the current directory
184 bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
185 // results in an output directory, TMPDIR/benchmarks is the default
186 bench_run("string", [], 'nb_run=100', TMPDIR);
187 ]]></programlisting>
188         <para>ベンチマークファイルの例. このファイルはファイル
189             SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tstに対応します.
190         </para>
191         <programlisting role="example"><![CDATA[
192 // =============================================================================
193 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
194 // Copyright (C) 2007-2008 - INRIA
195 //
196 //  This file is distributed under the same license as the Scilab package.
197 // =============================================================================
198
199 //==============================================================================
200 // Benchmark for chol function
201 //==============================================================================
202
203 // <-- BENCH NB RUN : 10 -->
204
205 a = 0;
206 b = 0;
207 a = rand(900, 900, 'n');
208 a = a'*a;
209
210 // <-- BENCH START -->
211 b = chol(a);
212 // <-- BENCH END -->
213 ]]></programlisting>
214         <para>テストの結果</para>
215         <screen><![CDATA[
216 -->bench_run('linear_algebra','bench_chol')
217
218            For Loop (as reference) ...........................      33.20 ms [ 1000000 x]
219
220  001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]
221 ]]></screen>
222     <para>
223     Running a subset of dedicated benchmarks by using a partial/generic testname:
224     <screen><![CDATA[
225 --> bench_run string ascii
226
227           For Loop (as reference) ...........................      102.98 ms [ 1000000 x]
228
229  001/005 - [string] bench_ascii_1 ...........................      447.40 ms [   10000 x]
230  002/005 - [string] bench_ascii_2 ...........................    31727.98 ms [ 1000000 x]
231  003/005 - [string] bench_ascii_3 ...........................     4173.69 ms [   10000 x]
232  004/005 - [string] bench_ascii_4 ...........................     5145.06 ms [   10000 x]
233  005/005 - [string] bench_ascii_UTF8 ........................       23.26 ms [      10 x]
234 ]]></screen>
235     </para>
236     </refsection>
237     <refsection role="see also">
238         <title>参照</title>
239         <simplelist type="inline">
240             <member>
241                 <link linkend="test_run">test_run</link>
242             </member>
243             <member>
244                 <link linkend="covStart">coverage</link>
245             </member>
246             <member>
247                 <link linkend="slint">slint</link>
248             </member>
249             <member>
250                 <link linkend="debug">debug</link>
251             </member>
252         </simplelist>
253     </refsection>
254     <refsection role="history">
255         <title>History</title>
256         <revhistory>
257             <revision>
258                 <revnumber>6.0</revnumber>
259                 <revdescription>
260                     <itemizedlist>
261                         <listitem>
262                             <literal>bench_run()</literal> can now return its results through the new
263                             <literal>modutests_names</literal>, <literal>elapsed_time</literal>
264                             and <literal>nb_iterations</literal> output parameters.
265                         </listitem>
266                         <listitem>
267                             Exportation of results in XML is now possible
268                         </listitem>
269                         <listitem>
270                             Global configuration settings mode(),
271                             format(), ieee(), warning() and funcprot()
272                             are now protected against tests.
273                         </listitem>
274                         <listitem>
275                             Partial/generic test names are now allowed to run a
276                             subset
277                             of benchmarks dedicated to the same function/feature.
278                         </listitem>
279                     </itemizedlist>
280                 </revdescription>
281             </revision>
282         </revhistory>
283     </refsection>
284 </refentry>