1. General description¶
THYRSIS (Transport HYdrogéologique Rapide Simulé en Insaturé et Saturé) is a software to simulate hydrogeological flow and transport of chemical and radiologic substances in both unsaturated and saturated porous environments.
It is a QGIS extension which is able to use all features provided by this GIS (Geographical Information System).
The modeling is based of 1D vertical unsaturated columns, coupled with a 2D horizontal groundwater model. The groundwater flow model can be imported or directly created with THYRSIS, which includes the GMSH mesh builder [Geuzaine2009] and provides an inversion process [Renard2008], [Renard2016].
1D and 2D simulations are realized with an external software for hydrogeological flow and transport in porous environnement. Different softwares can be connected to THYRSIS and two softwares are currently implemented :
OPENFOAM, through the (opensource) porousMultiphaseFOAM toolbox [Horgue2015a], [Horgue2015b].
METIS (Modélisation des Écoulements et des Transports avec Interaction en milieu Saturé), developed by the Ecole des Mines de Paris [Goblet1989].
THYRSIS can handle several injection types (flux, concentration or mass) and several injection zones, which can be defined in surface or underground. Injection can also be defined on the whole study area and directly into the groundwater, ignoring the unsaturated zone.
THYRSIS includes uncertainty management using Latin Hypercube. By defining probability law for each parameters, the user can generate several simulations with different parameters and THYRSIS provides main statistics : mean, standard deviation and confidence interval. It also provides probability maps according to a threshold on a value.
The plugin uses the MPI protocol to implement parallel simulations in case of several unsaturated columns or uncertainty simulations with several parameter sets.
Chemical modeling is limited to the solubility limit approach, that helps to define solute flux on surface, and to the retention coefficient, which induces a slow-down in the solute transport. Solute compound speciation, complexation with organic material like humic substances and complex interactions with rock matrix are ignored.
THYRSIS plugin can simulate flow and material transport in “dual-porosity” model, as formulated by Gerke & Van Genuchten [Gerke1993] (but currently only with the METIS software).
THYRSIS is integrated to QGIS, so that users can define in a interactive way the injection zones and their characteristics, and the simulation parameters. Users can also launch simulations and display the results 1- in the 2D interface of QGIS, 2- in a 3D specific window, or 3- in time-dependant graphics showing the results as a function of time at specific locations, allowing for comparison with real measures. A mass balance graph is also created, showing total unsaturated and saturated mass as a function of time.
The plugin relies on Spatialite databases, which store all hydrogeological characteristics of the different models and also the simulation parameters.
2. Installation¶
2.1. Plugin installation¶
2.1.1. On Windows¶
Note
To use THYRSIS on Windows with OPENFOAM , WSL (Windows Subsystem Linux) is needed and has to be installed before THYRSIS. To that end, please open a PowerShell command line in Administrator mode and enter the following command :
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all
Reboot your machine, re-open a PowerShell command line in Administrator mode and enter the command :
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all
Reboot again your machine and then update WSL to version 2 by downloading the following executable and install it :
Check your installation by using the wsl command in a PowerShell command line and define wsl version 2 as default version using the following command :
wsl --set-default-version 2
Your system is ready to install THYRSIS on Windows.
To install THYRSIS on Windows, you need to use the OSGeo4W installer. Run it and choose the Advanced Install.

Follow the instructions until the installer asks you to choose the Download Site and add the following url :
Select it before clicking on next.

Search thyrsis amongst the available packages, and click on Skip to switch it on install (the thyrsis package version will be shown).

Then click on Next until the installation begins.
2.1.2. On Linux¶
2.2. Simulation softwares¶
1D and 2D simulations are realized with an external software for hydrogeological flow and transport in porous environnement. Two softwares are currently connected to THYRSIS :
OPENFOAM, through the (opensource) porousMultiphaseFOAM toolbox [Horgue2015a], [Horgue2015b]. Follow the instructions on the official site . Don’t forget to actualize environment variables with the bashrc file, located in
/opt/openfoam7/etc
. Then install theporousMultiphaseFoam
extension and make sure thegroundwaterFoam
executable is avalaible through the$PATH
variable environment.METIS (Modélisation des Écoulements et des Transports avec Interaction en milieu Saturé), developed by the Ecole des Mines de Paris [Goblet1989]. The
metis
executable must be avalaible through the$PATH
variable environment.
The simulation software is chosen by using the THYRSIS Preferences dialog.
2.3. Databases installation¶
THYRSIS is based on several spatialite databases, which are organized in a .thyrsis folder in your home folder, as such :
a Spatialite database named sites.sqlite, which contains general characteristics of the modeled sites, the measured data on these sites, and also the parameters of saved simulations.
a
mesh
directory, which contains the Spatialite databases associated to each hydrogeological model, named SITE_MODEL.mesh.sqlite, where :SITE is the site name - saved in sites.sqlite database,
MODEL is the model name - a model is composed of a mesh and of several hydrogeological fields and parameters,
THYRSIS plugin adds a new menu Thyrsis to the QGIS menu bar and gives access to several features. These features are summarized in the Interface chapter, which begins with the Preferences menu, in order to explain how to set configuration parameters.
3. Tutorial¶
This tutorial explains with an example how to create a new hydrogeologic model and how to create and use a new study.
Tutorial data can be found in the thyrsis/tutorial_data
folder.
A hydrogeologic model is associated to a site and is a combination of a mesh and some scalar and spatial characterics.
The site can be characterized by points of interest, measurements and boreholes descriptions.
3.1. Mesh creation¶
3.1.1. Mesh project¶
The first step is to create a mesh project, which will be used for 2D horizontal groundwater flow and transport calculation.
If THYRSIS is activated, there must be a Thyrsis menu in the main QGIS toolbar. To create a new mesh project, click on : Thyrsis>New>Mesh… (Figure 3.1.1).

Figure 3.1.1 New mesh creation¶
Note
THYRSIS will use the current projection to create the mesh database. Change the projection in QGIS to be sure you are using the right projection. In this tutorial, all data are projected in EPSG: 27572 (Extended Lambert II)
You must first fulfill the path where the mesh database will be saved. The ~/.thyrsis/mesh
directory is the right place to save the database for a later use by THYRSIS but another place can be chosen temporarily. The database must be named like SITE_MODEL.mesh.sqlite, where :
SITE is the site name - created and saved in the sites.sqlite database if it doesn’t exist,
MODEL is the model name - a model is composed of a mesh and of several hydrogeological parameters anf fields.
Here we will call it SACLAY_TUTORIAL, to indicate that it is a mesh model based on the SACLAY site and that it is the TUTORIAL mesh model. At the same time, THYRSIS will create a QGIS project (.qgs file). At the end your mesh directory should be like Figure 3.1.2.

Figure 3.1.2 Mesh directory¶
A background layer is useful for locating the project environment. For example, OpenStreetMap can be opened through the QGIS browser menu (Figure 3.1.3).

Figure 3.1.3 QGIS canvas with OSM layer¶
You can also add a river layer, which will be useful for delimiting the project area. For the tutorial, we provide a river.gpkg
file. Click on Layer>Add Layer>Add Vector Layer and add the river layer (Figure 3.1.4).

Figure 3.1.4 Add Vector Layer¶
At last, two rasters are needed for the mesh project creation:
a digital elevation model (DEM), named
mnt.tif
a “wall” raster of the aquifer substratum’s altitude, named
mur.tif
To add them, click on Layer>Add Layer>Add Raster Layer.
We recommend you to put the background layer and the raster layers below the other layers. You can also add some transparency in your DEM symbology properties. Your canvas should look like Figure 3.1.5.

Figure 3.1.5 QGIS canvas with DEM layer¶
Don’t forget to save your project (CTRL + S or click on Project>Save)
3.1.2. Meshing¶
The next step is the 2D mesh creation.
The contours layer must be defined first. It is a layer of polylines with the followings attributes :
groupe : group name of the contour,
nom : contour name,
longueur_element : element length, which defines the mesh density in the neighbourhood of the contour,
potentiel_impose : 1 if the contour corresponds to an imposed potential boundary condition, 0 or NULL otherwise.
To create the contours, enable the snapping tools of QGIS, and select the active layer option. It is necessary to create true topological layer with closed contours.

Figure 3.1.6 Enabling snapping¶
Then select the contours layer, click on the editing button (Figure 3.1.7),

Figure 3.1.7 Editing contours layer¶
and activate the Add Line Feature (Figure 3.1.8).

Figure 3.1.8 Adding line feature on the contours layer¶
For the tutorial, we want to create a mesh for the Plateau de Saclay. We recommand you to create 4 contours :
a north contour on the river,
an east contour between the two rivers,
a south contour on the river,
a west contour perpendicular to the north and south rivers.
All contours must be included within the DEM and wall raster extents. For each validated contour, the windows of Figure 3.1.9 opens.

Figure 3.1.9 Contours layer’s attributes¶
The field longueur_element must be filled and the field potentiel_impose must be set to 1 if the contour corresponds to an imposed potential boundary condition.
Nested contours can be created in order to define several meshing zones.
Because it is not possible to use snapping on itself (QGIS limitation), a closed contour must be created by defining first an almost closed contour, then using snapping and the QGIS node tool to move the last vertex on the first one.
Save the contours layer. THYRSIS will populate the domaines layer with polygons obtained from the contours layer.
If no polygon is created in the domaines layer, there is probably a topological error with non closing contours.
Your canvas should look like Figure 3.1.10, with similar contours attributes.

Figure 3.1.10 QGIS canvas after validating the contours layer¶
Finally use the Mesh button (Figure 3.1.11) in the THYRSIS toolbar to create the mesh.

Figure 3.1.11 Mesh button¶
The window of Figure 3.1.12 opens.

