1. Tutorial¶
1.1. Plugin installation¶
1.1.1. THYRSIS installation¶
1.1.1.1. 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 mirror to download package, add the following url :
And 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.
1.1.1.2. On Linux¶
Debian and related distributions
Clone the THYRSIS git deposit in a directory:
git clone https://link_to_the_repository
THYRSIS uses python3 (should be already installed with QGIS ) and some dependencies are required.
Note
Preferably, favor your distribution packages to pip packages. Distribution packages tend to be more stable to pip
A Makefile is provided to install THYRSIS and the dependencies. Use the following command :
If you already installed the dependency, you can install THYRSIS only using :
or directly use thyrsis.package
module to configure the installation :
python -m thyrsis.package -d <optional: no documentation> --loc <optional: locale to use for documentation en/fr> -i <optional: path to your QGIS user plugin directory, default: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugin>
Use the -d
to install THYRSIS without documentation.
You will need to activate THYRSIS extension into the QGIS plugins menus (Plugins > Manage and Install Plugins…). During the QGIS first launch, a .thyrsis
folder should be created into the $HOME
directory.
On CentOS and related distribution
You can now use the makefile as Debian-like system.
Note
Depending on you Centos version, package name can change. Please take a look of yum_requirements.txt
With some distribution (Centos6 for instance), it is not possible to access hidden folder through QGIS files explorer. To skip this problem, we recommand you to create a symbolic link of the plugin installation in a accessible folder. For example :
ln -s .local/share/QGIS/QGIS3/profiles/default/python/plugins/thyrsis ~/
1.1.2. Simulation codes¶
Simulation codes are executables needed by the plugin. These executables are used to simulate flow and hydrogeological transport.
The METIS software is provided with THYRSIS (installed with the Makefile or with OSGeo4W) and should be added to the $PATH.
OPENFOAM can also be used. If you install it, make sure the groundwaterFoam executable is accessible through the $PATH
You will choose the simulation codes using the Preferences dialog in QGIS.
1.2. Model creation¶
The goal of this tutorial is to give the right steps to the user to create a new model with his own data. Tutorial data can be found into the thyrsis/doc/source/tutorial
folder.
1.2.1. Create the mesh project¶
The first step aims to create a mesh project, which will be use to 2D horizontal saturated model calculation. We will see the steps to initialise a mesh project.
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...

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 (Lambert II Etendu)
You must fulfill the path where the mesh database will be saved. You have to save the database into the ~/.thyrsis/mesh
directory so it can be recognised by THYRSIS. The database must be named like SITE_MODEL_STUDY.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 field and hydrogeological parameters,
STUDY is the name of a particular study, associated to the considered model (optional).
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 :

Having a background layer can be useful for locating the project environment. On this purpose you can open a OpenStreetMap through the QGIS browser menu :

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.

At last, two rasters are needed for the mesh project creation:
a digital elevation model (DEM), named
mnt.tif
a “wall” raster (altitude of the water table), 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 under the other layers. You can also add some transparency in your DEM symbology properties. Your canvas should look like the following image :

Don’t forget to save your project (CTRL + S
or click on Project > Save
)
1.2.2. Create the mesh¶
Now we have a brand new project, we can start to build the hydrogeological model. We will create the mesh for the 2D model.
The first step will be to define the contours of the zone. Contours define the limit condition of the flowing model. Contours are contained in a polyline layer and we will define several contours according to the followings attributs :
groupe
: group name of the contournom
: optional, indicative name.longueur_element
: length element, determine the density of meshespotentiel_impose
: 0 or 1 (flag), must be set on 1 for the contour corresponding of rivers.
Note
potentiel_impose
attribut induces that user must create different contour polylines for river and non-river limits of a same domain.polylines with the same
groupe
will define a single domaine if they shape a closed set.
/!\ To create contour, enable the snapping tools of QGIS, and select the active layer option. It is necessary to create true topological layer where contours must be closed set.

Then select the contour layer, click on the editing button

and then activate the Add Line Feature
.

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
#. a east contour between the two rivers
#. a south contour on the river
#. a west contour up the hill
All contours must stand inside the DEM and wall raster extents. Each time you validate a polyline, an the following windows will open :

