Scenarios Manager

Abréviations

• LMC : left mouse click

• RMC : right mouse click

• DC : double left click

• Ctrl+DC : Control + double left click

• MW : Mouse Wheel

• UI : User Interface

Emplacement du code source

Le code source du gestionnaire de scénarios est dans le module Python ‘config_manager.py’ du dossier ‘scenario’ du paquet ‘wolfhece’.

Deux classes principales existent :

• ‘Config_Manager_2D_GPU’ : Stockage des données

• ‘UI_Manager_2D_GPU’ : Interface Utilisateur (UI) associé au stockage

Philosophie générale

La structuration des scénarios se veut ouverte et accessible sans outil spécifique. Le choix s’est donc orienté vers une structure de répertoires.

Les formats de fichier sont ouverts et privilégient les formats standards d’outils SIG tels que les GeoTIFF. Les données matricielles sont en binaire, parfois compressé, afin d’optimiser le stockage et les opérations de lecture/écriture.

Les opérations sont accessibles via UI ou via scripts (API) par l’instanciation d’une classe ‘Config_Manager_2D_GPU’. Les Jupyter Notebook sont supportés.

Créer un gestionnaire par l’API

Importer le module ‘config_manager’ du paquet ‘wolfhece’ dans le sous-répertoire ‘scenario’.

Créer une instance de la classe ‘Config_Manager_2D_GPU’ en passant en argument le chemin d’accès (format ‘str’ - chemin complet ou relatif). Il est également possible de passer un second argument (optionnel) de classe ‘WolfMapViewer’ si on souhaite lier une UI WOLF. Si une application wx tourne, une interface graphique du manager sera également créée.

Créer un gestionnaire depuis une UI WOLF

Depuis l’interface utilisateur de WOLF, il faut choisir :

‘File/Create…/Create scenarios manager’

Il est ensuite demandé de choisir un répertoire à analyser/utiliser :

Une nouvelle fenêtre s’ouvre avec le résultat de l’analyse :

Si le répertoire est vide, aucun arbre ne sera visible.

Description de la fenêtre du gestionnaire

La fenêtre contient 3 parties :

1. Un arbre énumérant la structure des répertoires et leurs contenus

2. Une liste de boutons d’action

3. Une zone de texte multilignes affichant des informations

Si des fichiers « .tif » existent dans la racine, des informations sont automatiquement extraites et affichées :

• La taille selon X et Y (‘shape’)

• La résolution spatiale selon X et Y (‘Resolution’)

• L’emprise spatiale de la matrice

  • Coin inférieur gauche (‘Origin’)

  • Coin supérieur droit (‘End’)

  • Largeur x Hauteur (‘Width x Height’)

Champ d’information

Le champ texte multilignes permet à l’utilisateur de recevoir de l’information mais pas de l’éditer.

L’édition des fichiers doit se faire via des outils spécifiques.

Il est recommandé :

• Pour les fichiers texte (*.txt) : Notepad++

• Pour les fichiers Python (*.py): Visual Studio Code

• Pour les fichiers GeoTif (*.tif, *.tiff) : WOLF, QGIS, ArcGIS

Types de fichiers analysés

Les fichiers analysés seront de plusieurs types et identifiés par leur extension :

• ‘tif’, ‘tiff’ : information matricielle au format GeoTIFF, c’est-à-dire géoréférencé. La donnée numérique peut être compressée (format supporté par GDAL). Le type de donnée est soit des réels, en Float32, soit des entiers, en Int32.

• ‘.py’ : script Python. L’utilisateur peut créer librement tous les scripts nécessaires au traitement souhaité. Le gestionnaire de scénarios propose néanmoins de créer des scripts vides à particulariser par la suite permettant de manipuler les données. Ces scripts seront différenciés des scripts libres au moyen d’une surcharge de classe. Par ce moyen, il est possible de manipuler, sur l’emprise de toute la modélisation :

  • la donnée topo-bathymétrique

  • la distribution du coefficient de frottement (‘n’ de la loi de Maning-Strickler)

  • les conditions aux limites faibles

• ‘npy’ : information matricielle au format NUMPY, non géoréférencée. Ces fichiers sont a priori internes à la modélisation (géolocalisation via un fichier externe ‘.json’) et ne devraient pas être modifiés manuellement par l’utilisateur non averti dans le cadre du gestionnaire de scénarios. Le type de donnée est soit des réels, en Float32, soit des entiers longs, en Int32, soit des entiers courts non signés, uInt8.

• ‘bin’ : information matricielle au format WOLF, géoréférencé via son fichier texte associé ‘.bin.txt’. Le type de donnée est soit des réels, en Float32, soit des entiers, en Int32.