Figure 3.1.12 Mesh dialog¶
Verify the layers and launch the mesh creation. The noeuds and mailles layers will be updated and the altitude and altitude_mur layers created.
You should obtain the QGIS canvas of Figure 3.1.13.

Figure 3.1.13 QGIS canvas with mesh result¶
3.2. Model creation¶
3.2.1. Model parameters¶
The model definition must be started by setting scalar parameters values in the parametres table (Figure 3.2.1).

Figure 3.2.1 parametres table to fulfill.¶
These parameters are typical values of the site and can be modified later in a specific study. They are defined as :
WC, cinematic porosity
VGA, Alpha van Genuchten (
)
VGN, n van Genuchten
VGR, residual saturation
VGS, maximal saturation
VGE, inlet pression (
)
WT, total porosity
VM, volumic mass (kg/m³)
DK, partition coefficient (m³/kg)
SL, solubility limit (kg/m³)
DLZNS, ZNS longitudinal dispersivity (m)
DLZS, ZS longitudinal dispersivity (m)
WM, matrix porosity
Then, the permeability field must be defined by clicking on the Model button which offers 3 choices :
Create model with a constant permeability field value : this creates an hydrogeologic model based on an uniform permeability field, whose value must be filled in the dialog,
Create model from a permeability field : this creates an hydrogeologic model based on a permeability field given by an external tif file, which must be selected in the dialog,
Create model with inversion : this enables an inversion process based on measured piezometric values and pilot points, see Inversion.
3.2.2. Inversion¶
3.2.2.1. Pilot points¶
Pilot points must first be defined in the points_pilote layer, and the zone where they belong and the measured piezometric value (altitude_piezo_mesuree) must be set. Zones must be numbered from 1 without empty number. Several pilot points can belong to the same zone.
The points_pilote layer provides the following fields :
OGC_FID : unique ID
nom : name of the pilot point
groupe : group of pilot points used for correlation display
zone : zone, used to associate pilot points with same permeability value
altitude_piezo_mesuree : measured altitude of the water table (m)
altitude_piezo_calculee : calculated altitude of the water table (m)
difference_calcul_mesure : difference between calculated and measured water table altitude (m)
permeabilite : permeability (m/s)
Note
The four attributes nom, groupe, zone and altitude_piezo_mesuree must be filled, the others will be calculated during inversion process.
It is possible to import delimited text files in QGIS (QGIS menu Layer>Add a layer>Add a delimited text layer) and do copy/paste actions between the imported layer and the points_pilote layer. To ease the copy/paste action, it is recommended to name the columns in the imported layer according to the points_pilote table columns (nom, zone, altitude_piezo_mesuree).
We provide a point_pilote.csv file which can be opened by using Layer>Add Layer>Add Delimited Text Layer (Figure 3.2.2).

Figure 3.2.2 Loading the point_pilote.csv file with Add Delimited Text Layer¶
The QGIS dialog must be answered by selecting the right X and Y coordinates columns (Figure 3.2.3).

Figure 3.2.3 Selecting X and Y coordinates columns in the Text Delimited dialog¶
The points_pilote layer can be completed by copy/paste from the loaded csv layer. Only column names with the same name as the points_pilote layer can be pasted.
At the end, the attribute table of the points_pilote layer should look like Figure 3.2.4.

Figure 3.2.4 Attributes table of the points_pilote layer¶
3.2.2.2. Inversion parameters¶
The inversion process depends on the parameters of the hynverse_parametres table :
infiltration : yearly mean infiltration in m/s. For heterogeneous infiltration, please enter 0 value and provide a u_infiltration.node.sat or u_infiltration.elem.sat file.
icalc : calcul type (default value : 3),
niter : maximum iteration number (default value : 20, but higher values are useful to obtain a good convergence),
errlim : error limit : process stops when the error is less than this value (default value : 0.1 m),
alfmin : minimal value for
: process stops when
is less than this value (default value :
),
alfa : initial
value (default value : 0.5),
terr : initial value of the maximum permissible growth rate of error (default value : 1.2) : if the growth rate of error is larger, the last iteration is not taken into account and a new one is done by dividing
by 2. This can be done nbessaismax times (see below),
nessaismax : number of possible iterations by dividing
by 2 (default value : 10),
permini : initial permeability value (default value :
),
permin : minimal permeability value (default value :
),
permax : maximal permeability value (default value :
),
nv_npp : number of closest nodes from the pilot points, used for pilot points potential estimation (default value : 4),
nv_ppm : number of closest pilot points from mesh centers, used for meshes permeability estimation (default value : 10),
dv_pp : radius (m) around pilot points to smooth permeability field by moving average (default value : 300 m),
d_mesh : min length from mesh center to node with imposed potential or to existing pilot point, used to add the mesh center as pilot point (in case of an external reference potential) (default value : 100 m).
To change these parameters, select the hynverse_parametres layer, click on the edit button and open the attribute table (Figure 3.2.5).

Figure 3.2.5 Opening attribute table of the hynverse_parametres layer¶
Here the infiltration value must be set to (enter 4.75e-09 in the attibute table).
3.2.2.3. Computation¶
Inversion process is launched by cliking on the Model button (Figure 3.2.6).

Figure 3.2.6 Model button¶
then by selecting Create model with inversion in the Model button dialog (Figure 3.2.7).

Figure 3.2.7 Model button dialog¶
Several layers are created :
potentiel_reference : reference piezometric level (m), if an external reference potentiel layer has been specified,
potentiel : calculated piezometric level (m),
epaisseur_zs : groundwater thickness (saturated zone) (m),
epaisseur_zns : unsaturated zone thickness (m),
permeabilite_x : permeability on x axis (m/s),
v_norme : Darcy velocity norm (m/s),
During the inversion process, the permeabilite_x layer is updated at each iteration. Graphics showing the convergence are also updated (Figure 3.2.8).

Figure 3.2.8 QGIS canvas with inversion graphics¶
The upper graphic shows the mean error between measured and estimated water table altitude. The lower graphic shows the correlation between measured and estimated water table altitude.
Finally save your mesh project by clicking to Project>Save or doing Ctrl + S
3.3. Radionuclides¶
THYRSIS takes into account radioactive decay and specific activity of radionuclides. Radioactive decay is used in radionuclide transport simulations and specific activity is used for concentration to activity conversion.
These values are read from the elements_chimiques table, which can be filled by using the following command :
python -m thyrsis.database.load_chemicals radionuclides.csv
The radionuclides.csv file is provided in the thyrsis/tutorial_data
directory. It is a csv file with “;” separator and the followingsortedcolumns : “name”, “period”, “atomic_mass”, “radioactive_decay”, “specific_activity”, “water_quality_limit”, “atomic_number”, “masse_number”.
3.4. Site characterization¶
The sites can be described by adding points of interest, potential or concentration measurements and boreholes stratigraphy description.
3.4.1. Points of interest¶
It is interesting to define some points of interest, which will be inserted into the points_interet table and the points_interet QGIS layer. Simulation results at points of interest are automatically saved in a text file for further use.
Points of interest can be loaded in the sites.sqlite database by using the following command :
python -m thyrsis.database.load_points site srid points_file [group]
where :
site is the site name (str),
srid is the EPSG value (int),
points_file is a text file with three columns separated by blanks and on each line the sorted three values : x_coordinate, y_coordinate, name,
group is an optional string defining a set of points (like “calcul” (default), “borehole”, “chimney”…)
Note
The first line is not read.
Only points from “calcul” group are selected for result files.
3.4.2. Measurements¶
Concentration or potential measurements can be associated to the points of interest in order to display them with the simulation results.
Measurements can be loaded in the sites.sqlite database by using the following command :
- for potential :
python -m thyrsis.database.load_measure [-d] site potPoint.dat
- for concentration :
python -m thyrsis.database.load_measure [-d] site chemical unit concPoint.dat
where :
site is the site name (str),
potPoint.dat is a file with measured potential at the point ‘Point’,
concPoint.dat is a file with measured concentration at the point ‘Point’,
chemical is a chemical element of the elements_chimiques table (str),
unit is the unit of the concentration (str),
the
-d
option is used to remove previous inserted measured values.
potPoint.dat and concPoint.dat are blank-separated text files with format :
dd/mm/YYYY[ HH:MM[:SS]] value[ uncertainty]
3.4.3. Boreholes¶
Boreholes and stratigraphic or fracturing data can be loaded in the sites.sqlite database by using the following python command :
python -m thyrsis.database.load_forages site srid forages.csv stratigraphie.csv [fracturation.csv]
where :
site is the site name (str),
srid is the EPSG value (int),
forages.csv is a csv file with “;” separator and sorted columns :
“FullName”, “Name”, “X_m”, “Y_m”, “Z_m”, “TubeHeight_m”, “TubeAltitude_m”, “Depth_m”, “BuildingDate”, “Type”, “Location”,
stratigraphie.csv is a csv file with “;” separator and sorted columns :
“Name”, “From”, “To”, “RockId”, “RockDescription”, “FormationId”, “FormationDescription”,
fracturation.csv is a csv file with “;” separator and sorted columns :
“Name”,”From”,”To”,”FracturationRate”,
Note
The column names are not read and can be different but the column’s order must be strictly respected,
“RockId” refers to the USGS lithology pattern’id, cf. Stratigraphic logs ,
“FormationId” refers to the CGMW codification, cf. Stratigraphic logs .
Examples of forages.csv and stratigraphie.csv files are provided with the tutorial, with site name “SACLAY” and srid set to 27572.
Boreholes are then available in the THYRSIS project via the button. By clicking on this button and then selecting a borehole in the QGIS canvas, a stratigraphic log is displayed in the Borehole tab (Figure 3.4.1).

Figure 3.4.1 Borehole example¶
3.5. Study creation¶
A study is created from a model and describes one or several injections on the ground surface, inside the unsaturated zone or directly into the groundwater. Transient infiltration can also be modeled.
3.5.1. Computational database¶
A new study is created by using the Thyrsis menu, selecting the New menu and the name of the model previously created (Figure 3.5.1).

