* Bug #14423 fixed - bench_run did not have a return value, export file was not confi...
[scilab.git] / scilab / modules / development_tools / help / ja_JP / bench_run.xml
index fbddd85..ab28003 100644 (file)
@@ -21,8 +21,9 @@
     <refsynopsisdiv>
         <title>呼び出し手順</title>
         <synopsis>
-            bench_run()
-            bench_run(module[,test_name[,options]])
+            [modutests_names, elapsed_time, nb_iterations] = bench_run()
+            [modutests_names, elapsed_time, nb_iterations] = bench_run(module[, test_name[, options, [exportToFile]])
+            [modutests_names, elapsed_time, nb_iterations] = bench_run(path_to_module[, test_name[, options, [exportToFile]])
         </synopsis>
     </refsynopsisdiv>
     <refsection>
                 </listitem>
             </varlistentry>
             <varlistentry>
+                <term>path_to_module</term>
+                <listitem>
+                    <para>
+                        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
+                        <literal>
+                            /path/to/directory/<emphasis role="bold">tests/benchmarks</emphasis>
+                        </literal>
+                        .Used for homemade benchmarks.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
                 <term>test_name</term>
                 <listitem>
-                    <para>文字列ベクトル</para>
+                    <para>a vector of string. Contains the names of the tests to perform.</para>
+                    <para>
+                        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.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                     <para>文字列ベクトル</para>
                     <itemizedlist>
                         <listitem>
-                            <para>list : モジュールで利用可能なベンチマークテストのリスト</para>
+                            <para>"list" : モジュールで利用可能なベンチマークテストのリスト</para>
                         </listitem>
                         <listitem>
-                            <para>help : Scilabコンソールにいくつかの使用例を表示</para>
+                            <para>"help" : Scilabコンソールにいくつかの使用例を表示</para>
                         </listitem>
                         <listitem>
-                            <para>nb_run=value : ベンチマークテストを指定回数反復実行</para>
+                            <para>
+                                <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.
+                            </para>
                         </listitem>
                     </itemizedlist>
                 </listitem>
             </varlistentry>
+            <varlistentry>
+                <term>exportToFile</term>
+                <listitem>
+                    <para>a single string</para>
+                    <para>
+                        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>.
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>modutests_names</term>
+                <listitem>
+                    <para>a N-by-2 matrix of strings</para>
+                    <para>
+                        the first column lists the modules tested by <function>bench_run</function>, the second column lists the names of the benchmarks
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>elapsed_time</term>
+                <listitem>
+                    <para>a vector of doubles</para>
+                    <para>the execution time for each benchmark</para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>nb_iterations</term>
+                <listitem>
+                    <para>a vector of doubles of size N</para>
+                    <para>the number of iterations of respective test</para>
+                </listitem>
+            </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
         <title>説明</title>
         <para>
-            ベンチマークテストライブラリの .tst ファイルを探して実行し,実行時間に関する
-            レポートを表示します.
-            .tst ファイルはSCI+"/modules/*/tests/benchmark"ディレクトリで探されます.
+            Performs benchmark tests, measures execution time and produces a report about benchmark tests.
+        </para>
+        <para>
+            Searches for .tst files in benchmark test library or input parameter path under <literal>tests/benchmark</literal> subdirectory,
+            executes them 10000 times and displays a report about execution time.
         </para>
         <para>
-            テスト処理を制御しやすくするために,.tstファイルに特殊なタグを挿入できます.
-            これらのタグはScilabコメントとして記入します.
+            Special tags may be inserted in the .tst file, which help to
+            control the processing of the corresponding test. These tags
+            are expected to be found in Scilab comments.
         </para>
-        <para>利用可能なタグを以下に示します :</para>
+        <para>These are the available tags :</para>
         <itemizedlist>
             <listitem>
                 <para>
-                    &lt;-- BENCH NB RUN : 10 --&gt;
-                    このテストは10回反復実行されます.
+                    <literal>&lt;-- BENCH NB RUN : 10 --&gt;</literal>
+                </para>
+                <para>
+                    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.
                 </para>
             </listitem>
             <listitem>
+                <programlisting role="no-scilab-exec"><![CDATA[
+//    <-- BENCH START -->
+[code to be executed]
+//    <-- BENCH END -->
+]]></programlisting>
                 <para>
-                    &lt;-- BENCH START --&gt;
-                    &lt;-- BENCH END --&gt;
-                    ベンチマークの関心がある部分をこれらのタグで括りますThe 
+                    Code between these tags will be repeated. Code before will be executed before the repetition, code after will be executed after the repetition.
+                    If these are not present, the entire code will be repeated.
                 </para>
             </listitem>
         </itemizedlist>
     </refsection>
     <refsection>
-        <title>例</title>
-        <para>bench_runを実行例をいくつか示します</para>
+        <title>Examples</title>
+        <para>Some simple examples of invocation of bench_run</para>
         <programlisting role="example"><![CDATA[
-// 全てのテストを実行
-bench_run();
-bench_run([]);
-bench_run([],[]);
-// 1つまたは複数のモジュールをテスト
+// Launch all tests
+// This may take some time...
+// bench_run();
+// bench_run([]);
+// bench_run([],[]);
+
+// Test one or several module
 bench_run('core');
 bench_run('core',[]);
 bench_run(['core','string']);
-// 指定したモジュールの1つまたは複数のテストを実行
+
+// Launch one or several test in a specified module
 bench_run('core',['trycatch','opcode']);
-// オプションを指定
+
+// With options
 bench_run([],[],'list');
 bench_run([],[],'help');
-bench_run([],[],'nb_run=2000');
- ]]></programlisting>
+bench_run("string", [], 'nb_run=100');
+// results in an output file in the current directory
+bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
+// results in an output directory, TMPDIR/benchmarks is the default
+bench_run("string", [], 'nb_run=100', TMPDIR);
+]]></programlisting>
         <para>ベンチマークファイルの例. このファイルはファイル
             SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tstに対応します.
         </para>
@@ -116,24 +186,30 @@ bench_run([],[],'nb_run=2000');
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
+
 //==============================================================================
 // Benchmark for chol function
 //==============================================================================
+
 // <-- BENCH NB RUN : 10 -->
+
 a = 0;
 b = 0;
 a = rand(900, 900, 'n');
 a = a'*a;
+
 // <-- BENCH START -->
 b = chol(a);
 // <-- BENCH END -->
- ]]></programlisting>
+]]></programlisting>
         <para>テストの結果</para>
-        <programlisting role="example"><![CDATA[
+        <screen><![CDATA[
 -->bench_run('linear_algebra','bench_chol')
-           For Loop (as reference) ...........................      143.00 ms [ 1000000 x]
-  001/001 - [linear_algebra] bench_chol ......................      130.60 ms [      10 x]
- ]]></programlisting>
+
+For Loop (as reference) ...........................      33.20 ms [ 1000000 x]
+
+001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]
+ ]]></screen>
     </refsection>
     <refsection role="see also">
         <title>参照</title>
@@ -143,4 +219,29 @@ b = chol(a);
             </member>
         </simplelist>
     </refsection>
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>6.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <literal>bench_run()</literal> can now return its results through the new
+                            <literal>modutests_names</literal>, <literal>elapsed_time</literal>
+                            and <literal>nb_iterations</literal> output parameters.
+                        </listitem>
+                        <listitem>
+                            Exportation of results in XML is now possible
+                        </listitem>
+                        <listitem>
+                            Global configuration settings mode(),
+                            format(), ieee(), warning() and funcprot()
+                            are now protected against tests.
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>