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                 </listitem>
  58             </varlistentry>
  59             <varlistentry>
  60                 <term>options</term>
  61                 <listitem>
  62                     <para>文字列ベクトル</para>
  63                     <itemizedlist>
  64                         <listitem>
  65                             <para>"list" : モジュールで利用可能なベンチマークテストのリスト</para>
  66                         </listitem>
  67                         <listitem>
  68                             <para>"help" : Scilabコンソールにいくつかの使用例を表示</para>
  69                         </listitem>
  70                         <listitem>
  71                             <para>
  72                                 <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.
  73                             </para>
  74                         </listitem>
  75                     </itemizedlist>
  76                 </listitem>
  77             </varlistentry>
  78             <varlistentry>
  79                 <term>exportToFile</term>
  80                 <listitem>
  81                     <para>a single string</para>
  82                     <para>
  83                         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>.
  84                     </para>
  85                     <para>
  86                         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.
  87                     </para>
  88                 </listitem>
  89             </varlistentry>
  90             <varlistentry>
  91                 <term>modutests_names</term>
  92                 <listitem>
  93                     <para>a N-by-2 matrix of strings</para>
  94                     <para>
  95                         the first column lists the modules tested by <function>bench_run</function>, the second column lists the names of the benchmarks
  96                     </para>
  97                 </listitem>
  98             </varlistentry>
  99             <varlistentry>
 100                 <term>elapsed_time</term>
 101                 <listitem>
 102                     <para>a vector of doubles</para>
 103                     <para>the execution time for each benchmark</para>
 104                 </listitem>
 105             </varlistentry>
 106             <varlistentry>
 107                 <term>nb_iterations</term>
 108                 <listitem>
 109                     <para>a vector of doubles of size N</para>
 110                     <para>the number of iterations of respective test</para>
 111                 </listitem>
 112             </varlistentry>
 113         </variablelist>
 114     </refsection>
 115     <refsection>
 116         <title>説明</title>
 117         <para>
 118             Performs benchmark tests, measures execution time and produces a report about benchmark tests.
 119         </para>
 120         <para>
 121             Searches for .tst files in benchmark test library or input parameter path under <literal>tests/benchmark</literal> subdirectory,
 122             executes them 10000 times and displays a report about execution time.
 123         </para>
 124         <para>
 125             Special tags may be inserted in the .tst file, which help to
 126             control the processing of the corresponding test. These tags
 127             are expected to be found in Scilab comments.
 128         </para>
 129         <para>These are the available tags :</para>
 130         <itemizedlist>
 131             <listitem>
 132                 <para>
 133                     <literal>&lt;-- BENCH NB RUN : 10 --&gt;</literal>
 134                 </para>
 135                 <para>
 136                     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.
 137                 </para>
 138             </listitem>
 139             <listitem>
 140                 <programlisting role="no-scilab-exec"><![CDATA[
 141 //    <-- BENCH START -->
 142 [code to be executed]
 143 //    <-- BENCH END -->
 144 ]]></programlisting>
 145                 <para>
 146                     Code between these tags will be repeated. Code before will be executed before the repetition, code after will be executed after the repetition.
 147                     If these are not present, the entire code will be repeated.
 148                 </para>
 149             </listitem>
 150         </itemizedlist>
 151     </refsection>
 152     <refsection>
 153         <title>Examples</title>
 154         <para>Some simple examples of invocation of bench_run</para>
 155         <programlisting role="example"><![CDATA[
 156 // Launch all tests
 157 // This may take some time...
 158 // bench_run();
 159 // bench_run([]);
 160 // bench_run([],[]);
 161
 162 // Test one or several module
 163 bench_run('core');
 164 bench_run('core',[]);
 165 bench_run(['core','string']);
 166
 167 // Launch one or several test in a specified module
 168 bench_run('core',['trycatch','opcode']);
 169
 170 // With options
 171 bench_run([],[],'list');
 172 bench_run([],[],'help');
 173 bench_run("string", [], 'nb_run=100');
 174 // results in an output file in the current directory
 175 bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
 176 // results in an output directory, TMPDIR/benchmarks is the default
 177 bench_run("string", [], 'nb_run=100', TMPDIR);
 178 ]]></programlisting>
 179         <para>ベンチマークファイルの例. このファイルはファイル
 180             SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tstに対応します.
 181         </para>
 182         <programlisting role="example"><![CDATA[
 183 // =============================================================================
 184 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 185 // Copyright (C) 2007-2008 - INRIA
 186 //
 187 //  This file is distributed under the same license as the Scilab package.
 188 // =============================================================================
 189
 190 //==============================================================================
 191 // Benchmark for chol function
 192 //==============================================================================
 193
 194 // <-- BENCH NB RUN : 10 -->
 195
 196 a = 0;
 197 b = 0;
 198 a = rand(900, 900, 'n');
 199 a = a'*a;
 200
 201 // <-- BENCH START -->
 202 b = chol(a);
 203 // <-- BENCH END -->
 204 ]]></programlisting>
 205         <para>テストの結果</para>
 206         <screen><![CDATA[
 207 -->bench_run('linear_algebra','bench_chol')
 208
 209 For Loop (as reference) ...........................      33.20 ms [ 1000000 x]
 210
 211 001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]
 212  ]]></screen>
 213     </refsection>
 214     <refsection role="see also">
 215         <title>参照</title>
 216         <simplelist type="inline">
 217             <member>
 218                 <link linkend="test_run">test_run</link>
 219             </member>
 220         </simplelist>
 221     </refsection>
 222     <refsection role="history">
 223         <title>History</title>
 224         <revhistory>
 225             <revision>
 226                 <revnumber>6.0</revnumber>
 227                 <revdescription>
 228                     <itemizedlist>
 229                         <listitem>
 230                             <literal>bench_run()</literal> can now return its results through the new
 231                             <literal>modutests_names</literal>, <literal>elapsed_time</literal>
 232                             and <literal>nb_iterations</literal> output parameters.
 233                         </listitem>
 234                         <listitem>
 235                             Exportation of results in XML is now possible
 236                         </listitem>
 237                         <listitem>
 238                             Global configuration settings mode(),
 239                             format(), ieee(), warning() and funcprot()
 240                             are now protected against tests.
 241                         </listitem>
 242                     </itemizedlist>
 243                 </revdescription>
 244             </revision>
 245         </revhistory>
 246     </refsection>
 247 </refentry>