Figure 3.5.1 New study creation¶
A project name must be chosen and a study directory where the computational database and all the results will be saved.
THYRSIS creates a new QGIS project and load it (Figure 3.5.2).

Figure 3.5.2 QGIS canvas at the creation of a new study¶
The model is displayed and a new tab is opened on the left.
3.5.2. Simulation parameters¶
The study uses the default parameters associated to the hydrogeolgical models (cf Model parameters) but these parameters can be modified either directly by modifying the parametres table, or by editing the Latin Hypercube menu (Thyrsis>Create>Latin Hypercube) which can also be used to generate several sets of parameters in the context of uncertainty study. For each parameter a reference value, a minimal and a maximal value and a variation law should be defined.
For the tutorial simulations, we suggest the parameters of Figure 3.5.3.

Figure 3.5.3 Parameters definition for a new study¶
3.5.3. Injection¶
Injection characteristics are defined through the THYRSIS panel described in the user manual.
For this tutorial we will define a HTO flux on an unique injection zone.
The HTO is selected via the chemical element combobox.
The injection is defined by clicking on the Flux button (Figure 3.5.4).

Figure 3.5.4 Injection buttons¶
and filling the form with the following values :
Begin : 01/01/2012
Duration : 0.00021 year (can also be defined in month, or day)
Flux :
(enter 9.8e-9)
Area : 59 (or use the pen that allow to draw the area on the map)
Location : use the
button and click on map to define center of the injection
Depth : 0
Water volume : 0
Then click on the Save button : the injection zone is added to the injection layer.
3.5.4. Simulation and results¶
To launch simulation, click on the engine button . After the calculation, a resultats layer is added to the canvas.
The ZNS tab is opened showing simulated concentrations displayed on an 1D column (Figure 3.5.5).

Figure 3.5.5 ZNS tab¶
The time control bar (Figure 3.5.6) and the result control bar (Figure 3.5.7) of the THYRSIS menu bar are updated :
the time combobox is filled with the simulation dates,
the result combobox and the unit combobox are updated with the informations of the simulated variables.

Figure 3.5.6 Time control bar¶

Figure 3.5.7 Result control bar¶
The results can be displayed in the canvas (Figure 3.5.8) and in the 1D window (Figure 3.5.9) at any simulation date through the time combobox or by using the arrows in the menu bar.

Figure 3.5.8 QGIS canvas with simulation result¶

Figure 3.5.9 1D graphic¶
at any simulation date through the time combobox or by using the arrows in the menu bar.
Futhermore a 3D canvas can be used to display results (Figure 3.5.10).

Figure 3.5.10 3D graphic¶
Note
3D scene can be configured through the 3D parameters tab. To display Open Street Map background map on 3D scene, add Open Street Map to the QGIS canvas and activate Texture check box.
4. User manual¶
4.1. Modeling¶
The THYRSIS hydrogeological flow and transport modeling is based of the coupling of a 1D vertical flow and transport model in the unsaturated zone and a 2D horizontal flow and transport model in the saturated zone. The saturated 2D modeling is based on a steady state flow field, which is created independently for each site.
This steady state flow field can be imported from an external calculation or created directly in THYRSIS by defining a 2D mesh with the GMSH mesh builder [Geuzaine2009] and determining the flow characteristics - mainly the permeability field - with the HYNVERSE inverse process [Renard2008], [Renard2016].
4.1.1. Steady state groundwater flow¶
Steady state groundwater flow must be defined first, because it is used for transitional flow and transport calculations in saturated zone. It is also needed to define the characteristics of the 1D unsaturated columns, namely :
the column thicknesses,
the saturated permeability in the columns.
Steady state groundwater flow is a 2D calculation whose parameters are :
infiltration, which is constant in steady state, but can be spatially heterogeneous,
groundwater thickness, variable on the whole modeled domain,
permeability field.
The output are :
potential (or piezometric) field, i.e the altitude of the water table in case of unconfined groundwater.
Darcy’s velocity field.
Futhermore, it is the same mesh that is used for flow and transport in saturated zone.
All these informations are saved in spatialite databases.
Steady state groundwater flow is a complex hydrogeological modeling process. The model is built using a great amount of data concerning the topography and the geology (in order to determine the aquifer vertical extension), the meteorology (in order to estimate the infiltration) and the hydrogeology. These data are the result of bibliographic studies and borehole analysis on the site and its neighborhood, because the domain extent is often wider than the studied site. The permeability field definition is a hard task, mostly resolved using inversion calculation, coupling geostatistics and optimization process (HYNVERSE [Renard2008], [Renard2016]).
4.1.2. Groundwater flow in transitional regime¶
Groundwater flow in transitional regime is based on the model built in permanent regime, adding a storage capacity value, equal to the effective porosity in case of unconfined groundwater.
The flow simulation in transitional regime needs the knowledge of the infiltration variation over time. This information is provided as an external file, according to the appropriate syntax (cf. User files).
4.1.3. Flow and transport in unsaturated zone¶
Unsaturated zone modeling is based on 1D vertical columns creation. There are as many columns as injection zones, and their thicknesses are calculated by substracting the steady state piezometric level to the topographic altitude.
Flow is calculated using the Richards equation, with the Van Genuchten formula [Genuchten1980], modified by [Ippisch2006] :
with :
: pressure potential (L)
: input pressure (L)
: permeability (
)
: saturated permeability (
)
: reduced water content, or effective saturation
: water content
: residual water content
: saturated water content
and
(
) are fitting parameters.
There is a one to one connection between water content and the saturation permeability
using
:
.
When , then
and we get the original Van Genuchten formula.
4.1.3.1. Mesh building of unsaturated columns¶
The columns are split in centimetric thickness elements, on one hand to keep numeric stability even for low dispersivity value, and on the other hand to garanty accurate mass balance.
More precisely, at the top of the column, the thickness of the first element is :
where is the thickness of the unsaturated column, expressed in centimeters.
The first element’s thickness is mostly equal to 1 cm, except for columns with a thickness less than 1 m. Then element’s thicknesses increase with a geometric progression until the middle of the columns, to finally dicrease in symmetry to reach the bottom of the column. The geometric progression is deduced from the ratio between the thickness of the middle column element and the thickness of the top column element. The ratio is equal to 5 by default and can be configured by the user (coef_maillage in simulations table).
Furthermore, the elements thickness is constrained to be less than (van Genuchten coefficient) in order to garanty numeric stability in case of high
value.
4.1.3.2. Unsaturated zone parameters¶
The unsaturated zone differs from the saturated zone, because the flow and the transport are processed in a single simulation, which starts with a steady state flow calculation, followed by a transitional flow and transport calculation.
The transport model parameters in the unsaturated zone are :
kinematic porosity
(fracture and/or matrix pore system, according to the studied site),
total porosity
,
volumetric mass density
,
and n van Genuchten coefficients,
maximal and residual saturations,
longitudinal dispersivity (transverse dispersivity doesn’t exist in 1D),
partition coefficient
,
chemical solubility
(cf. Mass injection).
Among these parameters, the total porosity and the volumetric mass density are used to calculate the time delay coefficient R, according to the following formula :
As for saturated zone, transitional infiltration simulations in unsaturated zone require the knowledge of the infiltration variation over time, which is provided as an external file, according to the appropriate syntax (cf. appendix User files).
4.1.3.3. Diffuse injection on the whole domain¶
It is possible to simulate a diffuse injection on the whole domain, either by simulating as many unsaturated vertical columns as mesh nodes, or by simulating columns groups (composed of similar thickness and permeability) to reduce the amount of simulations. In this case, two parameters must be defined (simulations table) :
pas_echant_zns is the column sampling step. It defines the column size of a same group. If the step is defined to 5 m, groups will be defined as follow [0,5m], [5m,10m], [10m,15m], etc. The more the step is high, the more the number of groups is low.
rapport_max_permeabilite is the maximal ratio of permeability tolerated in a same group of columns, by default equal to 10.
4.1.4. Transport in saturated zone¶
Transport in saturated zone is based on the flow model in permanent regime or in transitional regime.
A injection in the groundwater can be :
a flow, a concentration or a mass, defined via the interface, if the migration in unsaturated zone has not to be modeled (cf. injection),
a flow, defined from flows calculated at the bottom of unsaturated columns. In this case, the flow is injected into the meshes (OpenFOAM) or nodes (METIS) related to each injection zones, in order to cover the whole injection surface.
Transport model paramaters in saturated zone are :
porosity (fracture and/or matrix pore system, according to the studied site),
longitudinal and transverse dispersivities,
chemical retention rate.
In case of a flow in transitional regime, the storage capacity coefficient is set to the effective porosity.
4.1.5. Injection characteristics¶
Chemical injection is defined by the following characteristics :
coordinates (x, y) of the injection zone center,
depth,
area S concerned by the injection,
flow F, expressed in kg/s or Bq/s,
injection duration
.
For convenience, the injection can be defined as a concentration or mass, as described below. A leak can also be modeled. To define it, a water volume is required.
4.1.5.1. Concentration injection¶
In case of an injection defined by a concentration C
, flow F
is calculated from :
where I
is the rain water infiltration, defined with the flow model in permanent regime.
4.1.5.2. Mass injection¶
In case of an injection defined by a mass M
, flow F
and duration are calculated using the solubility limit
of the chemical :
4.1.5.3. Leak¶
It is possible to add a water injection to the chemical injection by defining the water volume injected , in addition to the flow
or the concentration
. In that case, injection velocity is calculated from :
This velocity can’t be greater than the saturated permeability . If it is the case, more precisely if :
injection duration is modified by :
and a message is emited to notify that it is advised to increase the injection area by setting :
If concentration is provided, then flow is equal to :
The following spreadsheet summarizes the flow calculation, according to the available data :
Data |
||
|
||
|
||
No calculation |
4.1.6. Uncertainty analysis¶
THYRSIS provides the opportunity to create several flow and transport parameter sets, according to standard probability laws (uniform, log-uniform, normal, log-normal), in order to get confidence intervals on simulated variables or to create probability maps according to a threshold.
The number of simulations must be greater than 1 and a probability law and min/max values must be defined for each parameter. The parameter sets are generated by Latin Hypercube, and one simulation is realized for each parameter set. The simulations can be parallelized according to the settings in the Preferences . Finally, THYRSIS aggregates the results in order to calculate mean and standard deviation for each simulated variable.
Graphics display confidence intervals or probability maps.
4.1.7. Dual porosity model¶
Dual-porosity flow model, as explained by Gerke & Van Genuchten [Gerke1993], is available in THYRSIS, but currently only when using METIS. This model is based on the assumption that the Richards equation applies simultaneously in the matrix pore system and in the fracture pore system. For a one dimensional vertical system, flow equations in a elementary volume are :
In fracture pore system :
In matrix pore system :
with :
and :
and
(
) : fracture and matrix pore system permeabilities,
and
(L) : fracture and matrix pore system hydraulic head,
(
) : exchange term describing water transfert between fracture and matrix pore system,
and
(
) : source terms in fracture and matrix pore system,
: volume fraction of the fracture pore system in the total system,
and
(
) : specific water capabilities in fracture and matrix pore system,
: water saturation rate,
(
) : specific storage capacity coefficient in fracture and matrix pore system,
and
: porosity in fracture and matrix pore system,
(
) : transition permeability between fracture and matrix pore system,
(L) : mean half-distance between fractures,
: structure factor, that is the geometry of the fracture system (beta=3 in case of a set of orthogonal and regularly spaced fractures),
: empiric factor equal to 0,4.
4.2. Interface¶
4.2.1. Preferences¶
The Preferences menu allows to define the general configuration which is saved :
in the
.thyrsis.ini
file of the project folder where the computation database is saved,in the
thyrsis.ini
file of the$HOME/.thyrsis
folder.
At the first use of the plugin, the $HOME/.thyrsis
folder is created and the thyrsis.ini
file is set with default values. The Preferences dialog is opened and the user is asked to set his configuration (cf. infra).
When a project is re-opened, the configuration loaded is the .thyrsis.ini
file of the database folder. Therefore it is possible to define a configuration for each project.
4.2.1.1. Installation¶

