\documentclass[11pt]{book}
\usepackage{makeidx,amstext,amsfonts,amssymb,amsbsy,subeqn,array,epic,eepic,times}

\newcommand{\bfn}{{\boldsymbol n}}
\newcommand{\norm}[2]{\left\|#1\right\|_{#2}}
\newcommand{\bfmK}{\mathbf{K}}
%\renewcommand{\rmdefault}{ppl}
\makeindex



\begin{document}
\title{\bf FEMLAB users manual} 
\author{Peter Hansbo \& M\aa rten Levenstam\\[4mm] \it
  Department of Mathematics, Chalmers University of Technology,\\ \it
  S-412 96 G\"{o}teborg, Sweden} 
\date{}
\maketitle
\tableofcontents

\chapter{Problem types solved by FEMLAB}

Our goal is to implement adaptive solvers for a wide variety
of partial differential equations. To start with, we
have implemented a solver for
two-dimensional convection-diffusion
problems of the type
\[\begin{array}{>{\displaystyle}r>{\displaystyle}c>{\displaystyle}l>{\displaystyle}l}
-\nabla\cdot\left(\bfmK\,\nabla u\right) + \beta\cdot\nabla u + \alpha\, u & 
= & f & \text{in}~\Omega ,\\[4mm]
\bfn\cdot\bfmK\,\nabla u + \gamma\, u & = & g & \text{on}~\Gamma_{\text{N}}, \\[4mm]
 u & = & h & \text{on}~\Gamma_{\text{D}}, \end{array}
\]
where $\bfmK$ is a symmetric, positive definite, $2\times 2$-matrix
containing material coefficients,  
$\alpha$ is an absorption coefficient,
$\beta$ is a convective velocity, and $\gamma$ is a heat transfer
coefficient. All of these coefficients may be variable.
Furthermore, $\bfn$ is the outward pointing unit normal to the boundary, 
$\Gamma_{\text{D}}$ is the Dirichlet part of the boundary where
the solution is prescribed, and $\Gamma_{\text{N}}$  is the Neumann part of the
boundary where the normal flux is prescribed (we also allow for Robin boundary conditions, where the normal flux depends on the solution, also known as
{\em convective} boundary conditions).
This problem is solved with $h$-adaptivity using root-mean-square ($L_2$), 
maximum ($L_{\infty}$),
or energy norm control of the error.
Thus, the program aims at producing solutions where
\[
\| u-u^h\|\leq \text{TOL}\,\norm{u}{},
\]
where TOL is a tolerance given by the user, and $\norm{\cdot}{}$ is the 
chosen norm.
In order to avoid too many degrees of freedom, we require the user to also
supply the maximum number of refinement 
levels, where the initial mesh represents level zero.


In order to have accurate control of the error in $L_2$ and $L_{\infty}$, 
an evaluation of a stability  
constant related to a continuous dual problem is
also performed according to the theory exposed in \cite{book}. 


\chapter{Interactive X-windows input and output}

In order to simplify the input of data, an X-windows based
interactive mesh generator and input data preparation module has
been implemented. It is activated by giving the command `Femlab', which
activates an X11-based data I/O window.

\section{Data input\label{in}}

The X11--window has five command buttons on the top left--hand side:
\begin{enumerate}
\item \textbf{File}
\item \textbf{Geometry}
\item \textbf{Mesh}
\item \textbf{Equations}
\item \textbf{View Result}  
\end{enumerate}
The numbered buttons on the right--hand side refers to viewing of
post--processed data, and will be discussed in Section \ref{out}
together with the `\textbf{View Result}' button.

Only highlighted command buttons are active; the dimmed buttons
will become activated when the right chain of commands
has been given.

\subsection{The `\textbf{File}' button}

Pressing the `\textbf{File}' button reveals a roll--down menu with four alternatives:
\begin{enumerate}
\item \textbf{Load\ldots}
\item \textbf{Save\ldots}
\item \textbf{Print\ldots}
\item \textbf{Print to file\ldots}
\item \textbf{Quit\ldots}
\end{enumerate}
The `\textbf{Load}'/`\textbf{Save}' commands work are tied to each 
other as follows.
At any time during the mesh generation or after solving,
the user may launch the `\textbf{Save}'--command which prompts for
a filename. Wen loading this file using `\textbf{Load}', the
program will return to exactly the state it was at `\textbf{Save}'.
This means that the user may leave the input data
unfinished and return at a later time to continue where he left off.

The `\textbf{Print}' command prints the graphics displayed on the screen
to a printer (using the PostScript format). A dialogue
window lets the user decide where to direct the output.

The `\textbf{Print to file}' command saves
the graphics displayed on the screen
in a file using postscript. The 

The `\textbf{Quit}' command exits the program without saving.

\subsection{The `\textbf{Geometry}' button}

Pressing the `\textbf{Geometry}' button
reveals a roll--down menu with two alternatives:
\begin{enumerate}
\item \textbf{Define scale\ldots}
\item \textbf{Define boundaries\ldots}
\end{enumerate}
Only the `\textbf{Define scale}' commands are highlighted initially.
When launching this command, a command box pops up, prompting
for the domain size. These figures will set the physical dimensions of
the input window (or a close approximation).

Once the scale has been set, another command box pops up, showing the
type
of geometrical objects that can be chosen to define the boundaries.
These are, from top to bottom,
\begin{itemize}
\item NACA wing profiles
\item Circles
\item Ellipses
\item Rectangles
\item General polygons
\end{itemize}
The following two items in the command box may be used to move points and
to delete given boundaries, respectively; the last two are used for zooming.

Use the left button to click out the boundaries. The general polygon
must be closed by clicking at the initial point. 
Use the left mouse--button to insert points. Make
a closed loop of straight segments to complete a boundary;
the direction does not matter.
To close the loop click once again at the initial point.
(NOTE: when closing the loop,
take care to position the arrow close to the initial point.
If this is not done, one more segment will be created. The
mesh generator will assume that the points given by the user
to define the boundaries are to be used as nodes, and it
cannot handle a situation where the smallest boundary segment
is substantially smaller than the local meshsize.) 

The other geometrical
figures are defined by the point at which you click (centroid for the
circle and ellipse, left upper corner for the rectangle and leading
edge for the NACA profile. Clicking again on the left mouse button
fixes the boundary of the geometrical object.

Note that you must choose type of boundary:
\begin{itemize}
\item An outer boundary is exterior to the domain.
\item An interior boundary is interior to the domain.
\item An internal boundary is embedded in the domain.
\end{itemize}
The internal boundaries may
represent for instance borders between different material types.

{\bf WARNING:} Do not place a geometrical object too close to a large
boundary segment defined by a polygon or a rectangle! The mesh
generator is forced to make the elements at least as small as the
segment size on the geometrical object. If the given meshsize is
considerably larger, problems will occur.


\subsection{The `\textbf{Mesh}' button}

Pressing the `\textbf{Mesh}' button
reveals a roll--down menu with two alternatives:
\begin{enumerate}
\item \textbf{Define mesh size\ldots}
\item \textbf{Make mesh}
\end{enumerate}

The `\textbf{Define mesh size}' command prompts for the local mesh size.
This can be given different values at different points in the domain.
Use the left mouse--button to give the location of the
mesh size currently displayed in the dialogue window.
Interpolation between different points is performed using 
Shepard's distance--weighting \cite{gordon}.

 
The `\textbf{Make mesh}' command creates a mesh using the advancing front
technique \cite{perair}. When the mesh is finished, it
will be displayed in the graphical window.

 
\subsection{The `\textbf{Solver}' button}

Pressing the `\textbf{Solver}' button
reveals a roll--down menu with two alternatives:
\begin{enumerate}
\item \textbf{Convection--diffusion equation\ldots}
\item \textbf{Equation data\ldots}
\item \textbf{Solve\ldots}
\end{enumerate}

 Launching `\textbf{Equation data}' 
 yields a dialogue window where data can be entered.
 These are the material data, the right--hand side of the equation,
 and the boundary conditions.
 To select the different data types, click in the box left of
 the respective header. The material data and right--hand side may be
 given in different formats. Clicking in the box left of the text
 describing the command, a command box prompts you to give the
data format: an analytical expression; a pointwise specification (same
as when the meshsize was given); and finally elementwise constant
data.

The analytical data are simply written in text format. The allowed
symbols are:
x,y,pi ($\pi$), sqrt(), exp(), sin(), cos(), tan(), \^ (power),
and the usual $*,+,-,/$. Analytical data are written in the rectangles
following the $=$ signs.


Data that are to be given as constants per element are fed in by
clicking on the appropriate element using the left mouse button, or by
using the right mouse button to obtain a ``rubber band rectangle'' 
covering the
domain to have constant data.

 
 When finished, click in the `\textbf{Done}' box. To delete given data,
 click in the `\textbf{Delete}' box, and to leave the dialogue box
 without saving, click in the `\textbf{Cancel}' box.


Boundary conditions must be given, choose between Dirichlet and
Neumann data. Once selected, the boundaries of the domain are shown on
the screen. Select one segment by pressing the left mouse button;
select the boundary
connected to the segment by pressing the middle button;
select the all boundaries by pressing the right. A dialogue box prompts
for numerical values.

 Launching `\textbf{Solve}' command prompts for additional data: 
 \begin{itemize}
 \item The tolerance,
 which should be given as percentage relative value,
 i.e.,
 \[
 \text{TOL} = 100\times\frac{\| u-u^h\|}{\| u\|},
 \]
\item  The maximum number of refinement levels, where level 1 is the original mesh. Higher levels denote the number of times (minus one)
that the smallest element has been subdivided.
\item  The norm to be used, energy norm (`ENE'), root-mean-square norm
(`RMS') or maximum norm (`MAX').
\end{itemize}
When these data have been provided, the solver is launched.

\section{Post processing\label{out}}


\subsection{The `\textbf{View Result}' button}

Pressing the `\textbf{View Result}' button
reveals a roll--down menu with two groups:
\begin{itemize}
\item \textbf{Zoom}
\item \textbf{Restore zoom}
\item \textbf{Setup\ldots}
\end{itemize}
and
\begin{itemize}
\item \textbf{Mesh}
\item \textbf{Concentration}
\item \textbf{Diffusive flux}
\end{itemize}

From the second group,
pick the entities you wish to view, the mesh and/or the isolines of
the solution and/or the vectors signifying the gradient of the
solution multiplied by the diffusion parameter (``heat flux'').
Then select the refinement level
you wish to view by selecting the appropriate button.
The number of levels (meshes) is reflected in the number
of highlighted buttons at the top right--hands side. 

The `\textbf{Zoom}' command
lets you zoom by placing the arrow
in the graphical window, pressing the left mouse--button
and, without releasing it, move the mouse. The domain to be
expanded is visible as an expandable rectangle in the graphical window. The command `\textbf{Restore Zoom}' returns to the original state.

The command `\textbf{Setup}' launches a dialogue window in which some
default values for the visualization can be selected.


\begin{thebibliography}{20}

\bibitem{book}K. Eriksson, D. Estep, P. Hansbo,
and C. Johnson, {\em Adaptive finite element
methods},
North--Holland, to appear.

\bibitem{gordon}
W. J. Gordon and J. A. Wixom,
`Shepard's method of ``metric interpolation'' to bivariate and multivariate
interpolation',
{{\em Math. Comp.,} \bf  32} (1978) 253--264.

\bibitem{perair}
J. Peraire, M. Vahdati, K. Morgan, and O. C.
Zienkiewicz, `Adaptive remeshing for compressible flow computations',
{\em J. Comput. Phys.,} {\bf 72} (1987) 449-466.

\end{thebibliography} 
\end{document}
