%% LyX 2.0.2 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[12pt,french]{article}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{geometry}
\geometry{verbose,tmargin=2cm,bmargin=2cm,lmargin=2cm,rmargin=2cm,headheight=2cm,headsep=2cm,footskip=2cm}
\usepackage{textcomp}
\usepackage{graphicx}
\usepackage{hyperref}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\newcommand{\noun}[1]{\textsc{#1}}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

\makeatother

\usepackage{babel}
\addto\extrasfrench{%
   \providecommand{\og}{\leavevmode\flqq~}%
   \providecommand{\fg}{\ifdim\lastskip>\z@\unskip\fi~\frqq}%
}

\begin{document}
\includegraphics[width=5cm]{img/Logo-INRAE_Transparent.png}

~

~

~

\begin{center}
Tutorial for Pamhyr2

January 2024
\par\end{center}

~

~

\begin{center}
\textbf{\LARGE 1D Modeling of the Hogneau River (Nord, France)}

using Pamhyr2
\par\end{center}{\LARGE \par}

~

~

\begin{center}
{\large INRAE Lyon-Grenoble Auvergne-Rhône-Alpes}
\par\end{center}{\large \par}

\begin{center}
RiverLy, river hydraulics
\par\end{center}

~

~

~

~

~

~

\begin{center}
\begin{tabular}{lll}
Authors : & Pierre-Antoine Rouby & pierre-antoine.rouby@inrae.fr\tabularnewline
& Théophile Terraz & theophile.terraz@inrae.fr\tabularnewline
& Lionel Pénard & lionel.penard@inrae.fr\tabularnewline
\end{tabular}
\par\end{center}

~

\pagebreak{}

\begin{center}
\tableofcontents{}
\par\end{center}

~

\pagebreak{}

% \section{Introduction}
%
% TODO
%
% \pagebreak{}

\section{Install Pamhyr2}

Pamhyr2 can be downloaded from \url{https://gitlab.com/pamhyr/pamhyr2}.
\begin{center}
\includegraphics[width=15cm]{img/dl.png}
\par\end{center}

Use the GNU Linux or the Windows download button depending on your system. On windows, launch the installer. On Linux, unpack the archive and launch Pamhyr2.


\section{Create your first study}

On the main windows, click on \texttt{[Files] => [New Study]} to create a new study.
Give it a name, for example \textit{Hogneau}, and validate.

\begin{center}
\includegraphics[width=15cm]{img/NEWSTUDY.png}
\par\end{center}

During study, don't forget to save periodicaly your work, using the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/save.png} button on the main window.

\section{Create the structure of the river}

Click on \texttt{[River Network] => [Edit River Network]} or on the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/network.png} shortcut to create the structure of your river.
In this window, you must define an oriented graph that represents the reaches of your river network: the edges are the reaches and the nodes are either upstream boundary conditions, downstream boundary conditions or junctions.
A default reach exists in a new study.
For this tutorial, we will delete it:
click on the  \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/del.png} button to enter the \textit{Delete} mode, then click on the nodes.
We can now start with an empty window.
Press the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} to enter the \textit{Add} mode. Create two nodes by clicking in the grey zone of the window, and create a link by clicking again on each node.
Press \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} again to exit the \textit{Add} mode.
You created your first reach, with an upstream node and a downstream node.
In the lower part of the \textit{Edit River Network} window you can rename the nodes and the reaches.
As the reach you created is automaticaly selected, all the next steps will apply to this reach.
The window should look like that:

\begin{center}
\includegraphics[width=15cm]{img/network.png}
\par\end{center}

Close the \textit{Edit River Network} window.


\section{Edit the river geometry}

Click on \texttt{[Geometry] => [Edit Geometry]} or on the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/geometry.png} shortcut to define the geometry of the selected reach.
Click on the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/import.png} button and select the file \texttt{Data/Bief\_1.st}.
You should see:

\begin{center}
\includegraphics[width=15cm]{img/Geo.png}
\par\end{center}

On the left panel is a list of all the cross sections with their name and longitudinal abscisa.
In the top left plot you can see the top view of the river, on the top right panel the longitudinal cross-section of the river and in the bottom plot you can see the selected cross-section (blue) along with the next one (dashed purple) and previous one (dashed black).
You can move in the section list using the right table or by clicking on the sections on one of the two upper plot.

You can edit the selected cross section by clicking on the \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/edit.png"} icon.

select the cross section named \textit{PontRD101m} and open the edition window. You should see:

\begin{center}
\includegraphics[width=15cm]{img/editsect.png}
\par\end{center}