Figure 4.2.1 Preferences menu, installation window¶
Installation preferences define the location of files and folders needed by the plugin :
the folder where the background layer maps are saved (.vrt files),
the MPI configuration file, which includes computational units to use, and the number of processes available for each unit, written like :
tata:8 titi:8 toto:4
Futhermore, it is also possible to define :
the MPI protocol, depending on the
mpiexec
found (MPICH, OpenMPI),the number of processes to use for parallelized computation,
the maximum number of vertical 1D columns to display.
Finally, two checkboxes are present in order to define :
if the logs have to be displayed in the terminal,
if detailed logs are wanted (verbose mode).
4.2.1.2. Variables¶

Figure 4.2.2 Preferences menu, Variables window¶
The variables preferences provide the opportunity to define which variables should be saved :
potential,
Darcy’s velocity,
concentration,
activity,
saturation,
and the display configuration, by defining:
the unit,
the scale,
the number of classes.
The scale defines the ratio between the minimal value to display and the maximal value obtained from simulation. By default the scale is set to 0.001, but a lower value can be chosen to get a better view of the plume extent.
The number of classes is used to display the plume with a graduated scale.
This preferences window enables also to define the mass unit for the mass balance and to check a box avoiding to display units, for communication purposes.
4.2.1.3. Animation¶

Figure 4.2.3 Preferences menu, Animation window¶
The refresh rate used for video export can be configure in this window.
4.2.1.4. Matplotlib¶

Figure 4.2.4 Preferences menu, Matplotlib window¶
This window allows the user to configure some matplotlib parameters such as :
tick label size,
y label font size,
legend font size.
4.2.1.5. Database¶

Figure 4.2.5 Preference menu, Database window¶
This window allows the user to connect to an experimental database by defining a connection service.
The push button Synchronize experimental database with site database enables the loading of boreholes, points of interest, hydraulic heads and volumic concentrations from the experimental base to the sites.sqlite database.
4.2.4. Dialogs and panels¶
4.2.4.1. 2D Panel¶

Figure 4.2.20 Example of 2D panel, with result layer displayed after a simulation¶
The 2D panel is the main QGIS interface, more precisely the map canvas. It is connected with the “Layers” panel and displays on various background maps the specific parameters of the hydrogeological model :
mesh nodes,
mesh,
points of interest,
boreholes,
contours,
potential (piezometric level),
permeability,
topographic elevation,
aquifer substratum altitude,
Darcy’s velocity,
unsatured zone thickness,
groundwater thickness,
reference potential, which is obtained by interpolation of the piezometric data, and could have been used to build the hydrogeological model, through inversion computation.
Injection zones, defined in the Thyrsis panel, are displayed in the 2D panel.
At the end of a computation, a result layer is also displayed in the 2D panel. The dates and the variable to display are controled by the Menu bar.
4.2.4.2. THYRSIS panel¶

Figure 4.2.21 Example of a Thyrsis panel, used to define injection zones¶
The THYRSIS panel is used to define injection zones.
The first values to define are :
the simulation name,
the chemical to use, selected in the drop-down menu,
the partition coefficient and the solubility limit in case of mass injection,
the starting date of the simulation, with format DD/MM/YYYY [hh:mm:ss],
a set of tuples (duration, step), that define the simulation output dates.
Then the type of injection can be chosen by clicking on :
flux (Thyrsis_Flux),
concentration,
mass.

Figure 4.2.22 Example of THYRSIS panel to define a flux injection zone¶
According to the injection type selected, relevant fields may differ, as mention in the injection part. A non-null water volume is a leak that induces a transient flow simulation.
It is possible to add as many injections as wanted by clicking many times on the selected button, but it is impossible to mix several injection types in the same simulation.
The center coordinates of the injection zone can be defined manually or by clicking on and then clicking on the wanted location in the map canvas.
Similary the surface can be defines manually in the Area field, or automatically calculated by clicking on and then drawing the shape on the map canvas.
Below the THYRSIS panel, three buttons allows to cancel or save the modifications, and also to launch computation :
4.2.4.3. Borehole¶

Figure 4.2.23 Example of stratigraphic log diplayed in the borehole panel¶
When stratigraphic and lithologic informations are provided in the sites.sqlite database, the stratigraphic log can be displayed in the borehole panel. Click on in the bar menu and select the borehole directly in the map canvas.
If the fracturated rate is known, it is displayed in the stratigraphic log.
This graphic representation is based on differents codifications presented in the stratigraphic logs annexe :
codification on the geological time scale (BRGM),
RGB colorimetric codification of the Commission for the geological map of the world (CGMW),
the lithology pattern chart from USGS.
4.2.4.4. 3D panel¶

Figure 4.2.24 Exemple of 3D panel¶
The 3D panel is used to display a three dimensional representation of the following three levels :
the aquifer substratum,
the piezometric level,
the topographic altitude.
If results from a simulation are available, they are displayed on the potential layer, with the same symbology used in the map canvas.
This panel is controled through the options of the “3D parameters panel” :
the cursor is used to ajust vertical scale,
checkbox can be activated to display :
texture,
contours,
boreholes,
computation points.
Colors of the topographic altitude and contours can be modified.
4.2.4.5. Unsaturated zone (ZNS)¶

Figure 4.2.25 Example of results displayed in the panel dedicated to the unsaturated zone¶
The ZNS panel displays in the unsatured zone columns the temporal evolution of the simulated variables.
These variables and units must be selected in the combobox of the bar menu.
Some options are provided to define the legend :
Automatic scale update of the legend : the legend scale is updated for each date. If desactivated, the legend is calculated on the whole timeseries.
Legend : this action opens a dialog to custom the legend,
Legend position : used to choose the legend position (left, right or bottom).
4.2.4.6. 1D panel¶
The temporal evolution curves are obtained by clicking on the button or the
button in the Menu bar, and are displayed in a new panel :
displays the temporal evolution of mass balance (if existing).
displays the temporal evolution of the selected variable in the combobox of the Menu bar, for each selected points in the QGIS map canvas.

Figure 4.2.26 Example of 1D graphic with temporal evolution of mass balance¶

Figure 4.2.27 Example of 1D graphic with temporal evolution of simulated and measured potential¶
4.3. Model building¶
A complete hydrogeologic model can be built with THYRSIS in two steps :
defining a domain and meshing it using the GMSH mesh builder [Geuzaine2009] ,
defining or computing a permeability field and computing all parameter fields.
4.3.1. Mesh¶
4.3.1.1. Operating principle¶
The mesh building is based on the use of the GMSH software [Geuzaine2009] . The first step is to define the bounds of the domain and sub-domains to model and the size of mesh for each one. Fixed points and lines can be integrated into the mesh.
Any contour element (polyline) can be defined as an imposed potential boundary condition. This will identify the corresponding nodes and cells associated with this boundary condition. By default, imposed potential value is equal to the topographic altitude value, in order to represent rivers or outcrops.
The mesh building needs two raster layers :
MNT (DEM), digital elevation model,
MUR, aquifer substratum altitude.
Once the mesh is built, the nodes and mesh tables must be filled in order to define the hydrogeological model. This can be done manually or by following the inversion process explained in the next chapter.
4.3.1.2. Implementation¶
4.3.1.2.1. New mesh project creation¶
The mesh project will be created according to the current projection, available on the bottom right corner of QGIS (Figure 4.3.1).