• ‘json’ : métadonnées de modélisation stockées sous la forme d’un fichier texte au format JSON. Ces fichiers sont générés par le code et ne devraient pas être manipulés par l’utilisateur non averti.

• ‘txt’ : information au format texte, encodage UTF-8 (ou ANSI – MS Windows). Les données d’hydrogrammes seront fournies par cette voie.

Des fichiers avec d’autres extensions sont tolérés mais ne seront pas analysés par le gestionnaire.

Les fichiers dont le nom débute par ‘__’, quelle que soit l’extension, seront ignorés.

Tous les fichiers avec une extension licite seront organisés dans l’arborescence sous un nœud spécifique :

.

Un DC sur un nom de fichier l’activera dans le gestionnaire et déclenchera une ou plusieurs actions :

• ‘tif’, ‘npy’, bin’ : propose de charger le fichier dans l’UI de WOLF (si existe et liée), affiche les informations utiles du fichier. Si Ctrl est maintenu, chargement automatique sans boîte de dialogue.

• ‘py’ : si Ctrl est maintenu, affiche le contenu du fichier sur un fond vert si c’est un script WOLF valide et un fond rouge autrement.

• ‘json’ : pas d’action

• ‘txt’ : affichage du contenu, si Ctrl est maintenu et que le fichier est un hydrogramme alors affichage d’un graphique Matplotlib.

Hydrogrammes

Les hydrogrammes potentiels à modéliser sont à fournir sous la forme de fichiers texte ‘.txt’ contenant en première colonne le temps [s] et dans les colonnes suivantes les débits [m³/s] pour chaque zone d’injection. Le séparateur est une tabulation (info : caractère par défaut lors d’une opération de copier/coller depuis Excel).

La première ligne est une ligne d’en-tête libre (même nombre de colonnes, séparateur tabulation ‘\t’). Seule la position des colonnes compte pour le gestionnaire, pas l’en-tête.

Une valeur de débit négative est autorisée. Cela correspondrait alors à un prélèvement et non à un apport.

Les zones d’injection sont spécifiées spatialement via le fichier ‘infiltration_zones.npy’ dans les dossiers de modélisation ou ‘infiltration.tif’ dans le dossier principal de scénarios.assembly

Remarque : le simulateur effectuera automatiquement une vérification de cohérence entre le nombre de colonnes de débits et le nombre de zones d’injection de la matrice. En cas d’incohérence, le simulateur de démarrera pas et une information sera retournée.

Organisation des dossiers et des fichiers

Une zone d’étude pour laquelle différents scénarios doivent être modélisés s’organise via une succession de répertoires précise. Avant toute manipulation, le dossier de travail doit comporter impérativement:

• Les fichiers suivant, au format ‘.tif’, dans le répertoire principal (‘simulations’):

  • une matrice topo-bathymétrique (‘bathymetry.tif’) - Float32

  • une matrice de coefficient de frottement (‘manning.tif’) - Float32

  • (optionnel) une matrice de zones d’infiltration (‘infiltration.tif’) - Int32

• Les fichiers de débits à tester dans un sous-répertoire (‘discharges’) contenant les débits à tester, sous format ‘.txt’.

Plus en détails :

• il existera autant de sous-répertoires que voulu ; chaque sous-répertoire étant interprété comme un scénario.

• si des sous-répertoires existent en cascade, cela formera implicitement des scénarios supplémentaires additionnant les éléments de chaque répertoire parent jusqu’au répertoire de base.

• des modélisations seront stockées dans des répertoires ‘simulations’ pour chaque niveau de scénario.

Les noms des répertoires sont libres. Ils peuvent être utilisés adéquatement par l’utilisateur pour organiser les scénarios. Il n’y a pas de métadonnées associées aux scénarios. L’utilisateur peut gérer sa classification comme bon lui semble

Les noms en gras ci-dessus ne peuvent pas être modifiés.

Domaine de calcul

Le domaine de calcul sera défini sur base du fichier de bathymétrie. La valeur nulle attendue est « 99999. » ce qui signifie que le domaine de calcul sera défini par toute maille d’une valeur différente de la valeur nulle.

Il est du ressort de l’utilisateur de s’assurer que les valeurs nulles des différents fichiers « .tif » à agglomérer soient bien définies.

Boutons d’action

Un fois le dossier créé selon les consignes précédentes, différentes actions sont possibles :

• ‘Reload/Update structure’ : supprime de la mémoire la structure actuelle et réanalyse le même répertoire racine. Cette opération est nécessaire en cas d’ajout de scénario(s) et/ou de fichier(s) pour qu’ils apparaissent dans l’arbre. Certaines actions déclenchent automatiquement cette action de rafraîchissement. L’action referme l’arbre à son niveau supérieur.

