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