Figure 4.3.1 QGIS SRID¶
Users should apply the wanted projection before creating the project.
To create a new mesh project, use the menu Thyrsis>Nouveau>Maillage… (Figure 4.3.2).

Figure 4.3.2 New mesh creation¶
Then enter a name for the mesh project, e.g. SACLAY_TEST. The name must :
be extended with a suffix starting with _, and describing the new model.
A Spatialite database named SACLAY_TEST.mesh.sqlite is created, related to a SACLAY_TEST.mesh.qgs
QGIS project. This project is opened into QGIS (Figure 4.3.3).

Figure 4.3.3 New mesh project created¶
4.3.1.2.2. MNT and MUR layers definition¶
It is compulsary to provide a DEM layer (MNT) and an aquifer substratum altitude layer (MUR), preferably with the names mnt.tif and mur.tif. These layers should be opened into the mesh QGIS project (Figure 4.3.4).
The xyz_to_tif python script can be used to transform a .xyz file into a .tif file :
python -m thyrsis.utilities.xyz_to_tif file.xyz
Add as many raster/vector layers useful for the mesh definition (for example : satellite images, buildings, site contours).

Figure 4.3.4 Opening MNT and MUR raster layers.¶
Zoom on one of the layer extent (Figure 4.3.5).

Figure 4.3.5 DEM layer opened in QGIS, after a zoom on the layer.¶
4.3.1.2.3. Contour elements definition¶
In order to define the contours of the model, it can be useful to import an existing contours layer (Figure 4.3.6). The contours can also be defined directly into QGIS.

Figure 4.3.6 Adding a contours layer providing the contours of the site and the domain to mesh (if existing).¶
Select the contours layer and configure the snapping mode to use snap on vertex in the QGIS preferences (Figure 4.3.7 and Figure 4.3.8).

Figure 4.3.7 Snapping options selection¶

Figure 4.3.8 Snapping menu. Snap on vertex with a 10 pixels precision. Topological edition improve editing and maintaining common boundaries in polygon layers.¶
Activate the contours layer edition mode and add contours manually or copy contours from an existing contours layer :
Existing contours can be copied in the contours layer using copy/paste action,
Contour parts can be defined by selecting a contour and cutting it with the “Edit > Separate entities” tools,
Contours parts can be merged together by selecting them and using the “Edit > Merge selected entities”.
A length must be defined for each contour element, by opening and filling the attribute table of the contours layer. For each contour element with imposed potential boundary condition, the potentiel_impose field should be set to 1. In this case, the potential value will be computed from the DEM layer (Figure 4.3.9).
When all contour elements are defined, close the edition mode and save the changes.

Figure 4.3.9 For each contour element specify its length (m) and if it corresponds to an imposed potential boundary condition (potentiel_impose set to 1).¶
Once changes are saved, domaines and extremites layer are automatically updated. This checks the contours topological consistency (Figure 4.3.10).

Figure 4.3.10 Mesh domain after saving the contours layer, defining a closed domain.¶
Note
An endpoint (from the extremites layer) in the middle of a contour is usually related to a wrong snapping configuration,
Because it is not possible to use snapping on itself (QGIS limitation), a closed contour must be created by defining first an almost closed contour, then using snapping and the QGIS node tool to move the last vertex on the first one,
Open contours inside a domain are accepted and are considered as fixed lines of the mesh.
4.3.1.2.4. Fixed points definition¶
It is also possible to define fixed points that will be integrated to the mesh nodes. The meshing in the vicinity of a fixed node is specified by the longueur_element attribute. Fixed points can be copied from another layer using copy/paste (Figure 4.3.11).
Caution: element length is required for all fixed points.

Figure 4.3.11 Adding fixed points.¶
4.3.1.2.5. Mesh generation¶
Once the domains and fixed points are defined, click on the button to create the mesh (Figure 4.3.12). In the dialog, choose the DEM layer (MNT) and the aquifer substratum altitude layer (MUR). If available, add a potential layer. THYRSIS generates several layers (Figure 4.3.13) :
maillage (mesh), providing triangles of the mesh,
noeuds (nodes), providing the mesh nodes,
altitude, a layer that provides altitude at each mesh node, based on the MNT (DEM) layer,
altitude_mur, a layer that provide altitude of the aquifer substratum at each mesh node, based on the MUR layer.
potentiel_reference, providing the potential value at each node, if the potential layer has been set.

Figure 4.3.12 Dialog window for the mesh building, with MNT, MUR and potential layer selection.¶

Figure 4.3.13 Final mesh with transparency.¶
4.3.2. Parameters definition¶
The model definition must be started by setting scalar parameters values in the parametres table (Figure 4.3.14).

Figure 4.3.14 Parametres table to fulfill.¶
Then, the permeability field must be defined by clicking on the Model button which offers 3 choices (Figure 4.3.15) :
Create model with a constant permeability field value : this creates an hydrogeologic model based on an uniform permeability field, whose value must be filled in the dialog,
Create model from a permeability field : this creates an hydrogeologic model based on a permeability field given by an external tif file, which must be selected in the dialog,
Create model with inversion : this enables an inversion process based on measured piezometric values, cf. paragraph Inversion.

Figure 4.3.15 Model button dialog¶
4.3.3. Inversion¶
4.3.3.1. Operating principle¶
The goal of the inversion process is to determine a permeability field that, combined with a flow simulation, returns the measured piezometric data.
The piezometric data can be:
values provided at ponctual location, called pilot points (points pilotes),
values provided on the whole study area, through a piezometric layer, called reference potential (potentiel de référence). This layer usually is obtained by geostatistical methods from ponctual measures.
The inversion process provided by the plugin is limited to permanent regime (constant infiltration) and is based on the pilot points method [Renard2008], [Renard2016].
The operating principle is to ajust permeability on several “pilots zones”, using an iterative computation to minimize the mean error between the piezometric simulated values and the measured values :
where :
is the total pilot points number,
is the piezometric value calculated at the location
for the iteration
,
is the piezometric value measured at the location
.
For each iteration, each pilot zone permeability is ajusted as follows :
with :
where :
is strictly between 0 et 1,
is the permeability of the zone
for the iteration
,
is the number of pilot points in the zone
.
is the maximal value of
for the iteration
.
parameter is initiated to 0.5. The value seems to be a good compromise between precision and speed convergence. When the error increasing in a to important way,
parameter is divided by two and a new iteration starts from the before last iteration.
For each permeability zone, permeability is constrained by min and max value :
Iterative process is stopped in several cases :
when the maximal number of iteration is reached,
when the calculated error is less than a limit value
:
,
when the
parameter is less than a minimal value :
,
when the number of attempts to decrease the
parameter has been reached.
4.3.3.2. Implementation¶
Pilot points must first be defined in the points_pilote layer, and the zone where they belong and the measured piezometric value (altitude_piezo_mesuree) must be set. Zones must be numbered from 1 without empty number. Several pilot points can belong to the same zone.
It is possible to import delimited text files in QGIS (QGIS menu Layer>Add a layer>Add a delimited text layer) and do copy/paste actions between the imported layer and the points_pilote layer. To ease the copy/paste action, it is recommended to name the columns in the imported layer according to the points_pilote table columns (nom, zone, altitude_piezo_mesuree) (Figure 4.3.16).

Figure 4.3.16 Pilot points table¶
Then the parameter values of the hynverse_parametres table must be set (Figure 4.3.17) :
infiltration : yearly mean infiltration in m/s. For heterogeneous infiltration, please enter 0 value and provide a u_infiltration.node.sat or u_infiltration.elem.sat file.
icalc : calcul type (default value : 3),
niter : maximum iteration number (default value : 20, but higher values are useful to obtain a good convergence),
errlim : error limit : process stops when the error is less than this value (default value : 0.1 m),
alfmin : minimal value for
: process stops when
is less than this value (default value :
),
alfa : initial
value (default value : 0.5),
terr : initial value of the maximum permissible growth rate of error (default value : 1.2) : if the growth rate of error is larger, the last iteration is not taken into account and a new one is done by dividing
by 2. This can be done nbessaismax times (see below),
nessaismax : number of possible iterations by dividing
by 2 (default value : 10),
permini : initial permeability value (default value :
),
permin : minimal permeability value (default value :
),
permax : maximal permeability value (default value :
),
nv_npp : number of closest nodes from the pilot points, used for pilot points potential estimation (default value : 4),
nv_ppm : number of closest pilot points from mesh centers, used for meshes permeability estimation (default value : 10),
dv_pp : radius (m) around pilot points to smooth permeability field by moving average (default value : 300 m),
d_mesh : min length from mesh center to node with imposed potential or to existing pilot point, used to add the mesh center as pilot point (in case of an external reference potential) (default value : 100 m).

Figure 4.3.17 Inversion parameters table¶
Inversion is triggered by clicking on button, which opens the dialog of Figure 4.3.15.
Select the first item to launch pilot points inversion.
Inversion process will display a new panel with two graphs (Figure 4.3.18) :
the first one displays error evolution at each iteration,
the second displays correlation evolution between simulated and measured piezometric values at each iteration, grouped by zone.
The process updates the permeability map at each iteration and the layer is displayed if it has been activated before the calculation.

Figure 4.3.18 QGIS windows during an inversion process¶
Note that in the (Figure 4.3.18), nodes with imposed potential are highlighted. This can be obtained by using the DBManager (QGIS menu Database>DBManager…), selecting the current calculation database and executing the following SQL request :
select * from noeuds, potentiel_impose where noeuds.OGC_FID=potentiel_impose.nid
When the result is loaded, check the Load as a new layer checkbox, choose the GEOMETRY item for the geometry column, and name the new layer :