Please fulfill it, especially the potentiel_impose (1 for river limit)
You can also add another contour to create a finer mesh inside the first area. In case you create a domain with a single contour, you will notice that the snapping tool is not working on the line you are creating. You need to validate the polyline then use the vertex tool to select the final vertex and replace it on the initial vertex.
Save your contours layer. THYRSIS will populate the domain
layer with polygons obtained from the contour layer. If there is no polygon created in the domaines
layer, there must be a topological error (more likely, contours doesn’t shape a closed set for polygon, try to replace the vertex between the different contours features).
Your canvas should look like the following image, with a similar contours attributs layer :

Finally the final step to create the mesh is to use the Mesh
button in the THYRSIS toolbar :

The following windows will open :

Verify the layers and launch the mesh creation. It will update the noeud and mailles layer and also create altitude
and altitude_mur
layers.
You should obtain the following result :

1.2.3. Build model¶
There are two options to build the model. If you already have a raster permeability data or if you want to use a constant permeability value, it’s not necessary to do inversion. Otherwise you will need control points.
1.2.3.1. Model with inversion¶
Create control points
Control points has to be entered into the points_pilote layer, that has the following fields :
OGC_FID
: unique IDnom
: name of the control pointgroupe
: group of control points used for correlation visualization (exp. organism origin of the data)zone
: zone, used to associate additional pilot pointsaltitude_piezo_mesuree
: altitude of the water table from measure (m)altitude_piezo_calculee
: altitude of the water table from simulation (m)difference
calcul mesure : difference between both water table altitude (m)permeabilite
: permeability (m/s)
Note
The first five attributes are needed, the others will be calculated during inversion calculation
We provide a point_pilote.csv
file. Please open it using Layer > Add Layer > Add Text Delimited Text Layer
:

Please fulfill the form with X and Y coordinates columns :

To fill the points_pilote
layer, you can copy the features from the loaded csv, and paste it into the points_pilote
layer. If you use you own data, note that you can only paste the attribute table if the column names of your csv are the same as the points_pilote
layer.
At the end, the attribute table of the points_pilote
layer should look like the following one :

Configure inversion parameters
From the control points, it will be possible to simulated the hydraulic head distribution. The inversion process depends on the hynverse_parameters
table. The parameters are :
infiltration
: yearly mean infiltration m/s. For heterogeneous infiltration, please enter 0 value and provide au_infiltration.sat
file (include a value for each node).icalc
: calcul type (default value : 3),niter
: number of iteration (default value : 20),errlim
: error limit, process stops when the error is inferior to this value (default value : 0.1 m),alfmin
: minimal value for \alpha, process stops when \alpha is inferior to this value (default value : 10^{-5}),alfa
: initial \alpha 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 superior, the last iteration is not take into account and a new one is done by dividing \alpha by 2. This can be donenbessaismax
time (see below),nessaismax
: number of iteration possible by dividing \alpha by 2 (default value : 10),permini
: initial permeability value (default value : 2.10^{-5}),permin
: min permeability value (default value : 2.10^{-7}),permax
: max permeability value (default value : 2.10^{-4}),nv_npp
: number of closest nodes from the control points, used for control points potential estimation (default value : 4),nv_ppm
: number of closest control points from meshes center, used for permeability field estimation at each mesh (default value : 10),dv_pp
: radius (m) from control points to smooth permeability field by local mean (default value : 300 m),d_mesh
: min length from mesh center to node with imposed potential, used to add the center as control points (in case of an extern referencial to potential) (default value : 100 m).
To change theses parameters, please select the hynverse_parameters layer, click on the edit button and open the attribute table :

Because we don’t provide u_infiltration.sat
file, the infiltration
value must be change, please enter 4.75^{-9} (write 4.75e-09 in the attibute table)
1.2.3.2. Build model¶
Launch the process by clicking on the Model button :

If you choose to use control points, please check Create model with inversion
and accept form.
If you choose to use permeability data, please check Create model from a permeability field
, and enter the permeability field data.
Finally if you choose to use a constant permeability value, please check Create model with a constant permeability field value
, and enter the constant value.

Some layers are created :
v_norme : Darcy’s velocity (m/s))
permeabilite_x : permeability x (m/s)
epaisseur_zs : thickness of saturated zone (m)
epaisseur_zns : thickness of unsaturated zone (m)
potentiel : water table altitude (m)
potentiel_reference : water table altitude (m), if a potentiel layer has been specified.
If you build model from control points, you should see that the permeabilite_x layer changes at each iteration. At the same time, charts should be update to as the following image :

