2. Simuler avec OpenFLUID-engine

2.1 Préparer le jeu de données

Un jeu de données de simulation doit être composé des fichiers normalisés suivants:

• model.xml: définition du modèle
• run.xml: configuration de la simulation
• SUdefs.dat, RSdefs.dat, GUdefs.dat: géométrie-topologie des objets spatiaux
• *.ddata.xml : propriétés et conditions initiales distribuées
• *.events.xml : évènements discrets distribués
• output.xml: définition des sorties

Par défaut, le jeu de données en entrée doit se trouver dans un répertoire .openfluid/engine/OPENFLUID.IN se situant dans le répertoire-maison (home directory) de l'utilisateur. De la même manière, les résultats de simulation se trouveront, en fin de run, dans un répertoire .openfluid/engine/OPENFLUID.OUT se situant dans le répertoire-maison de l'utilisateur. Il est possible de modifier ce comportement par défaut via les options de la ligne de commande (voir en annexe).

2.1.1 Définition du modèle de flux (model.xml)

Le fichier de définition du modèle de flux model.xml décrit la schéma du simulation qui sera mis en oeuvre. On dit qu'il défit un modèle OpenFLUID-engine. Il décrit:

• les paramètres globaux de calcul et de fonctionnement
• l'enchaînement des fonctions de simulation constituant le modèle
• les paramètres globaux propres à chacune des fonctions de simulation

