src/Tools/Verima/Doc/usage_outil.rst

   1 Utilisation de l'outil
   2 ======================
   3 Introduction
   4 -------------
   5 Avant d'utiliser les différents scripts décrits ci-dessous, il faut préalablement taper dans un terminal la commande ./runSession dans le répertoire Salome où se situe le runSession. On peut trouver les différents scripts au niveau du répertoire : ./Salome-n°version/modules/SMESH_n°version/share/salome/plugins/smesh/Verima
   6
   7 Création de la base
   8 --------------------
   9
  10 La base de données ne doit, à priori, n'être créée qu'une unique fois. Cependant, relancer le script de création ne changera pas les informations contenues dans la base et n'a pas d'incidence sur la base ni sur son contenu.
  11
  12   * createDatabase.py
  13         - Crée la structure de la base et le fichier myMeshDB.db
  14         - Si le fichier myMeshDB.db (c'est à dire si la base) existe déjà, le script ne modifie pas la structure des tables et n'affecte pas les enregistrements qu'elles contiennent déjà.
  15         - Le script a un unique paramètre optionnel : le nom de la database.
  16
  17      .. code-block:: python
  18
  19           python createDatabase.py -d maBaseAMoi.db
  20
  21 Initialisation d'un jeu de tests par défaut
  22 -------------------------------------------
  23 Si on le souhaite, on peut initialiser un jeu de tests par défaut. Ce jeu de tests s'applique aux versions, aux mailleurs testés, aux scripts de maillage et enfin aux groupes de référence associés à ces maillages.
  24 Les quatres fichiers python se situent dans le répertoire Base.
  25
  26   * Pour les versions, il s'agit du fichier tableVersions. Dans la méthode "remplit", on renseigne :
  27         - Le nom de la version
  28         - Un commentaire
  29
  30   * Pour les mailleurs, il s'agit du fichier tableMailleurs. Dans la méthode remplit, on renseigne :
  31         - Le nom du mailleur
  32
  33   * Pour les scripts, il s'agit du fichier tableMaillages. Dans la méthode remplit, on renseigne :
  34         - Le nom du cas test
  35         - Le nom du script python
  36         - Le nom du fichier med
  37         - Le numéro de l'identifiant correspondant au mailleur testé
  38         - La dimension maximale du maillage
  39         - Les quatres seuils correspondant aux quatres critères à savoir le temps CPU, l'aspect ratio, la longueur et enfin le nombre d'entités
  40         - Un commentaire
  41
  42   * Pour les groupes de référence, il s'agit du fichier tableGroupesRef. Dans la méthode remplit, on renseigne :
  43         - Le nom du groupe
  44         - Le numéro d'identifiant correspondant au maillage
  45
  46 Remarque : actuellement, le jeu par défaut porte :
  47   * sur les versions
  48         - n°id=1,'Salome7.2.0'
  49         - n°id=2,'Salome7.3.0'
  50         - n°id=3,'Salome7.4.0'
  51   * sur les mailleurs
  52         - n°id=1,'BLSURF'
  53         - n°id=2,'NETGEN1D2D'
  54         - n°id=3,'GHS3D+BLSURF'
  55         - n°id=4,'GHS3D+NETGEN1D2D'
  56         - n°id=5,'NETGEN1D2D3D'
  57
  58 Ajouter un enregistrement à une table
  59 -------------------------------------
  60
  61 Lors d'une nouvelle version de Salome, de l'arrivée d'un nouveau cas test ou d'un nouveau mailleur, il sera nécessaire d'enrichir la base de données. Aucun contrôle sur la cohérence des valeurs n'est effectué.
  62
  63   * l'autoincrement
  64
  65    Les identifiants ("id") des tables Maillages, Mailleurs et Versions sont crées de façon automatique lors de l'insertion d'un enregistrement dans la table. Il n'est ni possible ni nécessaire de les préciser lors de la création d'un enregistrement.
  66    Ainsi, pour ajouter un mailleur, il suffit de spécifier son nom.
  67
  68
  69   * ajoutEnreg.py
  70
  71         - Le script a deux paramètres : le nom de la database (optionnel) et le nom de la table qu'il faut enrichir.
  72           les valeurs des colonnes doivent être fournies dans l'ordre.
  73
  74          .. code-block:: python
  75
  76             python ajoutEnreg -d maBaseAMoi.db -t TableMailleurs  "monMailleur"
  77
  78
  79         - Les contrôles effectués sont minimaux : nombre de valeurs de l'enregistrement et identifiant. En revanche, la cohérence entre tables n'est pas vérifiée. Ainsi, par exemple, pour entrer un nouveau cas test, il faut ajouter un enregistrement à la table des maillages. Si l'identifiant du mailleur n'existe pas, aucune erreur ne sera détectée.
  80
  81          .. code-block:: python
  82
  83           python ajoutEnreg -d maBaseAMoi.db -t TableMailleurs  "monMailleur"
  84           python ajoutEnreg -d maBaseAMoi.db -t TableMaillages  "monMaillage" "mesScripts/lanceMonMaillage" "/tmp/monFichierMed" 4 3 5 5 5 5 "essai pour mon Mailleur"
  85
  86
  87 Changement de la version de référence
  88 -------------------------------------
  89
  90 A priori, cette fonction ne devrait pas être utilisée. mais ... Elle permet de changer la version de référence.
  91
  92   * changeVersion.py
  93
  94          .. code-block:: python
  95
  96             python changeVersion.py Salome7.3 ou
  97             python changeVersion.py 3
  98
  99 Consultation des tables
 100 -----------------------
 101
 102   * le script Gui/visualiseDatabase.py (qui peut également être lancé de l'outil générique lance.py) permet de visualiser les tables contenues dans la base. (Attention au path de la database)
 103
 104          .. code-block:: python
 105
 106             python visualiseDatabase.py -d ../myMesh.db
 107
 108 .. image:: images/visualisation.png
 109
 110
 111 Lancer un job de maillage particulier ou l'ensemble des tests
 112 ----------------------------------------------------------------
 113
 114    * le script passejob.py permet de passer l'ensemble des tests ou un cas particulier. il admet les options suivantes :
 115
 116        - '-a' pour passer l ensemble des Tests (non activée par defaut)
 117        - '-s' pour preciser le path du runAppli (par exemple ~/Appli). Permet au job de trouver le runAppli
 118        - '-d' pour preciser le fichier dataBase
 119        - '-v' pour spécifier la version de Salome
 120        - si l'option -a n'est pas activée, il faut préciser l'identifiant du job à passer
 121
 122
 123          .. code-block:: python
 124
 125             python passeJobs.py -d ../myMesh.db 1
 126
 127 Modifier les scripts pour les intégrer dans le mécanisme de test
 128 -------------------------------------------------------------------
 129
 130     * ajout des lignes suivantes à la fin du script :
 131
 132          .. code-block:: python
 133
 134             from Stats.getStats import getStatsMaillage, getStatsGroupes
 135             from Stats.getCritere import getStatsCritere
 136             #
 137             fichierMedResult = 'fichierMed.med'
 138             getStatsMaillage(monMaillage,fichierMedResult)
 139             getStatsGroupes(monMaillage,fichierMedResult)
 140             getStatsCritere(dimMaillage,monMaillage,fichierMedResult)
 141
 142 Lancement du script de comparaison
 143 -----------------------------------
 144   * compareVersions.py
 145        - '-s' pour preciser le path du runAppli (par exemple ~/Appli). permet au job de trouver le runAppli
 146        - '-r' pour spécifier les numéros de versions de référence pour chacun des scripts
 147        - '-d' pour preciser le fichier dataBase
 148        - '-f' pour spécifier le nom du rapport html produit (/tmp/toto.html par défaut -) )
 149
 150          .. code-block:: python
 151
 152            python compareVersions.py -s ./runAppli -r 1,2,2 -d ./myMesh.db -f ./rapport.html
 153
 154
 155    Ici, pour les scripts n°1, 2 et 3, les versions de référence sont, respectivement "Salome7.2.0", "Salome7.3.0" et "Salome 7.3.0".
 156
 157
 158 export/import de la base
 159 -------------------------
 160   * exportDatabaseToCSV.py
 161
 162     - admet l option  -p (pour partiel) qui ne sauvegarde pas les tables a priori communes a tous :
 163             * la table des mailleurs
 164             * la table des maillages
 165             * la table des versions
 166             * la table des machines
 167             * la table des groupes references
 168
 169    - les fichiers sont ranges dans la directory ExportDB+date. la premiere ligne de chaque fichier contient le nom des colonnes, puis les valeurs par ligne
 170
 171    - pour faire une vraie sauvegarde de la base (structure et donnees) il faut lancer sqlite3 et executer .dump
 172
 173
 174   * importDatabaseFromCSV.py
 175
 176     - parametre d 'entree obligatoire : la directory qui contient les fichiers a importer
 177     - admet l option  -p (pour partiel) qui n importe pas les tables a priori communes a tous
 178     - admet l option  -f (pour force) qui pour les enregistrements qui existent déjà dans la base remplace
 179       par les valeurs donnees dans le fichier
 180
 181 Critères de vérification
 182 ========================
 183 Principe
 184 --------
 185 Le principe est simple.
 186 Pour chaque maillage, on définit des valeurs de référence associées au maillage. A chaque nouvelle version de Salome, on compare les résultats obtenus avec ces valeurs de référence pour le script étudié. On émet un warning à chaque fois que les écarts relatifs dépassent un certain seuil.
 187
 188 Critères
 189 --------
 190 Les critères de vérification portent sur :
 191
 192   * Le temps CPU
 193
 194   * Le nombre d'entités du maillage classé par type
 195         - Le nombre de noeuds
 196         - Le nombre de segments (maille 1D)
 197         - Le nombre de triangles (maille 2D)
 198         - Le nombre de quadrangles (maille 2D)
 199         - Le nombre de tétraèdres (maille 2D)
 200
 201   * Le rapport de tailles de chaque élément du maillage (fonction GetAspectRatio)
 202         - Pour un maillage 3D, on calcul le ratio des mailles 3D
 203         - Pour un maillage 2D, on calcul le ratio des mailles 2D
 204
 205   * La longueur de chaque élément du maillage (fonction GetMaxElementLength)
 206         - Pour un maillage 3D, on calcul la longueur des mailles 3D
 207         - Pour un maillage 2D, on calcul la longueur des mailles 2D
 208
 209 Ces critères sont calculés sur tout le maillage et éventuellement sur des groupes de mailles de référence associés au maillage.
 210
 211 Pour chaque maillage, les valeurs de référence sont calculées sur la base d'une version spécifique de Salome (qui peut être différente d'un maillage à l'autre).
 212
 213 Pour le rapport de tailles et la longueur des mailles, on calcule systématiquement le maximun, le minimum, la moyenne, le 1er et 3ème quartile et enfin la médiane.
 214
 215 Pour ces quatres critères, on définit un seuil à ne pas dépasser (qui peut être différent d'un critère à l'autre). Actuellement, au sein d'un même critère, les seuils sont identiques.
 216