4.4. Spatialite database¶
This chapter describes the three types of database used by the THYRSIS plugin.
4.4.1. sites.sqlite database¶
The sites.sqlite database is defined in the installation Preferences and contains different tables, describing available chemicals to use in simulation, the studied sites and the reference simulations.
4.4.1.1. elements_chimiques table¶
The elements_chimiques table contains the main characteristics of radionuclides : number and atomic mass, specific activity and radioactive decay.
4.4.1.2. Sites tables¶
sites : this table links each site to an integer id.
points_interet : this table contains all interest points for each site, associated with a name and a belonging group.
mesures : this table contains all the measures associated to the interest points, with a date, the measured chemical id, the concentration and its uncertainty, the piezometric level and its uncertainty.
forages : this table contains general characteristics of boreholes (name, type, building date, depth, elevation).
lithologies : this table provides for each borehole the rock type and its USGS code, according to the depth.
stratigraphies : this table provides for each borehole the geological formation and its BRGM code, according to the depth.
fracturations : this table provides for each borehole the fraturated rate, according to the depth.
4.4.1.3. Reference simulation tables¶
Simulations can be stored in the sites.sqlite database (cf. Export, § Template), and reused as starting point to new simulations. Several tables are used to store these informations :
simulations : this table refers to a site and a hydrogeological model, and defines some parameters as follows :
nombre_de_simulations is the number of simulations to achieve, greater than 1 in case of uncertainty computation.
coef_maillage is the ratio between the mesh thickness in the middle of an unsaturated column and the thickness of the first mesh on the top, with default value 5.
pas_echant_zns is the column thickness sampling step, used in case of column thickness grouping. It defines the column thickness of a same group. If the step is defined to 5 m, groups will be defined as [0,5], [5,10], [10,15], etc. The larger the step, the smaller the number of groups.
rapport_max_permeabilite is the maximal permeability ratio for a same group of columns, by default equal to 10.
permeabilite_zns_uniforme is the saturated permeability value used for unsaturated columns in case of non-null value and missing u_permeabilite_zns.node.sat or u_permeabilite_zns.elem.sat file. Default value is null.
type_injection defines the injection type, with values among ‘aucune’ (default) i.e. none, ‘flux’, ‘concentration’ or ‘mass’.
type_infiltration defines the infiltration type, with values among ‘permanente’ (default) i.e. permanent regime or ‘transitoire’ i.e. transient regime.
insature defines if the unsatured zone has to be modeled. It can take values ‘oui’ (that is “yes”, default value) or ‘non’ i.e no.
parametres : this table refers to the simulations table, and defines the parameter values of each stored simulation :
nom is the parameter name, among:
WC, cinematic porosity
VGA, Alpha van Genuchten (
)
VGN, n van Genuchten
VGR, residual saturation
VGS, maximal saturation
VGE, inlet pression (
)
WT, total porosity
VM, volumic mass (kg/m³)
DK, partition coefficient (m³/kg)
SL, solubility limit (kg/m³)
DLZNS, ZNS longitudinal dispersivity (m)
DLZS, ZS longitudinal dispersivity (m)
WM, matrix porosity
valeur is the parameter value if the simulation number is 1,
valeur_min is the minimal parameter value in case of Latin Hypercube use,
valeur_max is the maximal parameter value in case of Latin Hypercube use,
loi_de_variation is the parameter probability law in case of Latin Hypercube use. Available values are ‘constant’ (default), ‘normal’, ‘lognormal’, ‘uniform’ or ‘loguniform’.
VGA, VGN, VGR, VGS, VGE parameters are the coefficients
,
,
,
,
in the Ippisch & Vogel (ZNS) formulation.
In case of dual-porosity simulation, the parameters listed above are duplicated, with the 2 suffix, and four parameters are added :
PL, bound permeability (m/s),
ASHAPE, factor corresponding to the average half-distance between two fractures,
BSHAPE, factor depending to the fractured geometry (a value of 3 corresponds to regularly spaced orthogonal fractures),
CSHAPE, empirical coefficient, usually equal to 0.4.
PL, ASHAPE, BSHAPE et CSHAPE parameters are the coefficients
,
,
et
of the Dual-porosity model.
openfoam_options : this table refers to the simulations table and compiles all OPENFOAM options. The default values are appropriate for almost all cases but some modifications can be necessary for some numerically difficult cases. These options are briefly defined below, with the default values in bracket.
Algorithmic parameters:
picard_tolerance: tolerance for the ZNS transient Picard’s algorithm (10).
picard_maxiter: maximum iteration number for the ZNS transient Picard’s algorithm (20).
newton_tolerance: tolerance for the ZNS transient Newton’s algorithm (1.e-10).
newton_maxiter: maximum iteration number for the ZNS transient Newton’s algorithm (20).
h_tolerance: tolerance for ZNS “h” solver (1.e-12).
h_residualControl: residual control for ZNS stationary “h” solver (1.e-10).
h_relaxationFactor: relaxation factor for ZNS stationary “h” solver (0.01).
potential_tolerance: tolerance for ZS “potential” solver (1.e-8).
potential_tolerance_relative: relative tolerance for ZS transient “potential” solver (0.1).
potential_residualControl: residual control for ZS stationary “potential” solver (1.e-6).
potential_relaxationFactor: relaxation factor for ZS stationary “potential” solver (0.5).
Time step managing:
delta_time_init: initial time step value (10).
dtfact_decrease: decreasing time step factor if Picard’s or Newton’s algorithm has not converged (0.8).
truncationError: time-scheme truncation error for time step computation (0.01).
Properties:
fluid_density: fluid density [kg/m3] (1.e3).
dynamic_viscosity: dynamic fluid viscosity [Pa.s] (1.e-3).
molecular_diffusion: molecular diffusion [m/s2] (0).
tortuosity: tortuosity [-] (1).
specific_storage: specific storage [-] (0).
hwatermin: minimal groundwater thickness for ZS “potential” solver [m] (0.1).
metis_options : this table refers to the simulations table and compiles all METIS options. The default values are appropriate for almost all cases but some modifications can be necessary for some numerically difficult cases. These options are briefly defined below, with the default values in bracket.
niter_gc_zns: maximal iteration number for the ZNS (unsaturated zone) conjugate gradient (100).
niter_gc_zs: maximal iteration number for the ZS (saturated zone) conjugate gradient (100).
The following options affect the ZNS flow resolution in permanent regime :
saturation_initiale: initial saturation value used for the ZNS flow calculation in permanent regime (0.8),
rmult_cormax: multiplier coefficient of the maximum dimension, that defines the maximal variation of hydraulic head (0.1),
c_pstep: initial value of the solution splitting (0.1),
c_ps_inc: initial value of the increment (0.1),
c_ps_tol: tolerance on the parameter stepping: the solution is considered converged when c_pstep is greater than 1 - c_ps_tol (allows to shorten a laborious convergence where we tend towards 1 without ever exactly reaching it) (1.e-5 ),
ratio_max_res: comparison of two methods of residue calculation. Allows more precise detection of local convergence in case of residue oscillation (1.e-6),
critereres: residue convergence criterion. The calculation is converged when c_pstep equals 1 and redres < critereres (1.e-5),
niterns: iteration number for the ZNS flow calculation in permanent regime (1000).
courant: ‘oui’/’non’ (yes/no). The Courant number is calculated from a saturation front pseudo-velocity. If courant = ‘oui’, time step is adjusted to constraint the front progression to one element per step. Useful for 1D abrupt front. (‘oui’).
emmagasinement: specific storage (
), used to handle important leak with the option ‘sat_nonsat’ = on, assorted to ‘courant’ = ‘oui’ (1.e-3).
kdecoup_delt_zns: ZNS initial time step (10).
kdecoup_dmin_zns: ZNS minimal time step (1).
kdecoup_delt_zs: ZS initial time step (100).
kdecoup_dmin_zs: ZS minimal time step (1).
force_fin_phase: ‘oui’/’non’ (yes/no), forces the end of phase with a large time step when the time step becomes too small (‘oui’).
max_iter: maximal iteration number for phreatic calculation (200),
relax_phreat: relaxation coefficient (weight attributed to the last iteration) (0.5).
critere_pot: convergence criterion on potential (0.1 m),
phrea_min: minimal groundwater thickness (1.0 m).
injections : this table refers to the simulations table, and defines injection characteristics:
profondeur: injection depth (m)
debut: injection starting date, DD/MM/YYYY format
duree: injection duration, in ‘day’, ‘month’ or ‘year’ unit
nom: injection name
volume_eau: water volume injected, en m³
coefficient_surface: ratio between the real injection area and the area of the corresponding nodes (case of borehole injection, where the real injection surface is limited to the borehole surface, which can be much smaller than the influence surface of the nodes) ;
coefficient_injection: ratio between the real quantity injected and the maximal quantity that it is possible to inject, according to the solubility (this allows to consider only a part of the whole mass, for an injection duration calculated from the total mass - only useful in case of mass injection. In case of concentration or flux injection, it is only a multiplier of the concentration or flux) ;
permeabilite: ZNS permeability value, automatically computed from the permeability field of the saturated zone, or from a u_permeabilite_zns.node.sat or u_permeabilite_zns.elem.sat file if existing, or equal to the permeabilite_zns_uniforme value of the simulations table, if not null.
infiltration: infiltration value on top of the unsaturated column, automatically computed from the hydrogeological model.
epaisseur: ZNS column thickness, automatically computed from the hydrogeological model.
altitude: ZNS column top altitude, automatically computed from the hydrogeological model.
dates_resultats : this table refers to simulations table and defines simulation output dates by providing as many times as necessary:
duree: duration, in ‘day’, ‘month’ or ‘year’ unit,
pas_de_temps: time step, which sample the duration, in ‘day’, ‘month’ or ‘year’ unit.
4.4.2. Model databases¶
Hydrogeological models are saved in independant spatialite databases, located in the models folder defined in the installation Preferences. Each database contains the tables defining the 2D mesh, the hydrogeological model characteristics and the paramaters used for inversion process, if appropriate.
4.4.2.1. Mesh tables¶
The following tables are used to define and build the mesh. Only contours and points_fixes tables are manually edited by the user. The other tables are automatically created and are secondary.
bords: secondary table used for the mesh building process,
contours : this table contains the definition of the contour elements used for the domain, with the following fields :
groupe: defines a contour class (site or river for example), but this field is not currently used,
nom: is the name of the contour element,
longueur_element: is the distance (in meters) between two nodes placed along the element (constrains the mesh size),
potentiel_impose: is equal to 1 if the contour element has imposed potential, otherwise equal to NULL or 0.
domaines: secondary table used to describe the domains to mesh, according to the contours,
extremites: secondary table containing the endpoints of the contour elements,
points_fixes : table containing the points to insert into the mesh :
nom: fixed point name,
groupe: group name of the fixed point,
longueur_element: distance, in meter, between two nodes near to the fixed point.