Ce fichier est au format XML. Il contient une section unique <model>. Cette section décrit l'ordonancement des fonctions de simulation qui vont être utilisée. Chaque fonction sera décrite par une balise <function> contenant un attribut obligatoire : fileID. Cet attribut défit l'identifiant du fichier de la fonction (nom du fichier binaire sans l'extension). S'il y a lieu, chaque fonction de simulation peut définir ses paramètres globaux particuliers au travers d'une ou plusieurs sous-balises <param> contenant deux attributs: name contenant le nom du paramètre, value contenant sa valeur.

l'ordre de description des fonctions utilisées est important: elles seront chaînées ainsi lors de l'exécution de la simulation.

<?xml version="1.0" standalone="yes"?> <openfluid> <model> <function fileID="mseytoux" > <param name="resstep" value="0.000005" /> </function> <function fileID="hayamisu"> <param name="maxsteps" value="100" /> <param name="meancel" value="0.045" /> <param name="meansigma" value="500" /> </function> <function fileID="hayamirs"> <param name="maxsteps" value="100" /> <param name="meancel" value="0.8" /> <param name="meansigma" value="500" /> </function> </model> </openfluid>

2.1.2 Configuration de la simulation(run.xml)

La configuration de la simulation consiste principalement à définir la période de simulation (date de début, date de fin) ainsi que le pas de temps d'échange ($\delta t$) entre les fonctions de simulation. Les dates de début et de fin précisant la période sont données à la seconde près sous la forme "AAAA-MM-JJ hh:mm:ss". Si la date de fin demandée ne respecte pas la formule $fin = début + k*\delta t$ (avec k entier représentant le nombre de pas de temps), la date de fin est automatiquement recalculée pour englober la date de fin demandée. Il est également possible dans ce fichier de forcer la valeur de l'identifiant de simulation généré automatiquement.

Ce fichier est au format XML. Il contient une section unique <run>. Dans cette section run, on trouve 2 balises obligatoires <deltat> et <period>, et une balise facultative <simid>. La balise <deltat> définit le pas de temps d'échange. La balise <period> définit la période de simulation au travers de ses attributs obligatoires begin et end. La balise <simid> permet de forcer la valeur de l'identifiant de simulation.

<?xml version="1.0" standalone="yes"?> <openfluid> <run> <deltat>60</deltat> <period begin="1997-06-05 04:00:00" end="1997-06-05 16:23:00" /> </run> </openfluid>

2.1.3 Unités (SUdefs.dat, RSdefs.dat, GUdefs.dat)

Les fichiers de description des unités définissent l'ensemble des unités représentant le domaine spatial de simulation. Ils décrivent leur géométrie, leur topologie (connectivité), ainsi que l'ordre dans lequel elles devront être traitées par le modèle de flux. Ces fichiers sont au format texte-colonnes. Leur format est fixé et chaque colonne a une signification précise.
Ces fichiers sont au nombre de 3 et chacun définit un type d'objet. Si un de ces fichiers est absent le modèle considèrera qu'il n'a pas à traiter les objets de ce type là.
Le fichier SUdefs.dat décrit la surface sous la forme d'un ensemble d'unités de surface (SU). Il est composé de 8 colonnes exactement.

Fichier de description des unités de surface SUdefs.dat
Type: texte colonnes
Nom	Type	Description
ID	entier	Identifiant unique de l'objet
Area	réel	Aire (m2)
Slope	réel	Pente (m/m)
FlowCode	caract.	Type de l'objet avec lequel se font les échanges de surface : R pour un bief, S pour une autre SU
FlowID	entier	ID de l'objet avec lequel se font les échanges de surface
FlowDistance	réel	Distance entre centroïdes des objets pour les échanges de surface(m)
ExchangeGU	entier	ID de la GU avec lequel se font les échanges surface-souterrain
ProcessOrd	entier	ordre de traitement de l'objet

% définition des unités de surfaces (SU) %ID AREA SLOPE FCODE FID FDIST EXCHGU PCSSORD 1 4813.344 0.06265 R 330 14.366 2 1 2 293.982 0.27129 R 1 18.468 18 2 3 1038.097 0.16391 S 2 50.15 18 1 4 498.407 0.14065 R 113 4.906 10 3 5 1610.964 0.10073 S 10 23.031 24 1 6 1282.989 0.05443 S 4 30.497 10 2 7 2212.718 0.35908 R 112 15 18 1 8 3315.03 0.02693 S 6 35 10 2 9 1806.479 0.11358 S 169 15.231 18 3 10 2153.719 0.21005 S 9 13.901 18 2 11 4471.305 0.00487 R 350 10 18 4 12 201.064 0.24028 R 7 13.484 18 1 13 2043.269 0.19111 S 11 28.779 18 3 14 1672.532 0.10392 S 13 21.074 18 2 15 1625.557 0.0001 S 14 10 18 1 16 3191.879 0.05893 R 138 33.599 18 1 17 2672.699 0.17241 R 139 15.834 24 1

Le fichier RSdefs.dat décrit le réseau hydrographique au travers d'un ensemble de tronçons de biefs formant une arborescence. Il est composé de 10 colonnes exactement.

Fichier de description des segments de bief RSdefs.dat
Type: texte colonnes
Nom	Type	Description
ID	entier	Identifiant unique de l'objet
UpNode	entier	Identifiant du noeud haut
DownNode	entier	Identifiant du noeud bas
LowRS	entier	Identifiant du RS aval
Length	réel	Longueur (m)
Width	réel	Largeur (m)
Height	réel	Hauteur (m)
Slope	réel	Pente (m/m)
ExchangeGU	entier	ID de la GU avec lequel se font les échanges bief-souterrain
ProcessOrd	entier	ordre de traitement de l'objet

Le fichier GUdefs.dat décrit le souterrain sous la forme d'un ensemble d'unités souterraines ou aquifères (GU). Il est composé de 4 colonnes exactement.

Fichier de description des unités souterraines GUdefs.dat
Type: texte colonnes
Nom	Type	Description
ID	entier	Identifiant unique de l'objet
SubstLevel	réel	Altitude absolue du substratum (m)
ExchangeGU	entier	ID de la GU avec lequel se font les échanges souterrain-souterrain
ProcessOrd	entier	ordre de traitement de l'objet

Lorsque le lien topologique requis n'existe pas, l'identifiant de l'objet lié doit être -1. Ceci s'applique notamment au champ FlowID du fichier SUdefs.dat, aux champs LowRS et ExchangeGU du fichier RSdefs.dat, ainsi qu'au champ ExchangeGU du fichier GUdefs.dat.

2.1.4 Propriétés et conditions initiales distribuées (*.ddata.xml)

Les fichiers des propriétés distribuées et des conditions initiales des unités homogènes définissent les propriétés et conditions initiales propres à chacune des unités, et doivent avoir pour extension .ddata.xml. Il peut y avoir autant de fichiers .ddata.xml que souhaité. Les propriétés ou conditions initiales définies pour des unités qui n'existent pas sont ignorées.

Les fichiers .ddata.xml sont au format XML-mixte décrit en annexe. Ils doivent comporter une section distridata, avec un attribut unitclass précisant la classe d'unités à laquelle s'appliquent les données, ainsi qu'un attribut datacat précisant la catégorie de données (ini pour des conditions initiales, param pour des propriétés). Dans la section distridata, doit se trouver une section columns avec un attribut order qui permet de définir l'ordre dans lequel se trouvent les colonnes de données, séparées par des ";". La section data contient les données en colonnes, la première colonne étant obligatoirement réservée à l'identifiant de l'unité.

<?xml version="1.0" standalone="yes"?> <openfluid> <distridata unitclass="SU" datacat="param"> <columns order="ks;hc;betaMS;thetares;thetasat;nmanning" /> <data> 1 0.000001 0.1 1.3 0.02 0.36 0.05 2 0.000001 0.1 1.3 0.02 0.36 0.05 3 0.000001 0.1 1.3 0.02 0.36 0.05 4 0.000001 0.1 1.3 0.02 0.36 0.05 5 0.000001 0.1 1.3 0.02 0.36 0.05 6 0.000001 0.1 1.3 0.02 0.36 0.05 7 0.000001 0.1 1.3 0.02 0.36 0.05 8 0.000001 0.1 1.3 0.02 0.36 0.05 9 0.000001 0.1 1.3 0.02 0.36 0.05 10 0.000001 0.1 1.3 0.02 0.36 0.05 11 0.000001 0.1 1.3 0.02 0.36 0.05 12 0.000001 0.1 1.3 0.02 0.36 0.05 13 0.000001 0.1 1.3 0.02 0.36 0.05 14 0.000001 0.1 1.3 0.02 0.36 0.05 15 0.000001 0.1 1.3 0.02 0.36 0.05 </data> </distridata> </openfluid>

2.1.5 Evènements discrets distribués (*.events.xml)

Les fichiers des évènements discrets distribués contiennent les calendrier d'évènements qui surviennent à moment donné sur une unité donné, ainsi que leur description. Ils doivent avoir pour extension .events.xml. Il peut y avoir autant de fichiers .events.xml que souhaité.

<?xml version="1.0" standalone="yes"?> <openfluid> <calendar> <event unitclass="SU" unitid="127" date="2008-02-26 09:51"> <info key="depth" value="0.15" /> <info key="followslope" value="1" /> <description>this event is a tillage... blablabla..</description> </event> <event unitclass="SU" unitid="7" date="2008-02-22 09:00"> <info key="product" value="roundup" /> <info key="molecule" value="glyphosate" /> <info key="qty" value="0.92" /> </event> <event unitclass="RS" unitid="372" date="2008-05-12 00:00"> <info key="molecule" value="diuron" /> <info key="qty" value="0.12" /> </event> </calendar> </openfluid>

2.1.6 Gestion des sorties (output.xml)

La gestion des sorties se fait au travers du fichier output.xml. Ce fichier de définition des sorties est au format XML. Il permet de définir l'ensemble des résultats qui seront extraits en fin de simulation sous la forme de fichiers au format texte-colonnes contenant pour chaque pas de temps de simulation un ensemble [date;variable1;variable2; ;variablen]. La date est considérée dans son ensemble comme une seule et même colonne. Ces fichiers contenant les résultats de simulation peuvent être générés selon 2 modes: le mode "auto" et le mode "custom". A l'heure de la rédaction de ces lignes, seul le mode "auto" est fonctionnel.

Le fichier de définition des sorties contient une section définie par la balise <autooutfiles>. Cette balise peut contenir les attributs siuvants

• colsep qui définit le séparateur entre les colonnes. Par défaut si l'attribut n'est pas présent, c'est le caractère tabulation qui est le caractère séparateur.
• dtformat qui définit le format de la date. Le format peut être défini en utilisant la nomenclature ANSI strftime (cf annexes), ou bien en utilisant les formats prédéfinis 6cols ou iso. Par défaut si l'attribut n'est pas présent, c'est le format iso qui sera utilisé.
• commentchar qui définit le caractère de mise en commentaire. Par défaut si l'attribut n'est pas présent, c'est le caractère % (pourcent) qui est le caractère de mise commentaire.

Dans la section <autooutfiles>, il peut être défini autant de catégories de sorties que souhaité à l'aide des balises <SUout> pour extraire les données simulées sur les les unités de surface, <RSout> pour les données simulées sur les tronçons de biefs, <GUout> pour les données simulées sur les unités souterraines. Chacune de ces balises va donner lieu à la génération d'une série de fichiers contenant les résultats de simulation et qui seront nommées selon la nomenclature ObjetID_Suffixe.dat. Ces balises peuvent comporter 3 attributs:

• filesuffix qui viendra compléter le nom de fichier lors de la génération
• selection qui définit la liste des identifiants des objets dont on veut les données simulées. Chaque identifiant d'objet doit être séparé par un ";". Si on souhaite tous les objets, on met une "*". Par défaut si l'attribut n'est pas présent, les données sont générées pour tous les objets.
• vars qui définit la liste des variables que l'on souhaite extraire. Chaque nom de variable doit être séparé par un ";". Si on souhaite toutes les variable, on met une "*". Les variables de type vecteur doivent être suffixées avec les caractères []. Par défaut si l'attribut n'est pas présent, les données sont générées pour toutes les variables.

<?xml version="1.0" standalone="yes"?> <openfluid> <output> <autooutfiles colsep=" " dtformat="%d/%m/%Y;%H:%M:%S" commentchar="%"> <SUout filesuffix="full" selection="*" vars="runoff;infiltration;qoutput" /> <RSout filesuffix="qoutput" selection="*" vars="qoutput" /> <GUout filesuffix="fullfull" selection="*" vars="*" /> <SUout filesuffix="prod" selection="1;18;152" vars="runoff;infiltration" /> </autooutfiles> </output> </openfluid>

2.2 Lancer la simulation

Pour lancer la simulation, il faut lancer la commande openfluid-engine dans un shell (sous Unix/Linux) ou exécuter le programme openfluid-engine.exe (sous Windows).

2.3 Exploiter les résultats

Les résultats de la simulation se trouveront, en fin de run, dans un répertoire .openfluid/engine/OPENFLUID.OUT se situant dans le répertoire-maison de l'utilisateur. Il est possible de modifier ce comportement par défaut via les options de la ligne de commande (voir en annexe).