The upper chart shows the mean error between measured and estimated water table altitude. The downer chart shows the correlation between measured and estimated water table altitude.
If you build model from permeability data, layers will be updated, but there is no need to display mean error chart.
Note
If you already now simulations paramaters that you will use, you can edit the parameters tables. This step will be in the Simulation parameters section.
1.2.4. Integrate other data¶
To complete your project, there is some data that can be useful.
1.2.4.1. Boreholes¶
Among tutorial data you will find two csv (forages.csv
and stratigraphie.csv
). You can add boreholes with stratigraphique data with the following command, be careful to format as mentionned below :
python -m thyrsis.database.load_forages site srid forages.csv stratigraphie.csv [fracturation.csv]
load forage into the database
site : site name (str)
srid : EPSG id
the expected .csv format is:
- forages.csv: "Nom","Nom_reduit","X_L2E","Y_L2E","Z","H (tube_sol)","Z tube","Profondeur","Date de réalisation","Type","Localisation"
- stratigraphie.csv: "Forage","From\_","To\_","code_roche", "description_roche", "code_formation", "formation"
- (facultatif) fracturation.csv: "Forage","From","To","Taux_Frac"
where site
is the name of the site (“SACLAY”) and srid is 27572.
Boreholes are then available in your mesh project with the tool. Click on the button and then click on a borehole in the canvas, you should see a stratigraphic log like the following one :

1.2.4.2. Chemicals¶
To define chemicals spread, it’s necessary to precise which chemical is used for simulation. We provide chemicals.csv
which contains several chemicals information. Use the following command to add it to the database :
python -m thyrsis.database.load_chemicals chemicals.csv
load chemical into the database
the expected .csv format is:
- chemicals.csv: "name", "period", "atomic_mass", "radioactive_decay", "specific_activity", "water_quality_limit", "atomic_number", "masses_number"
1.2.4.3. Interest points¶
It’s also possible to add some interets points, where it will be possible to measure simulated values, and eventually compare it with field values. To add it, use the following command :
python -m thyrsis.database.load_points site point_file groupe
site : site name (str)
srid : EPSG id
point_file is a text file with a point per line, with the following informations :
x_coord y_coord nom <diplayed label> <label location>
where site
is the name of the site (“SACLAY”), srid
is the 27572 and groupe is the type of points (“calcul”,”puits_sables”,”cheminée”, other)
1.2.4.4. Measures¶
You can add mesures for each points that you previously loaded into the database. To do it, use the following command :
load_measure.py site element_chimique units concFile.dat
or
load_measure.py site potFile.dat
Finally save your mesh project by clicking to Project > Save
or doing Ctrl + S
1.3. Study creation¶
1.3.1. Create a calculate database¶
Several studies can be made from a mesh model, so studies are created apart from mesh database. To create a new study, it’s almost like creating a new mesh model. Go to the Thyrsis
menu and open the New
panel. Now that you created a mesh model, you should find the name of your site in the panel, and under it the name of your mesh model. Click on it.

You have to name your simulation database. This time the path of the database is not imposed. The name can be impotant if you want to save your template, the first string before underscore (if there is one) will be the name of your template. We can name it TutorialStudy1
.
THYRSIS create a QGIS project at the same time and load it.
You should obtain the following result :

You should see that the contour layer is displayed and that THYRSIS opens a new menu on the left.
1.3.2. Simulation parameters¶
There are several parameters to define for simulations. Maybe you already define it in the mesh model and parameters has been copied in the study database. Anyway you can modify it directly from the parametres
table, or you can also edite it from the Latin Hypercube
menu (Thyrsis > Create > Latin Hypercube
). The Latin Hypercube
menu is used for generate different sets of parameters when some of the parameters are uncertain. You can define the default value for each parameter and also minimal/maximal values and variation law to randomize parameters value for each simulation. The parameters are explained below :
WC, cinematic porosity
VGA, Alpha van Genuchten (m^{-1})
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, porosity matrix
For the tutorial simulations, we suggest the following parameters :
Note
Create several simulations will be necessary if you want to do probability map
1.3.3. Define injection zone¶
From this menu, you will define the simulation. The first combo box permits to define the spreaded chimical. You can also put simulation duration and the duration step (result map will be calculated at each step).
For this tutorial we will define a single located injection zone, but THYRSIS provides other simulation methods, as the Deposit spread over the entire domain method (Annexes pour méthode particulières ?)
Injection has the following characteristics :
center coordinates (x,y) of the injection
depth (m)
area
S
concerned by the injectionflux
F
, in kg/s or Bq/sduration of injection \Delta T
And to ease injection creation, it is possible to define F
directly in flux or in terms of concentration, mass and flux/concentration mode can be associated with a water leak. Each mode can be activated by clicking on its button.

