* Bug #14423 fixed - bench_run did not have a return value, export file was not confi...
[scilab.git] / scilab / modules / development_tools / help / fr_FR / 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="fr">
17     <refnamediv>
18         <refname>bench_run</refname>
19         <refpurpose>Lance les tests de performances</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntaxe</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>Vecteur de chaînes de caractères. Noms des modules internes à Scilab à tester.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>path_to_module</term>
40                 <listitem>
41                     <para>
42                         Vecteur de chaînes de caractères. Contient les chemins des modules à tester. Si <literal>"/chemin/vers/module"</literal> est donné en argument d'entrée, les tests sont récupérés dans le sous répertoire
43                         <literal>
44                             /chemin/vers/module/<emphasis role="bold">tests/benchmarks</emphasis>
45                         </literal>
46                         .A utiliser pour les tests de performance maison.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>test_name</term>
52                 <listitem>
53                     <para>Vecteur de chaînes de caractères. Contient les noms des tests à effectuer.</para>
54                     <para>
55                         Le nom d'un test est le nom du fichier sans <literal>.tst</literal>. Si plusieurs modules ou répertoires sont donnés comme premier argument d'entrée, recherche les tests dans chacun de ces modules ou répertoires.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>options</term>
61                 <listitem>
62                     <para>Vecteur de chaînes de caractères. Options parmi:</para>
63                     <itemizedlist>
64                         <listitem>
65                             <para>
66                                 <literal>"list"</literal> : liste les tests de performance (<literal>test_name</literal>) présents dans un module
67                             </para>
68                         </listitem>
69                         <listitem>
70                             <para>
71                                 <literal>"help"</literal> : affiche quelques exemples d'utilisation en console
72                             </para>
73                         </listitem>
74                         <listitem>
75                             <para>
76                                 <literal>"nb_run=value"</literal> : lance <literal>value</literal> fois chaque tests, par défaut <function>bench_run</function> effectue 10000 fois le code présent entre les balises BENCH START et BENCH END (voir ci-après). Remplace la valeur spécifiée dans la balise <literal>BENCH NB RUN</literal> pour les scripts de tests.
77                             </para>
78                         </listitem>
79                     </itemizedlist>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>exportToFile</term>
84                 <listitem>
85                     <para>une chaîne de caractères</para>
86                     <para>
87                         Chemin du fichier d'export des résultats de <function>bench_run</function> au format xml. Par défaut ou si <literal>"", []</literal> ou <literal>"[]"</literal> sont donnés en paramètres d'entrée, the répertoire de sortie est <literal>TMPDIR/benchmarks/</literal>.
88                     </para>
89                     <para>
90                         Si <literal>exportToFile</literal> est un répertoire, crée un fichier horodaté dans le répertoire, sinon crée le fichier <literal>exportToFile</literal>. Si ce fichier n'a pas pu être créé, un avertissement est affiché et le fichier est créé sous le répertoire <literal>TMPDIR/benchmarks/</literal>.
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>modutests_names</term>
96                 <listitem>
97                     <para>matrice de chaînes de caractères de taille N-par-2</para>
98                     <para>
99                         La première colonne représente les modules et chemins vers les fichiers testés par <function>bench_run</function>, la seconde colonne représente les noms des tests de performance.
100                     </para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>elapsed_time</term>
105                 <listitem>
106                     <para>vecteur de décimaux</para>
107                     <para>temps d'execution pour chaque test de performance</para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>nb_iterations</term>
112                 <listitem>
113                     <para>vecteur de décimaux de taille N</para>
114                     <para>nombre de fois que chaque a été lancé respectivement</para>
115                 </listitem>
116             </varlistentry>
117         </variablelist>
118     </refsection>
119     <refsection>
120         <title>Description</title>
121         <para>
122             Effectue des tests de performance, mesure les temps d'exécution et produit un rapport d'exécution pour ces tests.
123         </para>
124         <para>
125             Recherche tous les fichiers <literal>.tst</literal> sous le répertoire <literal>tests/benchmarks</literal> présent dans les modules internes scilab ou dans les chemins fournis en variable d'entrée, exécute ces fichiers 10000 fois et produit un rapport d'exécution.
126         </para>
127         <para>
128             Des balises présentes dans le fichier <literal>.tst</literal> permettent de contrôler le processus du test correspondant. Ces balises sont recherchées dans les commentaires du scripts.
129         </para>
130         <para>Les balises disponibles sont :</para>
131         <itemizedlist>
132             <listitem>
133                 <para>
134                     <literal>&lt;-- BENCH NB RUN : 10 --&gt;</literal>
135                 </para>
136                 <para>
137                     Par défaut, le test sera répété 10 fois, sauf si l'option <literal>"nb_run=###"</literal> de <literal>bench_run(...)</literal> est utilisée. Toute valeur entière peut être donnée pour cette balise.
138                 </para>
139             </listitem>
140             <listitem>
141                 <para>
142                     <programlisting role="no-scilab-exec"><![CDATA[
143 //    <-- BENCH START -->
144 [code to be executed]
145 //    <-- BENCH END -->
146 ]]></programlisting>
147                 </para>
148                 <para>
149                     Le code entre ces deux balises sera répétée lors du test de performance.
150                     Le code présent avant ces balises est exécuté avant la répétition, le code après ces balises est exécuté après.
151                     Si ces balises sont absentes du code, le code entier sera répété.
152                 </para>
153             </listitem>
154         </itemizedlist>
155     </refsection>
156     <refsection>
157         <title>Exemples</title>
158         <para>
159             Quelques exemples d'utilisation de <function>bench_run</function>
160         </para>
161         <programlisting role="example"><![CDATA[
162 // Lance tous les tests
163 // Cela peut prendre du temps...
164 // bench_run();
165 // bench_run([]);
166 // bench_run([],[]);
167
168 // Test d'un ou de plusieurs modules
169 bench_run('core');
170 bench_run('core',[]);
171 bench_run(['core','string']);
172
173 // Lance des tests spécifiques sur un module
174 bench_run('core',['trycatch','opcode']);
175
176 // Avec des options
177 bench_run([],[],'list');
178 bench_run([],[],'help');
179 bench_run("string", [], 'nb_run=100');
180 // Résultats dans un ficher sous le répertoire local
181 bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
182 // Résultats dans un répertoire, par défaut sous TMPDIR/benchmarks
183 bench_run("string", [], 'nb_run=100', TMPDIR);
184  ]]></programlisting>
185         <para> Exemple de fichier de test
186             SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tst.
187         </para>
188         <programlisting role="example"><![CDATA[
189 // =============================================================================
190 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
191 // Copyright (C) 2007-2008 - INRIA
192 //
193 //  This file is distributed under the same license as the Scilab package.
194 // =============================================================================
195
196 //==============================================================================
197 // Benchmark for chol function
198 //==============================================================================
199
200 // <-- BENCH NB RUN : 10 -->
201
202 a = 0;
203 b = 0;
204 a = rand(900, 900, 'n');
205 a = a'*a;
206
207 // <-- BENCH START -->
208 b = chol(a);
209 // <-- BENCH END -->
210 ]]></programlisting>
211         <para>résultat du test</para>
212         <screen><![CDATA[
213 -->bench_run('linear_algebra','bench_chol')
214
215 For Loop (as reference) ...........................      33.20 ms [ 1000000 x]
216
217 001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]
218   ]]></screen>
219     </refsection>
220     <refsection role="see also">
221         <title>Voir aussi</title>
222         <simplelist type="inline">
223             <member>
224                 <link linkend="test_run">test_run</link>
225             </member>
226         </simplelist>
227     </refsection>
228     <refsection role="history">
229         <title>Historique</title>
230         <revhistory>
231             <revision>
232                 <revnumber>6.0</revnumber>
233                 <revdescription>
234                     <itemizedlist>
235                         <listitem>
236                             <literal>bench_run()</literal> peut maintenant retourner les résultats des tests de performance via les nouveaux paramètres de sortie
237                             <literal>modutests_names</literal>, <literal>elapsed_time</literal> et <literal>nb_iterations</literal>
238                         </listitem>
239                         <listitem>
240                             L'export des résultats au format XML est désormais possible
241                         </listitem>
242                         <listitem>
243                             Les paramètres de  configuration globale
244                             mode(),format(), ieee(), warning() et funcprot()
245                             sont protégés lors des tests.
246                         </listitem>
247                     </itemizedlist>
248                 </revdescription>
249             </revision>
250         </revhistory>
251     </refsection>
252 </refentry>