Figure 4.4.1 Contours table example¶

Figure 4.4.2 Fixed points table example¶
4.4.2.2. Inversion tables¶
The following tables are used to definie the inversion process parameters, the OPENFOAM and METIS options, and the pilot points used for the inversion (cf. Inversion) :
hynverse_parametres : inversion parameters (cf. Inversion),
openfoam_hynverse_options : OPENFOAM options :
fluid_density: fluid density (1.e3).
dynamic_viscosity: dynamic fluid viscosity (1.e-3).
potential_tolerance: tolerance for ZS “potential” solver (1.e-8).
potential_tolerance_relative: relative tolerance for ZS “potential” solver (0.1).
potential_residualControl: residual control for ZS “potential” solver (1.e-6).
potential_relaxationFactor: relaxation factor for ZS “potential” solver (0.5).
hwatermin: minimal groundwater thickness (0.1).
metis_hynverse_options : METIS options :
niter_gc_zs: maximal iteration number for the ZS (saturated zone) conjugate gradient (100),
max_iter: maximal iteration number for phreatic calculation (200),
relax_phreat: relaxation coefficient (weight attributed to the last iteration) (0.5).
critere_pot: convergence criterion on potential (0.1 m),
phrea_min: minimal groundwater thickness (1.0 m).
points_pilote : pilot points used for the inversion process :
nom : pilot point name,
groupe : pilot point group, used for correlation graphic,
zone : pilot point zone,
altitude_piezo_mesuree : measured groundwater altitude (m),
altitude_piezo_calculee : computed groundwater altitude (m),
difference calcul mesure : difference between measured and computed groundwater altitude (m)
zones : zone permeability, and min/max permeability values tolerated during inversion process.
4.4.2.3. Model tables¶
The following tables provide hydrogeological model’s meshes and nodes characteristics :
mailles : this table defines each mesh element by an ordered list of three (triangle) or four (quadrangle) node numbers, and provides for each element the following model characteristics :
surface: mesh surface (
),
altitude: topographic altitude (m),
altitude_mur: substratum altitude (m),
infiltration: infiltration value (m/s),
epaisseur_aquifere: aquifer thickness (m),
potentiel_reference: reference piezometric value (m),
potentiel: piezometric value (m),
flux_eau: seepage term (m/s),
epaisseur_zs: groundwater thickness (saturated zone) (m),
epaisseur_zns: unsaturated zone thickness (m),
permeabilite_zns: permeability of the unsaturated zone (m/s),
permeabilite_x: permeability on x axis (m/s),
permeabilite_y: permeability on y axis (m/s),
permeabilite_z: permeability on z axis (m/s) (unused),
v_x: Darcy velocity on x axis (m/s),
v_y: Darcy velocity on y axis (m/s),
v_z: Darcy velocity on z axis (m/s) (unused),
v_norme: Darcy velocity norm (m/s),
noeuds : this table contains the same model characteristics as the table mailles, but computed at each node.
noeuds_contour : this table contains the id of the contour nodes.
parametres : this table contains the hydrogeolocial model parameters (cf. Reference simulation tables).
potentiel_impose : this table contains the id of the nodes with an imposed potential, with the imposed value.
4.4.3. Calculation project¶
For each computation project, a new computation database is created as follows :
by copying the model database specified as input (from the mesh folder),
by creating the sites.sqlite tables and inserting the entries corresponding to the site,
by creating the results tables.
The new computation database contains the following tables:
from the model database :
bords
contours
domaines
extremites
hynverse_parametres
mailles
metis_hynverse_options
noeuds
noeuds_contour
openfoam_hynverse_options
parametres
points_fixes
points_pilote
potentiel_impose
zones
from the sites database for the considered site :
dates_resultats
elements_chimiques
forages
fracturations
injections
lithologies
mesures
metis_options
openfoam_options
points_interet
simulations
sites
stratigraphies
with results tables creation :
bilan_masse
dates_simulation
isovaleur
mailles_zns
noeuds_zns
noeuds_injections
parametres_simulation
4.5. References¶
- Goblet1989(1,2)
Goblet, P., Programme METIS. Simulation d’écoulement et de transport miscible en milieu poreux et fracturé. Notice de conception. ENSMP/CIG, 1989
- Renard2008(1,2,3,4)
Renard, F.; Jeannée, N. Estimating transmissivity fields and their influence on flow and transport: the case of Champagne mounts. Water Resources Research, 2008 , 44, W11414, doi:10.1029/2008WR007033
- Renard2016(1,2,3,4)
Renard, F.; Tognelli, A. A new quasi-3D unsaturated-saturated hydrogeologic model of the Plateau de Saclay (France). Journal of Hydrology, 2016, 535, 495-508, doi:10.1016/j.jhydrol.2016.02.014
- Horgue2015a(1,2)
Horgue, P.; Soulaine, C.; Franc, J.; Guibert, R.; Debenest, G., An open-source toolbox for multiphase flow in porous media. Computer Physics Communications, 2015, 187, 217-226
- Horgue2015b(1,2)
Horgue, P.; Franc, J.; Guibert, R.; Debenest, G., An extension of the open-source porousMultiphaseFoam toolbox dedicated to groundwater flows solving the Richards’ equation. , 2015, Archives ouvertes HAL, hal-01206922
- Gerke1993(1,2)
Gerke, H. H.; Van Genuchten, M. T. A Dual-Porosity Model For Simulating The Preferential Movement Of Water And Solutes In Structured Porous-Media. Water Resources Research, 1993, 29, 305-319 doi:doi.org/10.1029/92WR02339
- Geuzaine2009(1,2,3,4)
Geuzaine, C.; Remacle, J. F. Gmsh: A 3-D finite element mesh generator with built-in pre- and post-processing facilities. International Journal For Numerical Methods In Engineering, 2009, 79, 1309-1331, doi:doi.org/10.1002/nme.2579
- Genuchten1980
Van Genuchten, M.T. A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Sci. Soc. Am. J., 1980, 44, 892-898 doi:10.2136/sssaj1980.03615995004400050002x
- Ippisch2006
Ippisch, O. and Vogel, H. J. and Bastian, P. Validity limits for the van Genuchten-Mualem model and implications for parameter estimation and numerical simulation. Advances In Water Resources, 2006, 29, 1780-1789, doi:doi.org/10.1016/j.advwatres.2005.12.011
4.6. Annexes¶
4.6.1. Latin Hypercube¶
The Latin Hypercube is a useful sampling method for uncertainty analysis, which allows to reduce the number of samples compared to Monte Carlo methods. It is designed as LHS that means Latin Hypercube Sampling.
- The operating principles are:
to split the variation interval of each parameter in a number n of equiprobable sub-intervals,
to randomly select a value in each sub-interval for each parameter,
to build n samples by random permutation in order to obtain only one value of each parameter in each sub-interval. Figure 4.6.1 provides a schematic representation with two parameters and five samples.

Figure 4.6.1 Two-dimensionnal graphic representation of a Latin Hypercube Sampling with two parameters and five samples (n=5). X1 has a normal distribution between A1 and B1, X2 has a uniform distribution between A2 and B2.¶
To define n equiprobable sub-intervals of each probability density, the image of the distribution function has to be splitted in n regular intervals, then the distribution function has to be inverted.
4.6.1.1. Uniform or log-uniform law¶
In case of an uniform or log-uniform law in the [A,B] interval, inversion is :
where r is a randomly generated number in each of the n regular intervals that sample [0,1].
A example is provided Figure 4.6.2, in case of 5 samples and a uniform law between A2 and B2.

Figure 4.6.2 Matching between the sampled intervals on one hand, and on the other the probability density and the distribution function. Example with n=5, uniform distribution between A2 and B2.¶
4.6.1.2. Normal or log-normal law¶
In case of a normal or log-normal law, inversion is more complex and uses the error function defined as :
which is available in informatic libraries.
The distribution function of a normal law, with mean mu and standard deviation sigma is :
where :
and z is a random value in each sub-interval of the repartition function image.
The parameters and
are usually not known but can be computed from the bounds A and B of the parameter’s variation interval, defined as the 0.001 and 0.999 quantile, so that the formula is:
then, as :
An example is provided Figure 4.6.3, with 5 samples and a normal distribution between A1 and B1.

Figure 4.6.3 Matching between the sampled intervals on one hand, and on the other hand the probability density and the distribution function. Example with n=5, normal distribution between A1 et B1.¶
4.6.2. Stratigraphic logs¶
This appendix presents the codifications used for the graphic representation of the stratigraphic logs :
geological time scale codification from the BRGM (Figure 4.6.4),
RGB colorimetric codification from the Commission for the Geological Map of the World (CGMW) (Figure 4.6.5),
the lithology pattern chart from USGS (Figure 4.6.6, Figure 4.6.7, Figure 4.6.8).

