breaklinks=true, %permet le retour <20> la ligne dans les liens trop longs
urlcolor= blue, %couleur des hyperliens
linkcolor= blue, %couleur des liens internes
citecolor= green %couleur citation biblio
}
%creation d une longueur egale a \baselineskip pour l utiliser dans les tabular (car un bug incroyable fait que \baselineskip est egal a 0 dans les tabular!!!!)
\newlength{\savebaselineskip}
\setlength{\savebaselineskip}{\baselineskip}
\newcommand{\ligne}[1]{
%on change l'unit<69> de longueur "\unitlength" li<6C>e <20> l'environnement "picture"
%\baselineskip = distance entre la base d'une ligne et la base de la ligne suivante
%
% pour info, on a : 1cm = 3\baselineskip (sous r<>serve d'un changement de la valeur de \baselineskip)
%
\setlength{\unitlength}{\baselineskip}
%on declare un dessin de dimension #1 et de hauteur 0
\begin{picture}(#1,0.)
%on fait une ligne d'origine (0,0.25\baselineskip), dans la direction (1,0) et de longueur #1 (egale a la taille du dessin)
\put(0,0.25){\line(1,0){#1}}
\end{picture}
%Rq : on utilise 0.25\baselineskip pour l'origine afin d'avoir une ligne "centr<74>e" en hauteur, ce qui permet de faire des trucs du genre :
Ce manuel pr<70>sente la proc<6F>dure de v<>rification d'une s<>rie de tests d<>di<64><20> Herezh++. Cette v<>rification est effectu<74>e via principalement un script perl. La premi<6D>re version de ce script a <20>t<EFBFBD> mise en place par Laurent Mah<61>o au cours de sa th<74>se au d<>but des ann<6E>es 2000. Puis plusieurs <20>volutions mineures ont <20>t<EFBFBD> introduite. Enfin derni<6E>rement, suite <20> un <20>largissement des objectifs, le script a <20>t<EFBFBD> enti<74>rement refond<6E> par Julien Troufflard en 2015. On trouvera dans ce document une description de l'organisation de l'arborescence, du fonctionnement et enfin de la m<>thodologie n<>cessaire pour introduire un nouveau test.
Le script \verb|verifier_exeHZ| permet de lancer la batterie de tests. Il lance automatiquement tous les tests pr<70>sents dans le r<>pertoire courant et ses sous-r<>pertoires. Un test est un r<>pertoire dont le nom commence par \verb|Test_R| ou \verb|Test_L| (voir section \ref{section_organisation_tests}). Le script peut \^etre lanc<6E> dans n'importe quel r<>pertoire contenant le r<>pertoire \verb|Perl|. Il produit un rapport de tests pour les tests \verb|Test_R| (tests rapides) et un rapport pour les tests \verb|Test_L| (tests longs). Ces rapports sont contenus dans le r<>pertoire \verb|Rapport| (<28>ventuellement cr<63><72> si il n'existe pas au lancement) sous le nom \verb|rapport_test_R.txt| et \verb|rapport_test_L.txt|. Le script affiche automatiquement ces rapports si l'<27>diteur de texte \verb|nedit| est disponible.
Le script \verb|verifier_exeHZ| prend un argument : le nom de l'ex<65>cutable Herezh++. Typiquement, cet ex<65>cutable est pr<70>sent dans un r<>pertoire point<6E> par la variable environnement \verb|$PATH|. Mais on peut <20>galement donner un chemin absolu ou relatif.\\
Exemples :
\begin{itemize}
\item[$\bullet$] cas d'un ex<65>cutable accessible via la variable environnement \verb|$PATH| :
\begin{itemize}
\item[]\verb|verifier_exeHZ HZppfast_Vn-1|
\item[]\verb|verifier_exeHZ HZppfast64|
\end{itemize}
\item[$\bullet$] cas d'un ex<65>cutable sp<73>cifi<66> par un chemin absolu ou relatif :
\subsection{Classement des tests}\label{section_classement_tests}
On distingue actuellement deux sortes de tests selon le temps de calcul : les tests "Rapides" et les tests "Longs". A titre indicatif, un test "Rapide" est suppos<6F> durer moins de 30 secondes. Chaque test est contenu dans un r<>pertoire dont le nom commence par \verb|Test_R| (test rapide) ou par \verb|Test_L| (test long). Les r<>pertoires de tests sont rang<6E>s dans le r<>pertoire \verb|Batterie| selon l'arborescence montr<74>e sur la figure \ref{arbo_tests}. Le classement actuel est le suivant :
\begin{itemize}
\item[$\bullet$]\verb|FONCTION_UNIQUE| : r<>pertoire d<>di<64> au simple test d'une fonctionnalit<69> (une loi de comportement, un mode de calcul, un type d'<27>l<EFBFBD>ment, ...). En g<>n<EFBFBD>ral, ce sont des tests "Rapides".
\item[$\bullet$]\verb|CALCUL_COMPLET| : exemples complets issus par exemple de travaux de recherche ou applications industrielles (par exemple : une mise en forme de t\^ole, un essai de traction avec localisation, un d<>ploiement de structure souple, ...). En g<>n<EFBFBD>ral, ce sont des tests "Longs".
\item[$\bullet$]\verb|AUTRE| : tests difficiles <20> classer. Ce r<>pertoire peut aussi servir de lieu de d<>p\^ot temporaire avant transfert vers une rubrique d<>di<64>e.
\end{itemize}
\begin{figure}[!h]
\centering
\begin{tikzpicture}[%
grow via three points={one child at (0.5,-0.7) and
two children at (0.5,-0.7) and (0.5,-1.5)},
edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}]
Le script \verb|verifier_exeHZ| a pour fonction de rechercher tous les r<>pertoires de tests (r<>pertoires commen<65>ant par \verb|Test_R| ou \verb|Test_L|. Chaque r<>pertoire de test contient un unique fichier \verb|.info| et un certain nombre $N$ de fichiers \verb|.CVisu|[i] o<> [i] est un num<75>ro de 1 <20>$N$. Pour chaque fichier \verb|.CVisu|[i], un calcul est lanc<6E>. Le premier calcul est celui correspondant au fichier \verb|.CVisu1|. Les calculs suivants pour [i]$>$1 sont des RESTART (si possible) du calcul pr<70>c<EFBFBD>dent <20> partir du dernier incr<63>ment sauvegard<72> (selon option \verb|SAUVEGARDE| du fichier \verb|.info|).\\
Pour chaque calcul, un <20>ventuel fichier d'extension \verb|.commande|[i] contient des commandes interactives pour r<>pondre aux diff<66>rents menus interactifs propos<6F>s par Herezh++. Par d<>faut, un calcul Herezh est ex<65>cut<75> avec l'option \verb|-f| suivie du nom du fichier \verb|.info| (calcul classique). Si le fichier \verb|.info| ne contient pas le mot-cl<63>\verb|dimension|, l'option utilis<69>e est \verb|-n| suivie du fichier \verb|.info| (cr<63>ation interactive d'un fichier .info). Il est <20>galement possible de d<>finir compl<70>tement les arguments donn<6E>s <20> Herezh++ dans un fichier \verb|.argument|[i]. Pour plus d'informations sur les fichiers facultatifs, on peut se r<>f<EFBFBD>rer <20> la section \ref{section_fichiers_facultatifs}.\\
Une fois un test termin<69>, le r<>pertoire du test est restaur<75> dans son <20>tat d'origine (restauration de l'<27>tat initial du fichier \verb|.info| et suppression de tous les fichiers qui n'<27>taient pas pr<70>sents <20> l'origine).
Pour chaque calcul, une v<>rification est faite pour d<>terminer si le test est r<>ussi ou non. Le rapport de test contient les indicateurs \verb|OK| ou \verb|ECHEC|. Il y a actuellement 3 types de v<>rification possible :
\begin{itemize}
\item[$\bullet$] comparaison des donn<6E>es sorties au format maple :
\item[] il s'agit du mode de v<>rification par d<>faut. Le fichier \verb|.CVisu|[i] d<>finit les sorties au format maple. Le r<>pertoire de test contient alors un fichier \verb|.maple.ref|[i] qui d<>finit les valeurs de r<>f<EFBFBD>rence. Si l'<27>cart absolu et relatif entre les donn<6E>es de r<>f<EFBFBD>rence et les donn<6E>es du calcul sont inf<6E>rieures <20> une tol<6F>rance, alors le test est r<>ussi. Les tol<6F>rances par d<>faut sont en absolu 1e-6 et en relatif 1e-3. Il est possible de choisir librement les tol<6F>rances dans un fichier \verb|.precision|[i]. Pour une grandeur $X$ g<>n<EFBFBD>r<EFBFBD>e <20> l'issue du calcul [i] et sa valeur de r<>f<EFBFBD>rence $X_{ref}$ contenue dans le fichier \verb|.maple.ref|[i], le test est r<>ussi si les relations de comparaison suivantes sont respect<63>es :
\bf IMPORTANT : \rm si les fichiers \verb|.maple| et \verb|.maple.ref| contiennent plusieurs lignes de donn<6E>es, seule la derni<6E>re ligne est trait<69>e\\
\end{itemize}
\item[$\bullet$] comparaison libre d<>finie par un script :
\item[] la v<>rification peut \^etre librement d<>finie par un script qui a pour fonction de renvoyer \verb|OK| ou \verb|ECHEC|. Ce script est un fichier ex<65>cutable d'extension \verb|.verif|[i], signifiant que le calcul n<>[i] sera v<>rifi<66> par un script libre.\\
\item[$\bullet$] v<>rification simple de l'ex<65>cution :
\begin{itemize}
\item[] en l'absence de fichier \verb|.maple.ref| ou de script \verb|.verif|, la v<>rification est consid<69>r<EFBFBD>e \verb|OK| si le calcul s'est lanc<6E> normalement et termin<69> normalement (que le calcul ait converg<72> ou non).
D'autres fichiers facultatifs peuvent \^etre contenus dans un r<>pertoire de test. Il n'y a pas de restriction mis <20> part qu'un r<>pertoire de test ne doit pas contenir des fichiers trop lourds en terme d'espace disque. Typiquement, il peut \^etre utile d'ajouter les fichiers suivants :
\item[$\bullet$] des fichiers de mise en donn<6E>es du test pour d'autres codes de calcul (par exemple : fichier \verb|.inp| pour Abaqus)
\item[$\bullet$] des fichiers donnant des r<>sultats donn<6E>s par d'autres codes de calcul ou par des solutions analytiques (bien que le fichier \verb|README| puisse \^etre utilis<69> pour <20>crire ces donn<6E>es)
\caption{Trame du fichier README pr<70>sent dans chaque r<>pertoire de test. {\color{blue} Les rubriques en bleu sont \underline{obligatoires}.}{\color{brown} Les rubriques en marron sont importantes pour la tra<72>abilit<69> des tests mais non obligatoires.}}
\subsection{Recherche de tests}\label{section_recherche_de_tests}
Un document pdf de nom \verb|documentation_tests.pdf| est pr<70>sent <20> la racine du projet CVS. Il dresse la liste actuelle des tests et r<>sume en quelques phrases leur contenu. Un index en fin de document permet de faire une recherche par mot-cl<63>.\\
Ce document est r<>dig<69> automatiquement sur la base du contenus des fichiers README montr<74> sur la figure \ref{format_fichier_README}.
Cr<EFBFBD>er un nouveau test consiste <20> ajouter un nouveau r<>pertoire dans le r<>pertoire \verb|Batterie|. Le choix de son emplacement dans l'arborescence est libre en s'inspirant tout de m\^eme des descriptifs donn<6E>s en section \ref{section_classement_tests}. Le contenu du r<>pertoire est celui d<>fini en section \ref{section_contenu_repertoire_test}.
Les fichiers facultatifs d<>pendent du type de traitement Herezh++. Dans tous les cas, l'arborescence du r<>pertoire de test est de la forme montr<74>e sur la figure \ref{arbo_repertoire_test} et les r<>gles suivantes sont <20> respecter :
\begin{itemize}
\item[$\bullet$] Le nom du nouveau r<>pertoire est choisi en utilisant uniquement les lettres de a <20> z, les chiffres de 0 <20> 9, le signe moins "-" et le tiret bas "\_". Si le test est un test "Rapide" (moins de 30 secondes), le nom commence par \verb|Test_R|, sinon il commence par \verb|Test_L|.
\item[$\bullet$] Un seul fichier d'extension \verb|.info| doit \^etre pr<70>sent dans le r<>pertoire. Ce fichier doit \^etre pr<70>sent m\^eme s'il est vide.
\item[$\bullet$] Pour chaque calcul, il est n<>cessaire de cr<63>er un fichier \verb|.CVisu| (\verb|.CVisu1|, \verb|.CVisu2|, etc...) m\^eme si celui-ci est vide. Ces fichiers servent non seulement <20> Herezh++ mais <20>galement au script \verb|Perl/test.pl| pour rep<65>rer les calculs <20> lancer (un calcul par fichier \verb|.CVisu|).
\item[$\bullet$] tous les fichiers \verb|.CVisu|[i] et les fichiers facultatifs n<>cessaires <20> l'ex<65>cution d'un test (\verb|.verif|[i], \verb|.commande|[i], etc...) ont la m\^eme racine que le fichier \verb|.info| (par exemple, si on a le fichier \verb|nom_fichier.info|, l'<27>ventuel fichier \verb|.verif1| doit avoir pour nom \verb|nom_fichier.verif1|)
\item[$\bullet$] le fichier \verb|README| contient obligatoirement les rubriques \it But du test \rm et \it Description du calcul \rm montr<74>es sur la figure \ref{format_fichier_README}. Ces deux rubriques serviront <20> g<>n<EFBFBD>rer automatiquement une documentation pdf (catalogue de tests). Dans le m\^eme but, les rubriques \it Auteur \rm et \it Mots-cles\rm, qui ne sont pas obligatoires, donnent des informations pr<70>cieuses (merci de les renseigner).
\item[] Remarque importante : ne pas <20>crire des lignes de tirets (\verb|---| et plus) dans le corps d'une rubrique.\\
La sous-section \ref{section_commandes_CVS} est un rappel des commandes CVS de base. Les sous-sections \ref{section_fichiers_obligatoires} et \ref{section_fichiers_facultatifs} donnent des informations sur les fichiers obligatoires et les fichiers facultatifs en lien avec l'ex<65>cution du test. Notamment, certains fichiers ont un format bien pr<70>cis pour \^etre exploitables. Ensuite, la sous-section \ref{section_exemples_tests} a pour but de balayer les cas les plus courant de tests et de donner des exemples.
\item[]\footnotesize (*) \underline{Toujours actualiser sa version locale avant de modifier le projet}. Cette commande actualise le r<>pertoire courant ainsi que tous ses sous-r<>pertoires\normalsize
\item[]\footnotesize (**) a priori, c'est la m\^eme d<>marche pour effacer un r<>pertoire, bien qu'il soit souvent constat<61> que le r<>pertoire effac<61> persistait\normalsize\\
La trame du fichier est montr<74>e sur la figure \ref{format_fichier_README}. La syntaxe de l'intitul<75> des deux rubriques obligatoires (en bleu) doit \^etre strictement respect<63>e. Il est fortement encourag<61> de renseigner les rubriques \it Auteur \rm et \it Mots-cles\rm. Les autres rubriques sont indiqu<71>es <20> titre de proposition et pour des questions d'harmonie sur la forme d'un test <20> l'autre. Comme montr<74> sur la figure \ref{format_fichier_README}, chaque titre de rubrique est pr<70>c<EFBFBD>d<EFBFBD> et suivi d'une ligne d'au moins trois tirets (\verb|---| et plus). Les lignes de tirets doivent \^etre r<>serv<72>es aux titres des rubriques (Ce motif sert <20> rep<65>rer la fin d'une rubrique. L'insertion d'une ligne de tirets dans le corps d'une rubrique mettra en d<>faut le script de g<>n<EFBFBD>ration automatique de la documentation!!).\\
\item[] Ce fichier est l'unique fichier d'extension \verb|.info| pr<70>sent dans le r<>pertoire. Il est obligatoire mais peut \^etre vide (par exemple dans le cas d'un cr<63>ation de fichier \verb|.info| avec l'option Herezh \verb|-n|).\\
Il n'y a pas de restriction majeure sur le contenu de ce fichier mais il est important de noter que dans le cas d'un test avec plusieurs fichiers \verb|.CVisu|, chaque calcul ult<6C>rieur au n<>1 tentera de faire un \verb|RESTART| du calcul pr<70>c<EFBFBD>dent. C'est pourquoi il faut faire attention au param<61>tre \verb|controle|$\rightarrow$\verb|SAUVEGARDE|. Le param<61>tre suffisant est :\\
\hspace*{2cm}\begin{minipage}{\textwidth}
\begin{verbatim}
controle
SAUVEGARDE DERNIER_CALCUL
\end{verbatim}
\end{minipage}
Si le calcul utilise un menu interactif, un fichier \verb|.commande| sera n<>cessaire.\\
\item[] La pr<70>sence de ces fichiers est obligatoire mais ils peuvent \^etre vides <20> partir du moment o<> le but du test n'est pas de comparer des r<>sultats Herezh maple ou Gmsh
\item[] Ce fichier permet de modifier les pr<70>cisions par d<>faut pour la comparaison des donn<6E>es au format maple pour un certain nombre de colonnes du fichier \verb|.maple|. Par d<>faut, les pr<70>cisions sont 1e-6 en absolu, 1e-3 en relatif. Le format du fichier est le suivant :\\
Il est important de noter que les crochets autour d'un num<75>ro de colonne sont obligatoires. Par exemple, si le fichier \verb|.maple| contient une ligne de la forme :\\
\item[] Le but de ce fichier est de fournir automatiquement les r<>ponses <20> un menu interactif. Sa pr<70>sence <20>quivaut <20> lancer un calcul Herezh++ de la mani<6E>re suivante :\\
Chaque ligne contient une r<>ponse suivie par un retour <20> la ligne. En particulier, il ne faut pas oublier le retour <20> la ligne <20> la fin de la derni<6E>re ligne.\\
\item[] Ce fichier est un ex<65>cutable dont la fonction est de fournir le r<>sultat de la v<>rification. Pour cela, il effectue les traitements n<>cessaires pour d<>terminer si le test est \verb|OK| ou \verb|ECHEC|. Il indique ce r<>sultat en affichant la ligne suivante :
Cet ex<65>cutable peut \^etre programm<6D> dans n'importe quel langage, mais pour <20>viter les probl<62>mes de compilateur, il est pr<70>f<EFBFBD>rable d'<27>viter les langages n<>cessitant une compilation (par exemple : C, C++, Fortran, etc...). Il est pr<70>f<EFBFBD>rables d'utiliser les langages interpr<70>t<EFBFBD>s (par exemple : sh, zsh, Perl, Python, etc...).\\
\item[] Ce fichier permet de d<>finir librement les arguments donn<6E>s <20> l'ex<65>cutable Herezh++. Il peut contenir autant de lignes que n<>cessaire. Il est important de noter que l'affichage produit par Herezh++ est toujours redirig<69> dans un fichier \verb|.log| avec la commande \verb|tee|. Il est donc inutile voire bloquant de rajouter une redirection suppl<70>mentaire parmi les arguments. Au final, pour un fichier contenant N lignes, la commande Herezh++ lanc<6E>e sera :\\
\item[] Ce fichier est utile pour la comparaison de donn<6E>es au format maple. Le nombre de colonnes de ce fichier doit \^etre en accord avec le fichier \verb|.maple| produit par la lecture du \verb|.CVisu| associ<63>.
Il s'agit du cas le plus courant consistant <20> r<>aliser des calculs g<>n<EFBFBD>rant des donn<6E>es au format maple <20> comparer avec les donn<6E>es contenues dans un fichier \verb|.maple.ref|. Les fichiers \verb|.CVisu|[i] d<>finissent des sorties au format maple. Le calcul n<>[i] utilise le fichier \verb|.CVisu|[i] pour g<>n<EFBFBD>rer un fichier \verb|.maple| qui sera compar<61> au fichier \verb|.maple.ref|[i] qui doit contenir exactement le m\^eme nombre de colonnes que le fichier \verb|.maple|.\\
Le fichier \verb|.info| doit g<>n<EFBFBD>rer automatiquement les sorties maple en choisissant parmi les 2 possibilit<69>s suivantes :
A noter que quelque soit la fr<66>quence de sortie des r<>sultats, seule la derni<6E>re ligne de donn<6E>es du fichier \verb|.maple| est v<>rifi<66>e.\\
Le test \verb|Batterie/FONCTION_UNIQUE/TYPE_DE_CALCUL/Test_R_non_dynamique| est un exemple de calcul classique utilisant les pr<70>cisions par d<>faut pour la comparaison des donn<6E>es.
Le test \verb|Batterie/FONCTION_UNIQUE/UTILITAIRES/Test_R_fusion-maillage| est un exemple de calcul utilisant un fichier de commandes interactives (r<>ponses au menu interactif de l'utilitaire "\verb|avec plus fusion_maillages|").
Le test \verb|Batterie/FONCTION_UNIQUE/UTILITAIRES/Test_R_suppression-noeuds-non| \verb|-references| est un exemple de calcul utilisant un script de v<>rification (comparaison entre deux fichiers \verb|.her|).
Le script \verb|Perl/test.pl| lance un calcul Herezh++ avec l'option \verb|-n| si le fichier \verb|.info| ne contient pas le mot-cl<63>\verb|dimension|. Pour cela, on cr<63>e simplement un fichier \verb|.info| vide. Un fichier \verb|.commande| sera forc<72>ment n<>cessaire pour r<>pondre au menu interactif de cr<63>ation.
Il ne s'agit pas d'un calcul classique. Donc, sauf cas particulier, la v<>rification sera faite via un script \verb|.verif| afin de comparer le fichier cr<63><72><20> un fichier de r<>f<EFBFBD>rence. Attention au fait que le fichier de r<>f<EFBFBD>rence ne doit pas avoir l'extension \verb|.info| car il ne peut y avoir qu'un seul fichier \verb|.info| dans le r<>pertoire. On peut par exemple utiliser l'extension \verb|.info.ref1|.\\
\item[-]cr<EFBFBD>ation d'un nouveau script (\verb|Perl/genere_catalogue_tests.pl|). Il g<>n<EFBFBD>re automatiquement une documentation sur les tests (r<>sum<75> et index pour recherche par mots-cl<63>s). Ce document est plac<61><20> la racine du projet sous le nom \verb|documentation_tests.pdf|. Le mode de fonctionnement (lecture des fichiers README de chaque test) impose une nouvelle contrainte sur la forme des fichiers README (interdiction d'utiliser des lignes de 3 tirets ou plus dans le corps d'une rubrique README car ce motif signifie la fin d'une rubrique). Cette contrainte est le choix actuel mais peut \^etre modifi<66><20> tout moment en d<>finissant une balise de fin de rubrique <20> utiliser dans les fichiers README (par exemple : \verb|fin_rubrique|) et en indiquant sa syntaxe dans la variable \verb|$MOTIF_FIN_RUBRIQUE| du script \verb|Perl/genere_catalogue_tests.pl|.\\
\item[-]Apparition d'une nouvelle rubrique README : \it Auteur \rm (renseigne le ou les auteurs du test avec pr<70>nom, nom, adresse mail). rubrique qui appara\^it dans la documentation des tests.
