Commit 9d0e9582 by Olga Glogowska

### edited: Chapter 2: rearangement of subsections, initial description of...

edited: Chapter 2: rearangement of subsections, initial description of demonstrators and workflow, some TODOs to be discussed
 \section{Minimalistic Finite Volumes for the Euler equations} \section{Minimalistic \exahype\ solvers for the Euler equations} As an introduction into \exahype\ workflow, we provide a complete implementation of an Euler solver based on all three of \exahype's native finite volume and finite element solvers, i.e.: \begin{enumerate} \item finite volume solver \item ADER-DG solver without limiting \item ADER-DG solver with finite volumes limiting \end{enumerate} We provide a complete Finite Volume implementation of a plain Euler solver realised with \exahype. This solver relies on a Rusanov flux and can, with only a few lines, be changed into an ADER-DG scheme later. Indeed, it can be used by an ADER-DG scheme as a limiter. You find the \texttt{EulerFV} in the \texttt{Demonstrators} subdirectory. \subsection{Preparation} \noindent Finite Volume solver is the simplest one. In its basic version, it relies on a Rusanov flux. With only a few lines, it can be changed into an ADER-DG-without-limiting scheme later. It can also be used by an ADER-DG scheme as a limiter. You can find all of these basic implementations in the \texttt{Demonstrators} subdirectory of \texttt{ExaHyPE-Engine}. For simplicity, all demonstrators are based on \texttt{*.exahype} configuration files.\\ In the following we provide an extensive description of how to run your first application based on \textit{Demonstrators/EulerFV} demonstrator. The demonstrator folder contains solely files modified to realise the solver. All glue code are to be generated with the toolkit. Before we do so, we open the file \texttt{EulerFV.exahype}. This simple text file is the centerpiece of our solver. \subsection{Finite Volume Solver} \todo[inline]{Why can I not open *.vtu files in Paraview for steps later than 1?} \noindent The demonstrator folder \texttt{Demonstrators/EulerFV} contains solely files modified to realise the finite volume solver. All \textit{glue code} are to be generated with the \texttt{Toolkit}. Before you do so, open \texttt{EulerFV.exahype} configuration file. This simple text file is the of the solver. It specifies the solver properties, the numerical schemes, and it also holds all the mandatory paths: \begin{code} ... ... @@ -50,20 +55,38 @@ exahype-project EulerFV end exahype-project \end{code} \noindent To prepare this example for the simulation, we have to generate all glue code To prepare this example for the simulation, you have to generate all the glue code with the \texttt{Toolkit}. In order to do that, change into the main \exahype\ directory and run the \texttt{Toolkit} as follows: \begin{code} > ./Toolkit/toolkit.sh \ Demonstrators/EulerFV/EulerFV.exahype > cd ExaHyPE-Engine > ./Toolkit/toolkit.sh Demonstrators/EulerFV/EulerFV.exahype \end{code} \noindent and afterwards change into the application's directory (\texttt{Demonstrators/EulerFV}) and type in \texttt{make}. If the context generation is successful, you will not receive any output or confirmation. In that case, just change into the application's directory \texttt{Demonstrators/EulerFV}: \begin{code} > cd Demonstators/EulerFV \end{code} Now you should see all the files that have been created by the \texttt{Toolkit} as shown in Figure \ref{fig:demonstrators-EulerFV}. Colour legend is equivalent to the one presented in Figure{fig:demonstrators-workflow} showing a gneral overview of \exahype\-specific workflow. As you can see, the \texttt{Toolkit} is smart enough not to overwrite the files that have already been provided in the \texttt{Demonstrator/EulerFV}, as these are the files that contain the implementation of application specific system of PDEs, initial conditions, etc. \begin{figure} \centering \includegraphics[width=.9\textwidth]{tikz/demonstrators-EulerFV.pdf} \caption[Sketch (tikz): Files generated by the Toolkit]{Structure of the files for \texttt{EulerFV} demonstrator \label{fig:demonstrators-EulerFV}} \end{figure} \begin{design} Most modifications to the specification file do not require you to rerun the \exahype\ toolkit. A rerun is only required for changes to parameters with a trailing \texttt{const}, if you change the number or type of solvers, or if you change the number of plotters in the specification file. \end{design} Now, you are ready for the next step, i.e. compilation of your programme. In order to do that, type in the following: \begin{code} > make -j4 \end{code} The flag \texttt{-j} with \texttt{n} being the number of threads can speed up the compilation. Depending on your system, you might have to set/change some environment variables or adopt pathes, but both the toolkit and the makefile are very variables or adopt paths, but both the toolkit and the makefile are very chatty. For the present demonstrator, it is usually sufficient to set either \begin{code} ... ... @@ -73,55 +96,43 @@ or \begin{code} > export COMPILER=GNU \end{code} \noindent In both modes, the makefile defaults to \texttt{icpc} or \texttt{g++}, respectively. To change the compiler used, export the variable \texttt{CC} explicitly. \begin{design} Most modifications to the specification file do not require you to rerun the {\exahype} toolkit. A rerun is only required for changes to parameters with a trailing \texttt{const}, if you change the number or type of solvers, or if you change the number of plotters in the specification file. \end{design} \subsection{Run} Once the compile has been successful, you obtain an executable \texttt{ExaHyPE-EulerFV} in your application-specific directory. \exahype's specification files always act as both specification and configuration file, so you start up the code by handling it over the spec file In case anything goes wrong and compilation does not work, although you have fixed the errors reported, you might need to run \begin{code} > make clean \end{code} This will clean up after previous unsuccessful compilation attempt and remove all trash files. Once the compile has been successful, as shown in Figure \ref{fig:demonstrators-EulerFV}, you obtain in your application's directory, among other files, also an executable \texttt{ExaHyPE-EulerFV}.\exahype's configuration files always act as both specification and configuration file, so you start up the code by handing over the same \texttt{*.exahype} file to it again: \begin{code} > ./ExaHyPE-EulerFV ./EulerFV.exahype \end{code} \noindent A successful run yields a \texttt{*.pvd} file that you can open with A successful run yields a bunch of \texttt{*.vtu} files that you can open for example with Paraview\footnote{\url{www.paraview.org}} or VisIt\footnote{\url{wci.llnl.gov/simulation/computer-codes/visit}}, e.g. There are two quantites plotted: The time encodes per vertex and quantity at which time step the data has been written. VisIt\footnote{\url{wci.llnl.gov/simulation/computer-codes/visit}}.\\ \todo[inline]{Is $t$ parameter described correctly?} \noindent There are two quantites plotted: \begin{enumerate} \item The time encodes $t$ per vertex. Quantity $t$ is referring to a time step at which the data has been written to a vertex For these primitive tests with global time stepping, this information is of limited value. It however later makes a big difference if parts of the grid are allowed to limited value. It however later makes a big difference if parts of the grid are allowed to advance in time asynchronous to other grid parts. The second quantity $Q$ is a vector of the real unknowns. \item The second quantity $Q$ is a vector of the real unknowns. The underlying semantics of the unknowns is detailed in Section \ref{chapter:new-development-project}. For the time being, you may want to select first entry which is the density or the last quantity representing the energy. The plot should look similar \ref{chapter:aderdg-user-defined-fluxes}. For the time being, you may want to select first entry $Q[1]$ which is the density or the last quantity $Q[4]$ representing the energy. The plot should look similar to Figure \ref{fig:02fvm-snapshots}. Please note that this minimalistic \exahype\ application will yield some errors/warnings that no \texttt{exahype.log-filter} file has been found and thus \end{enumerate} \noindent Please note that this minimalistic \exahype\ application will yield some warnings that no \texttt{exahype.} \texttt{log-filter} file has been found and thus no filter is applied on the output messages. You will obtain tons of messages. The tailoring of the log outputs towards your needs is subject of discussion in ... ... @@ -130,8 +141,7 @@ For the present experiment, you should be fine without diving into these details. \newpage \begin{figure} \begin{figure}[H] \begin{center} \includegraphics[width=0.36\textwidth]{screenshots/02_FVM_00.png} \includegraphics[width=0.36\textwidth]{screenshots/02_FVM_01.png} ... ... @@ -148,4 +158,46 @@ details. \caption[Paraview snapshots: Euler Demonstrator Logo flow]{Snapshots of the time evolution of $Q_4$, ie. the energy distribution in the EulerFlow Finite Volume demonstrator code.}% \label{fig:02fvm-snapshots} \end{figure} \newpage \subsection{ADER-DG Solver without limiting} For ADER-DG solvers, the procedure is practically the same as for Finite Volume solvers. Thus we only provide an overview of files generated in this example - highlighting the role of each of these in the \exahype\ workflow. Please refer to Figure \ref{fig:demonstrators-EulerADERDG-without-limiting}. You are encouraged to explore the content of these files on your own. Some general remarks on Finite Volume and ADER-DG solver can be found in Chapter \ref{chapter:aderdg-user-defined-fluxes}. Further, detailed description regarding ADER-DG solver, though based on Shallow Water Equations (SWE) case, is provided in Chapter \ref{chapter:swe}. \begin{code} > cd ExaHyPE-Engine > ./Toolkit/toolkit.sh Demonstrators/EulerADERDG-without-limiter/ EulerADERDG-without-limiter.exahype > cd Demonstrators/EulerADERDG-without-limiter > make -j8 >./ExaHyPE-EulerADERDG EulerADERDG-without-limiter.exahype \end{code} \subsection{ADER-DG Solver with finite volumes limiting} \todo[inline]{ Is this the right way to run this example?\\ 1) vertices plotter does not work so needs to be commented out for it to run\\ 2) if commented out and only subcellplotter used, there is no *.vtk output} \noindent For ADER-DG solvers with limiting, the procedure is somewhat different. Please refer to Chapter \ref{chapter:coupling-limiter} for more detailed description of how to couple Finite Volume Limiter with ADER-DG solver. Analysing provided overview of files generated for this example can give some hints. Please refer to Figure \ref{fig:demonstrators-EulerADERDG}. You are encouraged to explore the content of these files on your own. \begin{code} > cd ExaHyPE-Engine > ./Toolkit/toolkit.sh Demonstrators/EulerADERDG/EulerADERDG.exahype > cd Demonstrators/EulerADERDG > make -j4 >./ExaHyPE-EulerADERDG EulerADERDG.exahype \end{code} \newpage \begin{figure} \begin{center} \includegraphics[width=.9\textwidth]{tikz/demonstrators-EulerADERDG-without-limiting.pdf} \end{center} \caption[Sketch (tikz): Files generated by the Toolkit]{Structure of the fiiles for \texttt{EulerADERDG-without-limiting} demonstrator} \label{fig:demonstrators-EulerADERDG-without-limiting} \end{figure} \newpage \begin{figure} \begin{center} \includegraphics[width=.9\textwidth]{tikz/demonstrators-EulerADERDG.pdf} \end{center} \caption[Sketch (tikz): Files generated by the Toolkit]{Structure of the fiiles for \texttt{EulerADERDG} demonstrator} \label{fig:demonstrators-EulerADERDG} \end{figure} \ No newline at end of file