Figure 4.6.4 Geological time scale codification from the BRGM.¶

Figure 4.6.5 RGB colorimetric codification from the CGMW.¶

Figure 4.6.6 Lithology pattern codification from USGS (1).¶

Figure 4.6.7 Lithology pattern codification from USGS, selon USGS (2).¶

Figure 4.6.8 Lithology pattern codification from USGS, selon USGS (3).¶
4.6.3. User files¶
This appendix describes the external file formats used by THYRSIS to modify some properties of the hydrogeological model. These formats are independents of the hydrogeological software used. The units are from international system, that is : date in second, length in meter, infiltration and permeability in meter/second, mass in kg.
4.6.3.1. u_epaisseur_zns.node.sat or u_epaisseur_zns.elem.sat¶
These files provide the thickness of the unsaturated zone at each node or element of the 2D mesh. They are useful to impose a different ZNS thickness field from the hydrogeological model.
They provide as many lines as nodes or elements (depending on the “.node” or “.elem” extension), with a thickness (in meter) on each line, ordered by node or element number.
Example:
27.6423
27.6636
27.6938
27.7452
27.7969
27.8473
27.9090
...
4.6.3.2. u_permeabilite_zns.node.sat or u_permeabilite_zns.elem.sat¶
These files provide the permeability in the unsaturated zone at each node or element of the 2D mesh. They are useful to impose a ZNS permeability field. The default is to compute the ZNS columns permeability values from the saturated permeability field.
These files provide as many lines as nodes or elements (depending on the “.node” or “.elem” extension), with a permeability (in meter/second) on each line, ordered by node or element number.
Example:
0.10062337E-04
0.10151087E-04
0.10006153E-04
0.10216447E-04
0.10134652E-04
0.98510526E-05
0.10076285E-04
...
4.6.3.3. u_infiltration.node.sat or u_infiltration.elem.sat¶
These files provide the infiltration of the permanent regime at each node or element of the 2D mesh. They should be used with caution, because they may lead to a inconsistency between simulated and modeled infiltration. They are mainly used to test the influence of a spatially heterogeneous infiltration.
These files provide as many lines as nodes or elements (depending on the “.node” or “.elem” extension), with a infiltration (in meter/second) on each line, ordered by node or element number.
Example:
2.98e-09
2.98e-09
2.98e-09
2.98e-09
2.98e-09
2.98e-09
...
4.6.3.4. u_infiltration_transitoire.sat and u_infiltration_transitoire.insat¶
These files provide a time-dependent but spatially homogeneous infiltration and are required in case of a flow simulation in transient state regime, whith the extension “.insat” when the unsaturated zone is taken into account, and the extension “.sat” if not. In order to obtain a relevant result, the resulting mean infiltration should be equal to the mean infiltration of the permanent regime.
The file format is presented in the exemple below. The date is given next to the entry “date” and the infiltration is given on the next line, with a negative sign corresponding to an input flow. The 0 value next to the infiltration value is unuseful but must be given.
Example:
date 0.0000000E+00
-0.6498923E-08 0
date 0.2629800E+07
-0.1411746E-07 0
date 0.5259600E+07
-0.9015090E-08 0
...
4.6.3.5. u_debit_entrant.sat¶
This file provides the chemical flow into the water table. It overwrites the “debit_entrant.sat” file automatically generated by THYRSIS.
The date is given next to the entry “date” and the chemical flows (kg/s) are given on the next lines, with a negative sign corresponding to an input flow and with a format depending on the software :
OpenFOAM : The chemical flows are given for each injection cell and are preceded by the cell coordinates.
METIS : The chemical flows are given for each injection node and are preceded by the node number.
OpenFOAM example:
date 3.155760e+05
637111.521 6847271.833 100 -2.514596e-16
637118.458 6847275.000 100 -3.023174e-16
637122.708 6847281.833 100 -1.394043e-17
637107.625 6847288.833 100 -8.280920e-19
637117.125 6847265.000 100 -2.757591e-17
...
date 6.311520e+05
637111.521 6847271.833 100 -2.859856e-16
637118.458 6847275.000 100 -3.438263e-16
637122.708 6847281.833 100 -1.585449e-17
637107.625 6847288.833 100 -9.417912e-19
637117.125 6847265.000 100 -3.136215e-17
...
date 9.467280e+05
637111.521 6847271.833 100 -2.860335e-16
637118.458 6847275.000 100 -3.438840e-16
637122.708 6847281.833 100 -1.585715e-17
637107.625 6847288.833 100 -9.419490e-19
637117.125 6847265.000 100 -3.136741e-17
...
METIS example:
date 3.155760e+05
17320 -4.832293e-16
11843 -2.915937e-16
1107 -5.763685e-16
17315 -5.149194e-16
...
date 6.311520e+05
17320 -5.993523e-16
11843 -3.616655e-16
1107 -7.148734e-16
17315 -6.386578e-16
...
date 9.467280e+05
17320 -5.992676e-16
11843 -3.616144e-16
1107 -7.147724e-16
17315 -6.385675e-16
...
4.6.3.6. u_debit_entrant.insat*¶
These files, whose names ended by the id number of the ZNS column, provide the chemical flow into the ZNS. They overwrite the “debit_entrant*.insat” files automatically generated by THYRSIS.
The date is given next to the entry “date” and the chemical flow (kg/s) is given on the next line, with a negative sign corresponding to an input flow and with a format depending on the software :
OpenFOAM : The chemical flow is preceded by the cell coordinates in case of deep injection, or by “top” in case of surface injection.
METIS : The chemical flow is preceded by the node number of the ZNS column mesh.
OpenFOAM example (surface injection):
date 0.000000e+00
top -2.314815e-15
date 7.862400e+06
top -2.314815e-15
...
OpenFOAM example (deep injection):
date 0.000000e+00
0.5 0.5 146.675 -2.314815e-15
date 7.862400e+06
0.5 0.5 146.675 -2.314815e-15
...
METIS example:
date 0.0000000E+00
625 2.3148148E-15
date 7.8624000E+06
625 2.3148148E-15
...
4.6.3.7. u_debit_eau_entrant.sat¶
This file provides the water flow into the water table. It overwrites the “debit_eau_entrant.sat” file automatically generated by THYRSIS.
The date is given next to the entry “date” and the water flows are given on the next lines, with a negative sign corresponding to an input flow and with a format depending on the software :
OpenFOAM : The water flows are given in (m3/s) for each injection cell and are preceded by the cell coordinates.
METIS : The water flows are given in (m/s) for each injection node and are preceded by the node number.
OpenFOAM example:
date 3.155760e+05
637111.521 6847271.833 100 -1.021677e-03
637118.458 6847275.000 100 -1.228312e-03
637122.708 6847281.833 100 -5.663981e-05
637107.625 6847288.833 100 -3.364528e-06
637117.125 6847265.000 100 -1.120406e-04
...
date 6.311520e+05
637111.521 6847271.833 100 -1.021858e-03
637118.458 6847275.000 100 -1.228529e-03
637122.708 6847281.833 100 -5.664982e-05
637107.625 6847288.833 100 -3.365123e-06
637117.125 6847265.000 100 -1.120604e-04
...
date 9.467280e+05
637111.521 6847271.833 100 -1.021913e-03
637118.458 6847275.000 100 -1.228596e-03
637122.708 6847281.833 100 -5.665289e-05
637107.625 6847288.833 100 -3.365305e-06
637117.125 6847265.000 100 -1.120665e-04
...
METIS example:
date 3.155760e+05
17320 -3.487842e-05 0
11843 -2.104659e-05 0
1107 -4.160100e-05 0
17315 -3.716574e-05 0
...
date 6.311520e+05
17320 -3.488461e-05 0
11843 -2.105032e-05 0
1107 -4.160838e-05 0
17315 -3.717234e-05 0
...
date 9.467280e+05
17320 -3.488655e-05 0
11843 -2.105150e-05 0
1107 -4.161070e-05 0
17315 -3.717441e-05 0
...
5. Translation¶
5.1. Documentation translation¶
THYRSIS documentation is based on sphinx. Source files are located in the doc/source folder :
conf.py is a python script that defines the configuration of the documentation (templates, languages, etc).
*.rst are text files based on reStructuredText syntax. They must be directly edited to update or improve the english version.
images folder contains images that are used by the documentation.
locale folder contains the translations into different languages, with one subfolder per language.
To translate THYRSIS documentation into another language, follow the next three steps :
in the doc folder, use the Makefile with the following command to create template files :
make gettextTemplate files will be created in build/locale.
to initiate a new language or update translate files use the following command :
sphinx-intl update -p build/locale/ -l frwhere ‘fr’ is the language ISO 639-1 code.
.po files will be created in source/locale/fr/LC_MESSAGES.
Open these .po files with QtLinguist to translate each sentence (Figure 5.1.1).
![]()
Figure 5.1.1 Example of .po file opened with QtLinguist¶
Then push the .po files to the gitlab repository. Online documentation will be updated after the commit will be integrated in the master branch. For local install on linux, reinstall THYRSIS using package.py module.
To export the documentation in pdf, use the following command in the doc folder :
make latexpdf
You may need to install the latexmk package to produce the file.
The pdf file is built in the doc/build/latex directory.
5.2. Interface translation¶
To fix and translate THYRSIS plugin interface, use qt internationalisation functionality. Strings to translate are the following :
strings from the *.ui files (in the gui folder)
strings identified by tr function in the *.py
All these files are listed in the i18n/thyrsis.pro file. The *.ts files are templates used to manage the translation. To update the template files, please use the following command :
pylupdate5 thyrsis.pro
Then open thyrsis_xx.ts files with QtLinguist to translate each string. When the translation is completed, use the release functionality in QtLinguist or the following command to produce the *.qm file :
lrelease thyrsis_xx.ts