• ‘Create void scripts’: crée des scripts vides au format WOLF dans le répertoire souhaité (cf boîte de dialogue). Ces scripts permettent de manipuler des données matricielles (topo-bathy et coefficient de frottement), via ‘update_top_mann_scen.py’, ou la simulation, via impose_bc_scen.py. Les noms des fichiers ‘.py’ peuvent être modifiés.

• ‘Assembly .vrt to current level’ : crée un fichier virtuel ‘.vrt’ qui assemble tous les fichiers associés à la topo-bathymétrie et au coefficient de frottement. Tous les fichiers entre le répertoire du scénario actif (DC sur l’arbre) et le répertoire racine seront compilés.

  Attention

  Les fichiers ‘.tif’ dont le nom commence par ‘bath_’ seront associés à la topo-bathymétrie. Les fichiers ‘.tif’ dont le nom commence par ‘man_’ seront associés au coefficient de frottement.

  Les autres fichiers ‘.tif’ seront ignorés.

  Cette opération utilise la commande ‘gdalbuildvrt‘. L’emprise spatiale et la résolution sont forcées sur base des fichiers ‘.tif’ du répertoire racine ; cela signifie que des matrices dont le positionnement est hors domaine ne seront pas exploitées. Ce fichier ‘.vrt’ est visualisable par un programme SIG mais pas par l’UI de WOLF.

• ‘Translate .vrt to .tif’ : converti le fichier ‘.vrt’ au format matriciel GeoTiff par la commande ‘Translate’. La donnée est compressée avec l’algorithme LZW.

• ‘Check consistency’: effectue certains tests de cohérence entre les fichiers. Exemple : toutes les matrices Numpy (liées à la modélisation) doivent posséder les mêmes dimensions ou bien tous les hydrogrammes doivent posséder le même nombre de colonnes. En cas de problème, un message est retourné dans la fenêtre d’information.

• ‘List simulation(s)’: Liste les chemins vers toutes les modélisations présentent dans la structure et affiche l’information dans la fenêtre.

• ‘Create simulation(s)’: crée une ou plusieurs modélisations sur base d’un répertoire de scénario et le choix d’un ou plusieurs hydrogrammes (cf chapitre lié à cette création de modèle).

Scripts

La structure ouverte de la gestion de scénario permet de modifier les données avec l’outil que l’utilisateur gère le mieux :

• QGIS, ArcGIS, WOLF… pour les données spatiales

• Notepad++, Excel, WOLF… pour les hydrogrammes

Il est également possible de procéder à l’automatisation de certaines tâches via des scripts Python.

Ces scripts peuvent être libres (via des fichiers ‘.py’ ou des Jupyter Notebook ‘.ipynb’, exploitant des librairies Gdal, GeoPandas, Shapely… ). Dans ce cas, l’utilisateur est pleinement responsable du traitement et de l’enregistrement.

Ces scripts peuvent être ‘guidés’ par le gestionnaire de scénarios. C’est le cas lorsqu’on active l’action ‘Create void scripts’. Dans ce cas, sont créés des fichiers ‘.py’ respectant un standard et des objets internes à WOLF.

Il est notamment possible de mettre à jour les données matricielles de topo-bathymétrie et du coefficient de frottement. Pour ce faire, il faut compléter les fonctions ‘update_manning’ et ‘update_topobathy’ du fichier ‘update_top_mann_scen.py’ ou le fichier renommé par l’utilisateur bien entendu.

Ces fonctions font partie d’une classe Python ‘Update_Sim_Scenario’ qui surcharge l’objet ‘Update_Sim’. Ces éléments, de même que le nom et les attributs des fonctions, ne peuvent en aucun cas être modifiés sous peine de ne pas être reconnus par le gestionnaire (cf affichage en vert ou rouge lors d’une activation dans l’arbre).

Chaque fonction reçoit en argument un objet ‘WolfArray’ (cf module Python ‘wolf_array.py’ du paquet ‘wolfhece’). Il s’agit du paramètre ‘manning’ pour le coefficient de frottement et de ‘topobathy’ pour la données topo-bathymétrique.

Le contenu des fonctions est libre mais doit être fonctionnel. Les importations proposées sont nécessaires pour le fonctionnement mais d’autres importations peuvent être ajoutées au besoin.