On the left panel is the list of all the points of the section, with their coordinates, their name and their transversal absisa.
The Z coordinate of the highest point is written in blue and the lowest in red.
Points can have a name.
If a point with the same name exists in every section in a reach, it forms a longitudinal line.
For example, here we have \textit{rg} and \textit{rd} which represent the left bank and the right bank of the main chanel.

On the plot is a projection of the cross section. You can click on a point to select it in the plot and \texttt{[right click]} to draw a water line and visualize usefull geometric data.
You can then remove this line with \texttt{[scroll wheel click]}.
You can close the cross section edition window and the geometry edition window.

% TODO mesh

\section{Edit the boundary conditions}

From the main window, click on \texttt{[Hydraulics] => [Boundary conditions and punctual contributions]} or on \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/boundary_condition.png"}.
You are now on the \textit{Boundary conditions} window:

\begin{center}
\includegraphics[width=15cm]{img/boundary.png}
\par\end{center}

 Use the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} button on the top left of the window to add a liquid boundary condition.
 On the new line, click to select the whole line, double click to select the cell.
 Select the \textit{Type} cell to give a name to the boundary condition.
 Here, we will define the flow discharge mesured during the february 2002 flood.
 You can name this boundary condition "flood2002".
 Select the \textit{Type} cell and use the combo box to put a \textit{Q(t)} law.
 Select the \textit{Node} cell and atribute this condition to the upstream node.
 Names of the nodes are recalled in the right panel with the network view.
 Now select the whole line and click on the edit button \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/edit.png"}.
 You opened the \textit{Edit Boundary Conditions} window.
 In a text editor, open the \texttt{Data/Fevrier\_2002.txt} file.
 Copy the content of the file (for example with \textit{ctrl+a ctrl+c}) and paste it in the left panel of the \textit{Edit Boundary Conditions} window with \textit{ctrl+v}.
 You can now see the flow discharge curve:

\begin{center}
\includegraphics[width=15cm]{img/fev2002.png}
\par\end{center}

Close this window.
Go back on the \textit{Boundary Conditions} window.
Add a new line, give it a name, give it the textit{Q(Z)} type (rating curve) and associate it to the downstream node of the network.
This downstream boundary condition corresponds to a weir.
There, the river transition from a fluvial flow to a torrential flow.
This allows us to compute a rating curve corresponding to the critical flow located over the weir.
Open the \textit{Edit Boundary Conditions} window (\includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/edit.png"}).
In the \textit{Edit boundary conditions} window click on \texttt{[Générer régime critique]} to comput the said rating curve.
Click on \texttt{[Make increasing]} to remove the points of the curve that are not strictly increasing.
You can close the the \textit{Edit Boundary Conditions} and the \textit{Boundary Conditions} window.

\section{Create initial conditions}

From the main window, click on \texttt{[Hydraulics] => [Initial conditions]} or on the \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/boundary_condition.png"} shortcut.
To start, the numerical solver needs to know the water elevation and the discharge at every cross-section of the river.
If you don't know the initial water elevation and flow discharge conditions of the river, you can use the \texttt{[Generate minimal depth]}, \texttt{[Generate from discharge]} or \texttt{[Generate elevation]} buttons to let Pamhyr2 estimate an initial condition using the Manning-Strickler formula.
Click on \texttt{[Generate from discharge]} and enter a discharge of $4 m^3$ in the pop-up window, and check the \texttt{[Generate depth]} to generate an initial water elevation condition based on the Manning-Strickler formula.
You should see:

\begin{center}
\includegraphics[width=15cm]{img/ic.png}
\par\end{center}

You can alternately use \texttt{[Generate elevation]} to enter a constant elevation of $21 m$ (upstream and downstream) associated with a null discharge.
The goal is to create a lake and to let the solver drain it to find a suitable initial state.

In your next simulations, you can use the final timestep of the previous simulation as an initial condition.
To do that, click on \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/import.png} and find the results contained in a \textit{.BIN} file.
This file should be in the sub-directory \textit{\_PAMHYR\_/Hogneau/default-mage}.

Close the \textit{Initial conditions} window.


\section{Edit friction coefficients}

We will now define the friction coefficients of the bottom of the river.
From the main window, click on \texttt{[Hydraulics] => [Edit friction]} or on the \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/friction.png"} shortcut.
You have to define sets of Strickler coefficients first.
Click on \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/edit.png"} to open the \textit{Strickler} window.
Here you can create couples of Strickler coefficients, the first one for the minor bed, the second one for the medium bed.
Click on \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} four times to create four new couples.
Give them the folowing values:

