\documentclass[11pt]{article}

\providecommand{\abs}[1]{\lvert#1\rvert}
\providecommand{\norm}[1]{\lVert#1\rVert}

\newcommand{\R}{\mathbb{R}}
\usepackage{amsmath,amsthm,amssymb,amsbsy}

\newcommand{\K}{\mathbf{K}}
\newcommand{\M}{\mathbf{M}}
\begin{document}\title{Tools for scalable modal analysis}\author{U. Hetmaniuk and R. Lehoucq}\date{\today}\maketitle

The purpose of this note is to describe the current state of the modal analysis
codes and to provide a user's guide.

\section{The model problem}

We have chosen to study the following  modal problem.
We look for the eigenpairs $(u, \lambda) \in H^{1}_{0}(\Omega) \times \R$ such that
\begin{eqnarray*}-\Delta u & = & \lambda u \quad \mbox{ in } \Omega, \\
u & = & 0 \quad \mbox{ on } \partial \Omega.\end{eqnarray*}We can select $\Omega$ to be $[0, L_x]$, $[0, L_x] \times [0, L_y]$, or
$[0, L_x] \times [0, L_y] \times [0, L_z]$.

The problem is discretized with finite elements.
The mesh is uniform in each direction and is made of segments in 1D, 
of rectangles in 2D, and of bricks in 3D.
The shape functions are piecewise polynomials of degree 1 or 2
in each direction.

The simplicity of the problem allows us to compare the computed
eigenpairs $(\hat{u}^h, \hat{\lambda}^h)$ with the exact 
discrete modes $(u^h, \lambda^h)$ and the exact 
continuous modes $(u, \lambda)$.
To validate and verify the computation, we perform the following checks:
\begin{itemize}
\item the norms of the residuals: 
$$
\norm{ \K \mathbf{\hat{u}}^h - \M \mathbf{\hat{u}}^h \hat{\lambda}^h }_{2}
\mbox{ and }
\frac{1}{ \sqrt{\mu_{min}}} 
 \norm{ \K \mathbf{\hat{u}}^h - \M \mathbf{\hat{u}}^h \hat{\lambda}^h }_{2}
$$
where $\mu_{min}$ is the smallest eigenvalue of the mass matrix $\M$.
\item the previous norms of the residuals scaled by $\hat{\lambda}^h$,
\item the relative error between $\lambda$ and $\lambda^h$ (discretization error),
\item the relative error between $\lambda^h$ and $\hat{\lambda}^h$ (algebraic error),
\item the discretization error for the exact eigenvectors:
$\norm{ u - u^h}_{L^2(\Omega)} / \norm{u}_{L^2(\Omega)}$ and 
$\norm{ u - u^h}_{H^1(\Omega)} / \norm{u}_{H^1(\Omega)}$,
\item the principal angles between the subspace spanned by $\{ \hat{u}^h \}$
and the one spanned by  $\{ u^h \}$.
\end{itemize}

\section{The executable `driver'}
 
This executable is the driver for the different algorithms.
To run this code, we edit a control file `control.driver' and 
then type one of the following commands:
\begin{itemize}
\item in sequential: `./driver.serial',
\item in parallel:  `mpirun -np NP ./driver.mpi'.
\end{itemize}
Next, we explain how to define the control file which commands 
the simulation. 

\subsection{Input file}
\label{subsec:inputDriver}

The code will read the parameters from the file `control.driver'.
Here is an example of input file:
\begin{verbatim}3            Space dimension (1, 2, 3)
1.0 2.0 3.0  Lx Ly Lz (Dimension of brick in each direction)
10 11 12     nX nY nZ (Number of elements in each direction)
1            Case Problem (1=Q1, 2=Q2)
1            Algorithm (1 .. 15)
2            Preconditioner (0 .. 3)
1            Parameter for preconditioner
10           Number of eigenpairs requested
5            Dimension of search space
5            Number of blocks
1000         Maximum number of outer iterations for eigensolver
1e-06        Tolerance for eigensolver
1000         Maximum number of inner iterations for linear solve
1e-07        Tolerance for linear solve
1            Verbose level
\end{verbatim}
All the lines must be written in this specified order.
The flags values have the following meanings:
\begin{itemize}
\item the choice of algorithm
	\begin{enumerate}
	\item {\it Blocked} LOBPCG with Cholesky-based local eigensolver
	\setcounter{enumi}{2}
	\item LOBPCG (Knyazev's version) with Cholesky-based local eigensolver
	\setcounter{enumi}{4}
	\item ARPACK (original version)
	\item ARPACK (version with user-provided residual)
	\item Generalized Davidson (RBL \& UH version)
	\setcounter{enumi}{8}
	\item BRQMIN with Cholesky-based local eigensolver
         \setcounter{enumi}{10}
         \item {\it Blocked} DACG with Cholesky-based local eigensolver
         \setcounter{enumi}{12}
	\item {\it Blocked} Jacobi-Davidson with PCG inner solve (Notay's version)
	\setcounter{enumi}{14}
	\item {\it Blocked}  Jacobi-Davidson (JDSYM) algorithm (Geus' version)
	\end{enumerate}
\item the choice of preconditioner
	\begin{enumerate}	\setcounter{enumi}{-1}
	\item No preconditioner	\item AMG with polynomial smoother
	\item AMG with Gauss-Seidel smoother
	\item Incomplete Cholesky factorization	\end{enumerate}
\item the parameter for the preconditioner
	\begin{itemize}
	\item for AMG with polynomial smoother, the parameter is the degree of the polynomial
	\item for AMG with Gauss-Seidel, this parameter is not referenced
	\item for the incomplete Cholesky factorization, the parameter is the level of fill	\end{itemize}
\item the dimension of search space
	\begin{itemize}
	\item for LOBPCG (1), it corresponds to the block size
	\item for the LOBPCG version of Andrew Knyazev (3), it is not referenced
	\item for ARPACK (5, 6), it is NCV. Note that if this dimension is smaller than
	the number of requested eigenvalues NEV, NCV is automatically set to 2NEV. 
	\item for the Generalized Davidson (7), it corresponds to the size of one block
	\item for BRQMIN (9), it corresponds to the block size
	\item for DACG (11), it corresponds to the block size
	\item for JDPCG (13), it corresponds to the size of one block
	\item for JDSYM (15), it corresponds to the size of one block.
	\end{itemize}
\item the number of blocks kept
         \begin{itemize}
           \item for LOBPCG (1, 3), it is not referenced
           \item for ARPACK (5, 6), it is not referenced
           \item for Generalized Davidson (7), it corresponds to the number of blocks
           \item for BRQMIN (9), it is not referenced
           \item for DACG (11), it is not referenced
           \item for JDPCG (13), it corresponds to the number of blocks.
           \item for JDSYM (15), it corresponds to the number of blocks.
         \end{itemize}
\item the verbose level
	\begin{enumerate}
	\setcounter{enumi}{-1}
	\item nothing
	\item print at each outer iteration the number of converged eigenvalues
	\item in addition to `1', output the history of residuals norms at the end of	the computation
	\item in addition to `2', check some orthogonality within the algorithms
	\item in addition to `3', print all kind of information depending on the
	algorithm 
	\end{enumerate}
\end{itemize}

\subsection{Output}

Two parts of output are automatically created: one for checking the accuracy of the 
computation and one for timing and memory information.
The statistics on the CPU time and memory are tailored according to the algorithm
chosen.

When the verbose level is greater than 1, a third section is created.
It contains all the scaled norms of the residuals.
For the Davidson-like algorithms, it has also the different sizes for the search space
and for the Jacobi-Davidson algorithms, the number of inner iterations for the
linear solver.

\subsection{Comments}

\begin{itemize}
\item The {\it blocked} LOBPCG (1) corresponds to the algorithm 2.3 of the report
\cite{Arbenz:2003:CAM}.
\item BRQMIN (9) is described in section 2.2 of the report \cite{Arbenz:2003:CAM}.
\item The {\it blocked} DACG (11) generalizes the algorithm 2.2 of the report
\cite{Arbenz:2003:CAM} with a matrix $\mathbf{B}_k$ defined as
$$
\mathbf{B}_k = diag( \mathbf{H}^T_{k-1} \mathbf{G}^T_{k-1} )^{-1}
                           diag( \mathbf{H}^T_{k} \mathbf{G}^T_{k} )
$$
\item The class JDBSYM is a wrapper that encapsulates the code jdbsym-0.14 of
Roman Geus. It uses the following parameters:
        \begin{itemize}
        \item TAU = 0.0,
        \item JMAX = 2 times the number of requested eigenvalues,
        \item JMIN = the number of requested eigenvalues,
        \item BLKWISE = 0,
        \item the QMR method as a linear solver,
        \item OPTYPE = OP\_SYM,
        \item EPS\_TR = the square root of the convergence tolerance,
        \item TOLDECAY = 1.5,
        \item TAU is left as it is.
        \end{itemize}\item All the algorithms, except ARPACK (5), use as convergence criterion the test
$$
\frac{1}{ \sqrt{\mu_{min}} } 
\norm{ \K \mathbf{ \hat{u} }^h - \M \mathbf{ \hat{u} }^h \hat{\lambda}^h }_{2} 
< \varepsilon \hat{\lambda}^h
$$
where $\mu_{min}$ is the smallest eigenvalue of the mass matrix $\M$ and 
$\varepsilon$ is the tolerance provided in the control file.
Note that the following estimate holds
$$
\norm{ \mathbf{z} }_{\M^{-1}} \leq \frac{1}{ \sqrt{\mu_{min}} } \norm{ \mathbf{z} }_{2}.
$$
\item Note that no test is performed against the possible stagnation of the algorithms.
\end{itemize}

\begin{thebibliography}{99}
\bibitem{Arbenz:2003:CAM}
P. Arbenz and R. Lehoucq, 
A comparison of algorithms for modal analysis in the absence of a sparse direct method,
SNL, Technical report SAND2003-1028J.
\end{thebibliography}

\end{document}