Une première aide succincte est présente par défaut mais peut être supprimée pour plus de lisibilité. Il y est rappelé que les matrices sont en Float32. La donnée est stockée sous la forme d’une matrice Numpy masquée et qu’il faut prendre soin à ne pas rompre le pointage de la variable. Il n’est donc pas possible de créer une nouvelle matrice Numpy (via np.zeros, np.ones par ex.) mais qu’il faut manipuler les données dans l’espace mémoire alloué (via [ :, :] ; +=…)

Il est également possible d’automatiser l’imposition de conditions aux limites. Dans la majorité des cas, une modélisation ‘wolfgpu’ n’aura besoin que de conditions limites à l’aval du domaine ; partout ailleurs ce sont des conditions d’imperméabilité qui seront automatiquement imposées, le(s) débit(s) étant géré(s) par l’intermédiaire de termes sources via les ‘zones d’infiltration’.

De façon similaire aux données matricielles, il faut respecter la classe ‘Impose_BC_Scenario’ qui hérite de ‘Impose_Boundary_Conditions’ et la fonction associée ‘impose_bc’ qui prend cette fois en paramètre ‘simul’, une instance de ‘SimpleSimulation’. Les modules importés sont similaires mais comportent une ligne de plus :

Une aide succincte est également présente et peut également être supprimée si cela est jugé utile pour la lecture et la modification. Il y est notamment rappelé que les conditions sont de type faible, c’est-à-dire imposée aux bords des mailles de calcul. La convention de position est d’énumérer les indices de la maille pour désigner le bord gauche (normale orientée selon X) ou le bord bas (normale orientée selon Y). A cette position est ajoutée une indication de direction ‘LEFT’ ou ‘BOTTOM’ (cf class Direction(Enum) dans le module ‘simple_simulation.py’ du paquet ‘wolfgpu’).

Les types de condition limite supportés sont (cf class BoundaryConditionsTypes(Enum) du module ‘simple_simulation.py’ du paquet ‘wolfgpu’) :

• H : niveau de surface libre [m DNG]

• QX : débit selon l’axe X [m²/s]

• QY : débit selon l’axe Y [m²/s]

• NONE : pas de CL (valable en écoulement supercritique sortant)

• FROUDE_NORMAL : imposition d’une altitude de surface libre respectant le nombre de Froude imposé ( \(Fr = \frac {u} {\sqrt{gh}} = \frac{q_n}{\sqrt{g h^3}}\)) sur base du débit normal au bord [-] ; utile pour une condition instationnaire (passage d’hydrogramme).

Création de simulations pour un scénario

Lors de la construction d’une modélisation pour un scénario (cf routine ‘create_simulation’ du module ‘config.manager.py’), les opérations suivantes sont réalisées dans l’ordre :

1. Validation de l’existence du répertoire du scénario sur disque avec les fichiers de base

2. Récupération des hydrogrammes utiles sur base des fichiers du dossier ‘discharges’

3. Création au besoin du répertoire ‘simulations’ et de sous-répertoires ‘sim_’+nom de l’hydrogramme.

4. Assemblage des informations matricielles ‘Assembly .vrt to current level’

5. Conversion ‘Translate .vrt to .tif’

6. Vérification de l’existence des fichiers ‘.tif’ assemblés. Output ‘All is fine’ si pas problèmes rencontrés.

7. Vérification de l’existence de ‘infiltration.tif’ dans le répertoire racine et utilisation, sinon création d’une matrice à modifier par l’utilisateur (output ‘infiltration_zones.tif created and set to -1 ! – Please edit it !’).

8. Pour chaque hydrogramme

   1. création d’un objet ‘SimpleSimulation’

   2. paramétrage de la résolution spatiale (‘param_dx’, ‘param_dy’) et du positionnement (‘param_base_coord_ll_x’ et ‘param_base_coord_ll_y’)

   3. paramétrage du nombre de Courant (‘param_courant’) à 0.4

   4. paramétrage de la durée de simulation (‘param_duration’) à la durée maximale de l’hydrogramme

   5. paramétrage de la pondération Runge-Kutta (‘param_runge_kutta’) à 0.5 (2^nd ordre de précision temporelle ; 0.3 est associé au 1^er ordre et plus adapté aux cas stationnaires)

   6. association des matrices (‘bathymetry’, ‘manning’, ‘nap’, ‘h’, ‘qx’, ‘qy’, ‘infiltration_zones’)

   7. appel de tous les scripts Python au format WOLF (topo-bathy, manning et conditions aux limites)

   8. ajout de l’hydrogramme

   9. sauvegarde sur disque

La dernière opération de sauvegarde sur disque va générer les matrices Numpy et un fichier de paramètres au format ‘.json’.

Ces modélisations peuvent finalement être modifiée via script et/ou exécutées par le code ‘ wolfgpu’.