\begin{center}
\includegraphics[width=15cm]{img/K.png}
\par\end{center}

You can use the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/sort_A-Z.png} button to sort the couples by alphabetical order.
Close the \textit{Strickler} window.

On the \textit{Edit friction} window, add four lines with the button \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} to create four friction zones.
Each zone is defined by a \textit{begin} and \textit{end} KP associated with a \textit{begin} and \textit{end} Strickler couple.
The strickler coefficient couples inside a zone are interpolated from the \textit{begin} and \textit{end} couples.
In our case, we will use uniform coefficients per zone.
Set the zones as follow:

\begin{center}
\includegraphics[width=15cm]{img/frictions.png}
\par\end{center}

The selected zone is highlighted in blue. Close the \textit{Edit friction} window.

\section{Model hydraulic structures}

Sometimes there can be cross-sections in which Shallow water equations can not be used to model the water flow.
In that case, we have to define an other law to link the water elevation and the flow discharge.
This is the case, for example, under bridges when the water elevation is too high, leading to a flow in charge.
Pamhyr2 enables to define various hydraulic structures with laws that can be parametrized.
In our case, two bridges have to be represented as hydraulic structures.
From the main window, click on \texttt{[Hydraulics] => [Hydraulic structures]} to open the hydraulic structures window.
Click two times on the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} button to create two hydraulic structures.
Each structure can have a name and must have a reach and a KP.
Set them as follow:

\begin{center}
\includegraphics[width=15cm]{img/hs.png}
\par\end{center}

Select the RD101 bridge and click on \includegraphics[width=0.5cm]{"../../../src/View/ui/ressources/edit.png"} to edit the laws of this structure.
Hydraulic structures are composed of basic hydraulic structures.
You can combine the laws of several basic hydraulic structures to setup your structure.
A bridge can be modeled as a combination of an orifice for the flow under the bridge and a weir for the flow over the bridge.
Create two basic hydraulic structures with the button \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} and set them as folow:

\begin{center}
\includegraphics[width=15cm]{img/seuilRD101.png}

\includegraphics[width=15cm]{img/orificeRD101.png}
\par\end{center}

Go back to the \textit{hydraulic structures} window and aply the same procedure for the Thivencelle bridge:

\begin{center}
\includegraphics[width=15cm]{img/seuilThivencelle.png}

\includegraphics[width=15cm]{img/orificeThivencelle.png}
\par\end{center}

You can now close the \textit{hydraulic structures} windows.
If you open the \textit{geometry} window you can see the structure position in the longitudinal view.

\section{Solver parameters}

From the main window, click on \texttt{[Execute] => [Numerical parameters for solvers]}.
In the window \textit{solver parameters} select the \textit{Mage v8} tab.
Set the minimul timestep to 0.1. and keep the default values for the other parameters.
We need a smaller minimum timester because the solver needs to reduce the timestep in order to converge during the steep increase of discharge at the begining of the flood.

% TODO precision

Close the \textit{solver parameters} window.

\section{Run the simulation}

From the main window, click on \texttt{[Execute] => [Run solver]}.
Select \textit{Defaut-Mage - (Mage8)} anc click on the \textit{Run} button.
It will open the \textit{Solver log} window.
The \textit{Solver log} window displays the outputs of the solver.
From the \textit{Solver log} window you can re-run the computation with the button \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/run.png}, and you can click on the \textit{Results} button to open the \textit{Results} window.

\section{Visualize the results}

If you closed the \textit{Solver log} window, you can click on \texttt{[Results] => [Visualize last results]} from the main window to open the \textit{Results} window.
The top left panel let you select your reach, the bottom left panel lets you select a cross-section in that reach.
the three plots on the right show the reach and the cross-section the same way than in the \textit{Geometry} window.
You can use the bottom slider to visualize the results at different timesteps.
The red crosses in the graphs corresponds to sections where the water level exceeds the limits of the geometry at least one time during the simulation.
This does not corresponds to water leaks, as the solver artificialy adds a virtual wall at both ends of the cross-sections geometry.
To visualize the flow discharge, switch to the \textit{Hydrograph} tab.
To create custom 2D plots, click on the \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/add.png} button on the top left of the window.
Select the values you want on the $X$ and $Y$ axis and click on \texttt{[OK]}.
You can now see a new tab with the custom 2D plot in the right panel of the \textit{Results} window.
The button \includegraphics[width=0.5cm]{../../../src/View/ui/ressources/export.png} allows you to export your results to a CSV file if you want to post-process them outside Pamhyr2.

\pagebreak{}
\end{document}

