1 <?xml version="1.0" encoding="UTF-8"?>
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
6 * Copyright (C) 2012 - 2016 - Scilab Enterprises
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.
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">
18 <refname>bench_run</refname>
19 <refpurpose>ベンチマークテストを実行</refpurpose>
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]])
35 <para>文字列ベクトル. モジュール名またはツールボックスの絶対パスを指定します.</para>
39 <term>path_to_module</term>
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
44 /path/to/directory/<emphasis role="bold">tests/benchmarks</emphasis>
46 .Used for homemade benchmarks.
51 <term>test_name</term>
53 <para>a vector of string. Contains the names of the tests to perform.</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.
65 <para>"list" : モジュールで利用可能なベンチマークテストのリスト</para>
68 <para>"help" : Scilabコンソールにいくつかの使用例を表示</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.
79 <term>exportToFile</term>
81 <para>a single string</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>.
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.
91 <term>modutests_names</term>
93 <para>a N-by-2 matrix of strings</para>
95 the first column lists the modules tested by <function>bench_run</function>, the second column lists the names of the benchmarks
100 <term>elapsed_time</term>
102 <para>a vector of doubles</para>
103 <para>the execution time for each benchmark</para>
107 <term>nb_iterations</term>
109 <para>a vector of doubles of size N</para>
110 <para>the number of iterations of respective test</para>
118 Performs benchmark tests, measures execution time and produces a report about benchmark tests.
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.
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.
129 <para>These are the available tags :</para>
133 <literal><-- BENCH NB RUN : 10 --></literal>
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.
140 <programlisting role="no-scilab-exec"><![CDATA[
141 // <-- BENCH START -->
142 [code to be executed]
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.
153 <title>Examples</title>
154 <para>Some simple examples of invocation of bench_run</para>
155 <programlisting role="example"><![CDATA[
157 // This may take some time...
162 // Test one or several module
164 bench_run('core',[]);
165 bench_run(['core','string']);
167 // Launch one or several test in a specified module
168 bench_run('core',['trycatch','opcode']);
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);
179 <para>ベンチマークファイルの例. このファイルはファイル
180 SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tstに対応します.
182 <programlisting role="example"><![CDATA[
183 // =============================================================================
184 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
185 // Copyright (C) 2007-2008 - INRIA
187 // This file is distributed under the same license as the Scilab package.
188 // =============================================================================
190 //==============================================================================
191 // Benchmark for chol function
192 //==============================================================================
194 // <-- BENCH NB RUN : 10 -->
198 a = rand(900, 900, 'n');
201 // <-- BENCH START -->
207 -->bench_run('linear_algebra','bench_chol')
209 For Loop (as reference) ........................... 33.20 ms [ 1000000 x]
211 001/001 - [linear_algebra] bench_chol ...................... 1233.93 ms [ 10 x]
214 <refsection role="see also">
216 <simplelist type="inline">
218 <link linkend="test_run">test_run</link>
222 <refsection role="history">
223 <title>History</title>
226 <revnumber>6.0</revnumber>
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.
235 Exportation of results in XML is now possible
238 Global configuration settings mode(),
239 format(), ieee(), warning() and funcprot()
240 are now protected against tests.