Note
Flux
Flux button open the following windows :

Concentration
Concentration button open the following windows :

In case of definition by concentration C
, flux F
is calculated from :
F = ISC
where I
is the rain water infiltration flux, defined with the flow model.
Mass
Mass button open the following windows :

In case of definition by mass, flux F
and duration \Delta T are calculated from :
F=ISL_{s}
where L_{s} is the solubility limit of the chimical, and
\Delta T=\frac{M}{F}
Water leak
It is possible to add a water injection to the chimical injection. You can define the water volume injected V, in addition of flux F or concentration C. In that case, injection velocity is calculated from :
v=\frac{V}{S \Delta T}
This velocity can’t be greater to the saturated permeability K_{s}. Otherwise injection duration is modified by :
\Delta T=\frac{V}{0.9 S K_{s}}
and a message is emited to signal that it is advised to grow the injection area to :
S=\frac{V}{0.9 K_{s} \Delta T}
If concentration C is provided, then flux is equal to :
F=vSC
Here we will define a flux injection. Select HTO
chimical from the chimical combo box, choose a begin date (like 01/01/2012 for the 1st january 2012). Define a simulation duration of 200 year
with a step of 1 year
. Click on Flux button and fill the menu with a name of your choice and :
Begin : 01/01/2012 or later
Duration : 0.00021 year (can also be define in month, or day)
Flux : 9.8e^{-09}
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, by zooming you should see the injection zone that has been added to the injection layer.
1.3.4. Launch simulation and view results¶
To launch simulation, click on the engine button . After the calculation, a
resultats
layer will be added to the canvas.
ZNS menu will opened also with legend and figure of the injection in the 1D column graph.

Futhermore, the time control toolbar will be filled with the dates calculated from the begin date, the simulation duration and the step duration.

You can play the simulation through dates with this toolbar. You will see changes on the canvas and on the 1D column graph.

Futhermore there is also a 3D canvas to observe the scene.

Note
3D scene can be configured from the 3D parameters menu. To display Open Street Map background map on 3D scene, add Open Street Map to the QGIS canvas and activate Texture
check box.
1.3.5. Other features¶
1.3.5.1. Result control toolbar and 1D plot¶
Here is the result control toolbar :

With comboboxes you can change the result layer (concentration, probability, etc) and the units. There is three useful tools at the right of the toolbar. The tool on the left is used to get the mesh layer value for the location you click on and for the date displayed. The tool on the right will open a window with a balance chart of the masses. The tool in the middle is used to display value for point of interest (cf Interest points), and if you mentionned measures for a point, they will be displayed on the chart.

1.3.5.2. Injection zones¶
It is possible to define automatically injections zones with similar properties, using Thyrsis => Create => Injections Zones
. You will see that injcetions widget has been created in the THYRSIS menu.

1.3.5.3. Latin Hypercube¶
If some parameters are uncertain, you can use the latin hypercube to realize several simulations with different parameter. Open the latin hypercube with Thyrsis => Create => Latin Hypercube
and fulfill the menu, defining for each parameter a minimum and a maximum value, and the propability law used to create parameters simulations; define also the number of simulations you want to do.

1.3.5.4. Probability map¶
If you define several simulation, it is possible to get probability map from those simulations. To do it, use Thyrsis => Create => Probability map
and define a threshold (for example the chemical max concentration allowed for water consumption). The probability map will be made for the current date.
1.3.5.5. Isovalues and isovalues gdal¶
You can obtain isovalue from the resultats
layer using Thyrsis => Create => Isovalues
and Thyrsis => Create => Isovalues (gdal)
. You have to confirm the values you want to see for the current date (and also a ratio pixels by meter if you use gdal method)