bench_run Lance les tests de performances

## Syntaxe

                [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]])

## Arguments

module

  Vecteur de chaînes de caractères. Noms des modules internes à Scilab à tester.

path_to_module

  Vecteur de chaînes de caractères. Contient les chemins des modules à tester. Si `"/chemin/vers/module"` est donné en argument d'entrée, les tests sont récupérés dans le sous répertoire `/chemin/vers/module/tests/benchmarks` .A utiliser pour les tests de performance maison.

test_name

  Vecteur de chaînes de caractères. Contient les noms des tests à effectuer.

  Le nom d'un test est le nom du fichier sans `.tst`. 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.

  Il est possible d'utiliser un libellé partiel/générique afin de lancer plusieurs bancs-tests dédiés à la même fonction/fonctionnalité. Par exemple, spécifier `"ascii"` sélectionnera tous les tests (dans les modules ciblés) dont le nom contient `"ascii"` (voir les exemples).
options

  Vecteur de chaînes de caractères. Options parmi:

  - `"list"` : liste les tests de performance (`test_name`) présents dans un module

  - `"help"` : affiche quelques exemples d'utilisation en console

  - `"nb_run=value"` : lance `value` fois chaque tests, par défaut `bench_run` 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 `BENCH NB RUN` pour les scripts de tests.

exportToFile

  une chaîne de caractères

  Chemin du fichier d'export des résultats de `bench_run` au format xml. Par défaut ou si `"", []` ou `"[]"` sont donnés en paramètres d'entrée, the répertoire de sortie est `TMPDIR/benchmarks/`.

  Si `exportToFile` est un répertoire, crée un fichier horodaté dans le répertoire, sinon crée le fichier `exportToFile`. Si ce fichier n'a pas pu être créé, un avertissement est affiché et le fichier est créé sous le répertoire `TMPDIR/benchmarks/`.

modutests_names

  matrice de chaînes de caractères de taille N-par-2

  La première colonne représente les modules et chemins vers les fichiers testés par `bench_run`, la seconde colonne représente les noms des tests de performance.

elapsed_time

  vecteur de décimaux

  temps d'execution pour chaque test de performance

nb_iterations

  vecteur de décimaux de taille N

  nombre de fois que chaque a été lancé respectivement

## Description

Effectue des tests de performance, mesure les temps d'exécution et produit un rapport d'exécution pour ces tests.

Recherche tous les fichiers `.tst` sous le répertoire `tests/benchmarks` 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.

Des balises présentes dans le fichier `.tst` permettent de contrôler le processus du test correspondant. Ces balises sont recherchées dans les commentaires du scripts.

Les balises disponibles sont :

- `<-- BENCH NB RUN : 10 -->`

  Par défaut, le test sera répété 10 fois, sauf si l'option `"nb_run=###"` de `bench_run(...)` est utilisée. Toute valeur entière peut être donnée pour cette balise.

-     //    <-- BENCH START -->
      [code à exécuter]
      //    <-- BENCH END -->

  Le code entre ces deux balises sera répétée lors du test de performance. Le code présent avant/après ces balises est exécuté une seule fois avant/après la répétition et n'est pas chronométré. Si ces balises sont absentes, le code entier sera répété.

## Exemples

Quelques exemples d'utilisation de `bench_run`

    // Lance tous les tests
    // Cela peut prendre du temps...
    // bench_run();
    // bench_run([]);
    // bench_run([],[]);

    // Test d'un ou de plusieurs modules
    bench_run('core');
    bench_run('core',[]);
    bench_run(['core','string']);

    // Lance des tests spécifiques sur un module
    bench_run('core',['trycatch','opcode']);

    // Avec des options
    bench_run([],[],'list');
    bench_run([],[],'help');
    bench_run("string", [], 'nb_run=100');
    // Résultats dans un ficher sous le répertoire local
    bench_run("string", [], 'nb_run=100', 'my_output_file.xml');
    // Résultats dans un répertoire, par défaut sous TMPDIR/benchmarks
    bench_run("string", [], 'nb_run=100', TMPDIR);

Exemple de fichier de test SCI/modules/linear_algebra/tests/benchmarks/bench_chol.tst.

    // =============================================================================
    // Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
    // Copyright (C) 2007-2008 - INRIA
    //
    //  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 -->

résultat du test

    -->bench_run('linear_algebra','bench_chol')

              For Loop (as reference) ...........................      33.20 ms [ 1000000 x]

    001/001 - [linear_algebra] bench_chol ......................     1233.93 ms [      10 x]

Lancer un lot de tests dédiés à une même fonctionalité en utilisant un libellé partiel/générique :

    --> bench_run string ascii

             For Loop (as reference) ...........................      102.98 ms [ 1000000 x]

     001/005 - [string] bench_ascii_1 ...........................      447.40 ms [   10000 x]
     002/005 - [string] bench_ascii_2 ...........................    31727.98 ms [ 1000000 x]
     003/005 - [string] bench_ascii_3 ...........................     4173.69 ms [   10000 x]
     004/005 - [string] bench_ascii_4 ...........................     5145.06 ms [   10000 x]
     005/005 - [string] bench_ascii_UTF8 ........................       23.26 ms [      10 x]

## Voir aussi

- test_run
- coverage
- slint
- debug

## Historique

6.0

- `bench_run()` peut maintenant retourner les résultats des tests de performance via les nouveaux paramètres de sortie `modutests_names`, `elapsed_time` et `nb_iterations`
- L'export des résultats au format XML est désormais possible
- Les paramètres de configuration globale mode(),format(), ieee(), warning() et funcprot() sont protégés lors des tests.
- Les libellés partiels/génériques de tests sont désormais permis afin de lancer un lot de tests dédiés à la même fonction/fonctionnalité.