Feature/helmholtz

Introduction of a Helmholtz tutorial to introduce users to elliptic solvers.

basics/helmholtz/basics-helmholtz.tex

@@ -29,19 +29,19 @@
 
 \chapter{Introduction}
 
-Welcome to the tutorial of the Helmholtz problem using the
-Advection-Diffusion-Reaction (ADR) Solver in the Nektar++ framework.
+Welcome to the tutorial on solving the Helmholtz problem using the
+Advection-Diffusion-Reaction (ADR) Solver in the \nektar framework.
 This tutorial is aimed to show the main features of the ADR solver in
 a simple manner. If you have not already downloaded and installed
-Nektar++, please do so by
-visiting \href{http://www.nektar.info}{nektar.info}, where you can
+\nektar, please do so by
+visiting \href{http://www.nektar.info}{http://www.nektar.info}, where you can
 also find the
 \href{http://www.nektar.info/downloads/8}{User-Guide} with the
 instructions to install the library.
 
 This tutorial requires:
 \begin{itemize}
-    \item Nektar++ ADRSolver and pre- and post-processing tools,
+    \item \nektar ADRSolver and pre- and post-processing tools,
     \item the open-source mesh generator \href{http://geuz.org/gmsh/}{Gmsh},
     \item the visualisation tool \href{http://www.paraview.org}{\underline{Paraview}}
 or \href{https://wci.llnl.gov/simulation/computer-codes/visit/downloads}{\underline{VisIt}}
@@ -51,7 +51,7 @@ or \href{https://wci.llnl.gov/simulation/computer-codes/visit/downloads}{\underl
 After the completion of this tutorial, you will be familiar with:
 \vspace{-0.5cm}
 \begin{itemize}
-\item the generation of a simple mesh in Gmsh and its conversion into a Nektar++-compatible format;
+\item the generation of a simple mesh in Gmsh and its conversion into a \nektar-compatible format;
 \item the visualisation of the mesh in Paraview or VisIt
 \item the setup of the initial and boundary conditions, the parameters and the solver settings;
 \item running a simulation with the ADR solver; and
@@ -116,7 +116,7 @@ can be solved in one, two and three spatial dimensions. We will here
 consider a two-dimensional problem. 
 
 \section{Problem description}
-The problem we want to run consists of known boundary conditions and
+The problem we want to solve consists of known boundary conditions and
 forcing function which depend on $x$ and $y$. To model this problem we
 create a computational domain also referred to as mesh or grid (see
 section \ref{helm-pre}) on which we apply the following two-dimensional
@@ -126,7 +126,7 @@ function with Dirichlet and Neumann boundary conditions.
 \begin{array}{l}
 \nabla^2 u - \lambda u =  -(2\pi^2 + \lambda) \cos(\pi x) \cos(\pi y) ,\\[1em]
 u(x,y) = \cos(\pi x) \cos(\pi y),\\[1em]
-u(x_{b} = \pm,y_{b}) = \cos(\pi x_{b}) \cos(\pi y_b),\\[1em]
+u(x_{b} = \pm 1,y_{b}) = \cos(\pi x_{b}) \cos(\pi y_b),\\[1em]
 \dfrac{\partial }{dn} u(x_{b},y_{b} = \pm 1)  =  \pm \dfrac{\partial }{dy} u(x_{b},y_{b} = \pm 1) = \mp \pi \left [\cos(\pi x_{b}) \sin(\pi y_b) \right ]
 \end{array}
 \label{eq:advection-2d}
@@ -137,18 +137,18 @@ computational domain (see section \ref{helm-configuring}) and
 $\lambda$ is a positive constant.
 
 We will set the boundary conditions and forcing function for this
-solver in section \ref{helm-configuring}) then after running the
-solver in section \ref{helm-running}) we will post-process the data in
+solver (see section \ref{helm-configuring}) then, after running the
+solver (see section \ref{helm-running}) we will post-process the data in
 order to visualise the results (see section \ref{helm-post}).
 
 \chapter{Pre-processing}
 \label{helm-pre}
-The pre-processing step consists in generating the mesh in a Nektar++
-compatible format.  For doing so we can use the open-source
-mesh-generator Gmsh to first create the geometry, that in our case is
-a square mesh. The mesh format provided by Gmsh shown in
-Fig. (\ref{f:gmsh}) - i.e. .msh extension - is not consistent with the
-Nektar++ solvers and, therefore, it needs to be converted.
+The pre-processing step consists of generating the mesh in a \nektar
+compatible format.  To do this we can use the open-source
+mesh generator Gmsh to first define the geometry, which in our case is
+a square mesh. The resulting mesh is shown in Fig. \ref{f:gmsh}. The mesh
+file format (.msh) generated by Gmsh is not directly compatible with the
+\nektar solvers and, therefore, it needs to be converted.
 %
 \begin{figure}[h!]
 \begin{center}
@@ -158,25 +158,25 @@ Nektar++ solvers and, therefore, it needs to be converted.
 \end{center}
 \end{figure}
 %
-To do so, we need to run the pre-processing routine
-called \inltt{NekMesh} within Nektar++.  This routine requires two
-line arguments, the mesh file generated by
-Gmsh, \inlsh{Helm\_mesh.msh}, and the name of the Nektar++-compatible
+To do so, we need to run the \nektar pre-processing routine
+called \inltt{NekMesh}.  This routine requires two
+command-line arguments: the mesh file generated by
+Gmsh, \inlsh{Helm\_mesh.msh}; and the name of the \nektar-compatible
 mesh file that \inltt{NekMesh} will generate, for
-instance \inlsh{Helm\_mesh.xml}. The command line for this step is
+instance \inlsh{Helm\_mesh.xml}.
 %
 \begin{tutorialtask}
 Convert the .msh file into a Nektar++ input from within the
-\$NEKTUTORIAL directory by calling
+    \inlsh{\$NEKTUTORIAL} directory by calling
 \tutorialcommand{\$NEK/NekMesh Helm\_mesh.msh  Helm\_mesh.xml}
 or 
 \tutorialcommand{\$NEK/NekMesh Helm\_mesh.msh  Helm\_mesh.xml:xml:uncompress}
 \end{tutorialtask}
 %
-Note that by default the information is stored in Xml blocks of
+Note that by default the information is stored in XML blocks of
 compressed data to reduce the size of large meshes. The second command
 above tells the converter \inltt{NekMesh} to write the file out in
-uncompressed format.  The generated .xml mesh file is reported below
+uncompressed ASCII format.  The generated .xml mesh file is shown below
 and can also be found in the \inlsh{completed} directory.  It contains
 5 tags encapsulated within the \inltt{GEOMETRY} tag, which describes
 the mesh.  The first tag, \inltt{VERTEX}, contains the spatial
@@ -185,22 +185,18 @@ second tag, \inltt{EDGE} contains the lines connecting the vertices.
 The third tag, \inltt{ELEMENT}, defines the elements (note that in
 this case we have both triangular - e.g. \inltt{<T ID="0">} - as well
 as quadrilateral - e.g. \inltt{<Q ID="85">} - elements). The fourth
-tag, \inltt{COMPOSITE}, is constituted by the physical regions of the
-mesh called \textbf{composite}, where the composites formed by
-elements represent the solution sub-domains - i.e. the mesh
-sub-domains where we want to solve the linear advection problem (note
-that we will use these composites to define expansion bases on each
-sub-domain in section \ref{helm-configuring}) - while the composites
-formed by edges are the boundaries of the domain where we need to
-apply suitable boundary conditions (note that we will use these
-composites to specify the boundary conditions in
-section \ref{helm-configuring}).  Finally, the fifth
+tag, \inltt{COMPOSITE}, describes the physical regions of the
+mesh and each composite may contain only one type of mesh entity. There are
+three composites composed of triangular or quadrilateral elements
+which represent the solution sub-domains where we want to solve the linear
+advection problem. We will use these composites to define expansion bases on
+each sub-domain in section \ref{helm-configuring}. The composites
+formed by edges are the boundaries of the domain where we will prescribe
+suitable boundary conditions in section \ref{helm-configuring}.
+Finally, the fifth
 tag, \inltt{DOMAIN}, formally specifies the overall solution domain as
-the union of the three composites forming the three solution
-subdomains (note that the specification of three subdomain -
-i.e. composites - in this case is necessary since they are constituted
-by different element shapes). For additional details on
-the \inltt{GEOMETRY} tag refer to
+the union of the three element composites. For additional details on
+the \inltt{GEOMETRY} specification refer to
 the \href{http://www.nektar.info/downloads/8}{User-Guide}.
 %
 \begin{lstlisting}[style=XMLStyle]
@@ -239,12 +235,13 @@ the \href{http://www.nektar.info/downloads/8}{User-Guide}.
 </NEKTAR>
 \end{lstlisting}      
 %
-After having generated the mesh file in a Nektar++-compatible
+After generating the mesh file in the \nektar-compatible
 format, \inlsh{Helm\_mesh.xml}, we can visualise the mesh.  This
-step can be done by using the following Nektar++ built-in
+step can be done by using the following \nektar built-in
 post-processing routine:
 %
-\begin{tutorialtask} Convert the .xml file into a .vtu format within the \$NEKTUTORIAL directory by calling
+\begin{tutorialtask} Convert the .xml file into a .vtu format within the
+    \inlsh{\$NEKTUTORIAL} directory by calling
 \tutorialcommand{\$NEK/FieldConvert Helm\_mesh.xml  Helm\_mesh.vtu}
 Alternatively a tecplot .dat file can be created by changing the extension of the second file, i.e. 
 \tutorialcommand{\$NEK/FieldConvert Helm\_mesh.xml  Helm\_mesh.dat}
@@ -272,7 +269,7 @@ boundary conditions, parameters and solver settings.
 To set the various parameters, the solver settings and the initial and
 boundary conditions needed, we create a new file
 called \inltt{Helm\_conditions.xml}, which can be found within the
-\inlsh{completed} director for this tutorial.  This new file contains
+\inlsh{completed} directory for this tutorial.  This new file contains
 the \inltt{CONDITIONS} tag where we can specify the parameters of the
 simulations, the solver settings, the initial conditions, the boundary
 conditions and the exact solution and contains the \inltt{EXPANSIONS}
@@ -404,16 +401,15 @@ Gmsh. For additional details on the \inltt{EXPANSIONS} tag refer to
 the \href{http://www.nektar.info/downloads/8}{User-Guide}.
 
 \begin{tutorialtask}
-Generate the file \inlsh{Helm\_conditions.xml} in the direcotry
-\$NEKTUTORIAL with $\lambda=2.5$ or copy it from the \inlsh{completed}
+Generate the file \inlsh{Helm\_conditions.xml} in the directory
+\inlsh{\$NEKTUTORIAL} with $\lambda=2.5$ or copy it from the \inlsh{completed}
 directory.
 \end{tutorialtask}
 
 
 \chapter{Running the solver}
 \label{helm-running}
-Now that we have the mesh file compatible with Nektar++ and periodic
-boundary conditions,
+Now that we have the mesh file compatible with Nektar++ which will support periodic boundary conditions,
 \inlsh{Helm\_mesh.xml}, and we have completed the condition file,
 \inlsh{Helm\_conditions.xml}, we can run the solver by using the following command:
 %
@@ -475,7 +471,7 @@ the file in order to visualise the results. In order to do so, we can
 use the built-in post-processing routines within Nektar++.  In
 particular, we can use the following command
 %
-\begin{tutorialtask} In the \$NEKTUTORIAL directory convert the .xml and .chk files into a .vtu format
+\begin{tutorialtask} In the \inlsh{\$NEKTUTORIAL} directory convert the .xml and .chk files into a .vtu format
 by calling
 \tutorialcommand{\$NEK/FieldConvert
     Helm\_mesh.xml Helm\_conditions.xml Helm\_mesh.fld Helm\_mesh.vtu}
@@ -514,12 +510,13 @@ You should be now familiar with the following topics:
 \item If the solver is compiled with the MPI option, then try running the case in parallel 
 with \inlsh{mpirun -np 2}.
 \item Change the Projection Operator to DisContinuous to see the same problem running with an HDG solver.
-\item Change one of the boundary conditiosn to a Robin (Mixed) boundary condition of the form $\partial u/partial n = \alpha u + \beta$ whith $\alpha =1$ and $\beta$ determined from the exact solution. 
+\item Change one of the boundary conditiosn to a Robin (Mixed) boundary
+    condition of the form $\partial u/\partial n = \alpha u + \beta$ whith $\alpha =1$ and $\beta$ determined from the exact solution. 
 \end{enumerate}
 
 \begin{tipbox}
 To check the additional settings and parameters that can be used for
-this solver, check the folder: \textsf{\$NEK/solvers/ADRSolver/Tests/}
+this solver, check the folder: \inlsh{\$NEK/solvers/ADRSolver/Tests/}
 where you can find several tests associated to the ADR solver.
 \end{tipbox}