Debian Codegraph @

packages/anasazi/doc/userGuide.tex

raw
1 \documentclass[11pt]{article}
2
3 \providecommand{\abs}[1]{\lvert#1\rvert}
4 \providecommand{\norm}[1]{\lVert#1\rVert}
5
6 \newcommand{\R}{\mathbb{R}}
7 \usepackage{amsmath,amsthm,amssymb,amsbsy}
8
9 \newcommand{\K}{\mathbf{K}}
10 \newcommand{\M}{\mathbf{M}}
11 \begin{document}\title{Tools for scalable modal analysis}\author{U. Hetmaniuk and R. Lehoucq}\date{\today}\maketitle
12
13 The purpose of this note is to describe the current state of the modal analysis
14 codes and to provide a user's guide.
15
16 \section{The model problem}
17
18 We have chosen to study the following modal problem.
19 We look for the eigenpairs $(u, \lambda) \in H^{1}_{0}(\Omega) \times \R$ such that
20 \begin{eqnarray*}-\Delta u & = & \lambda u \quad \mbox{ in } \Omega, \\
21 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
22 $[0, L_x] \times [0, L_y] \times [0, L_z]$.
23
24 The problem is discretized with finite elements.
25 The mesh is uniform in each direction and is made of segments in 1D,
26 of rectangles in 2D, and of bricks in 3D.
27 The shape functions are piecewise polynomials of degree 1 or 2
28 in each direction.
29
30 The simplicity of the problem allows us to compare the computed
31 eigenpairs $(\hat{u}^h, \hat{\lambda}^h)$ with the exact
32 discrete modes $(u^h, \lambda^h)$ and the exact
33 continuous modes $(u, \lambda)$.
34 To validate and verify the computation, we perform the following checks:
35 \begin{itemize}
36 \item the norms of the residuals:
37 $$
38 \norm{ \K \mathbf{\hat{u}}^h - \M \mathbf{\hat{u}}^h \hat{\lambda}^h }_{2}
39 \mbox{ and }
40 \frac{1}{ \sqrt{\mu_{min}}}
41 \norm{ \K \mathbf{\hat{u}}^h - \M \mathbf{\hat{u}}^h \hat{\lambda}^h }_{2}
42 $$
43 where $\mu_{min}$ is the smallest eigenvalue of the mass matrix $\M$.
44 \item the previous norms of the residuals scaled by $\hat{\lambda}^h$,
45 \item the relative error between $\lambda$ and $\lambda^h$ (discretization error),
46 \item the relative error between $\lambda^h$ and $\hat{\lambda}^h$ (algebraic error),
47 \item the discretization error for the exact eigenvectors:
48 $\norm{ u - u^h}_{L^2(\Omega)} / \norm{u}_{L^2(\Omega)}$ and
49 $\norm{ u - u^h}_{H^1(\Omega)} / \norm{u}_{H^1(\Omega)}$,
50 \item the principal angles between the subspace spanned by $\{ \hat{u}^h \}$
51 and the one spanned by $\{ u^h \}$.
52 \end{itemize}
53
54 \section{The executable `driver'}
55
56 This executable is the driver for the different algorithms.
57 To run this code, we edit a control file `control.driver' and
58 then type one of the following commands:
59 \begin{itemize}
60 \item in sequential: `./driver.serial',
61 \item in parallel: `mpirun -np NP ./driver.mpi'.
62 \end{itemize}
63 Next, we explain how to define the control file which commands
64 the simulation.
65
66 \subsection{Input file}
67 \label{subsec:inputDriver}
68
69 The code will read the parameters from the file `control.driver'.
70 Here is an example of input file:
71 \begin{verbatim}3 Space dimension (1, 2, 3)
72 1.0 2.0 3.0 Lx Ly Lz (Dimension of brick in each direction)
73 10 11 12 nX nY nZ (Number of elements in each direction)
74 1 Case Problem (1=Q1, 2=Q2)
75 1 Algorithm (1 .. 15)
76 2 Preconditioner (0 .. 3)
77 1 Parameter for preconditioner
78 10 Number of eigenpairs requested
79 5 Dimension of search space
80 5 Number of blocks
81 1000 Maximum number of outer iterations for eigensolver
82 1e-06 Tolerance for eigensolver
83 1000 Maximum number of inner iterations for linear solve
84 1e-07 Tolerance for linear solve
85 1 Verbose level
86 \end{verbatim}
87 All the lines must be written in this specified order.
88 The flags values have the following meanings:
89 \begin{itemize}
90 \item the choice of algorithm
91 \begin{enumerate}
92 \item {\it Blocked} LOBPCG with Cholesky-based local eigensolver
93 \setcounter{enumi}{2}
94 \item LOBPCG (Knyazev's version) with Cholesky-based local eigensolver
95 \setcounter{enumi}{4}
96 \item ARPACK (original version)
97 \item ARPACK (version with user-provided residual)
98 \item Generalized Davidson (RBL \& UH version)
99 \setcounter{enumi}{8}
100 \item BRQMIN with Cholesky-based local eigensolver
101 \setcounter{enumi}{10}
102 \item {\it Blocked} DACG with Cholesky-based local eigensolver
103 \setcounter{enumi}{12}
104 \item {\it Blocked} Jacobi-Davidson with PCG inner solve (Notay's version)
105 \setcounter{enumi}{14}
106 \item {\it Blocked} Jacobi-Davidson (JDSYM) algorithm (Geus' version)
107 \end{enumerate}
108 \item the choice of preconditioner
109 \begin{enumerate} \setcounter{enumi}{-1}
110 \item No preconditioner \item AMG with polynomial smoother
111 \item AMG with Gauss-Seidel smoother
112 \item Incomplete Cholesky factorization \end{enumerate}
113 \item the parameter for the preconditioner
114 \begin{itemize}
115 \item for AMG with polynomial smoother, the parameter is the degree of the polynomial
116 \item for AMG with Gauss-Seidel, this parameter is not referenced
117 \item for the incomplete Cholesky factorization, the parameter is the level of fill \end{itemize}
118 \item the dimension of search space
119 \begin{itemize}
120 \item for LOBPCG (1), it corresponds to the block size
121 \item for the LOBPCG version of Andrew Knyazev (3), it is not referenced
122 \item for ARPACK (5, 6), it is NCV. Note that if this dimension is smaller than
123 the number of requested eigenvalues NEV, NCV is automatically set to 2NEV.
124 \item for the Generalized Davidson (7), it corresponds to the size of one block
125 \item for BRQMIN (9), it corresponds to the block size
126 \item for DACG (11), it corresponds to the block size
127 \item for JDPCG (13), it corresponds to the size of one block
128 \item for JDSYM (15), it corresponds to the size of one block.
129 \end{itemize}
130 \item the number of blocks kept
131 \begin{itemize}
132 \item for LOBPCG (1, 3), it is not referenced
133 \item for ARPACK (5, 6), it is not referenced
134 \item for Generalized Davidson (7), it corresponds to the number of blocks
135 \item for BRQMIN (9), it is not referenced
136 \item for DACG (11), it is not referenced
137 \item for JDPCG (13), it corresponds to the number of blocks.
138 \item for JDSYM (15), it corresponds to the number of blocks.
139 \end{itemize}
140 \item the verbose level
141 \begin{enumerate}
142 \setcounter{enumi}{-1}
143 \item nothing
144 \item print at each outer iteration the number of converged eigenvalues
145 \item in addition to `1', output the history of residuals norms at the end of the computation
146 \item in addition to `2', check some orthogonality within the algorithms
147 \item in addition to `3', print all kind of information depending on the
148 algorithm
149 \end{enumerate}
150 \end{itemize}
151
152 \subsection{Output}
153
154 Two parts of output are automatically created: one for checking the accuracy of the
155 computation and one for timing and memory information.
156 The statistics on the CPU time and memory are tailored according to the algorithm
157 chosen.
158
159 When the verbose level is greater than 1, a third section is created.
160 It contains all the scaled norms of the residuals.
161 For the Davidson-like algorithms, it has also the different sizes for the search space
162 and for the Jacobi-Davidson algorithms, the number of inner iterations for the
163 linear solver.
164
165 \subsection{Comments}
166
167 \begin{itemize}
168 \item The {\it blocked} LOBPCG (1) corresponds to the algorithm 2.3 of the report
169 \cite{Arbenz:2003:CAM}.
170 \item BRQMIN (9) is described in section 2.2 of the report \cite{Arbenz:2003:CAM}.
171 \item The {\it blocked} DACG (11) generalizes the algorithm 2.2 of the report
172 \cite{Arbenz:2003:CAM} with a matrix $\mathbf{B}_k$ defined as
173 $$
174 \mathbf{B}_k = diag( \mathbf{H}^T_{k-1} \mathbf{G}^T_{k-1} )^{-1}
175 diag( \mathbf{H}^T_{k} \mathbf{G}^T_{k} )
176 $$
177 \item The class JDBSYM is a wrapper that encapsulates the code jdbsym-0.14 of
178 Roman Geus. It uses the following parameters:
179 \begin{itemize}
180 \item TAU = 0.0,
181 \item JMAX = 2 times the number of requested eigenvalues,
182 \item JMIN = the number of requested eigenvalues,
183 \item BLKWISE = 0,
184 \item the QMR method as a linear solver,
185 \item OPTYPE = OP\_SYM,
186 \item EPS\_TR = the square root of the convergence tolerance,
187 \item TOLDECAY = 1.5,
188 \item TAU is left as it is.
189 \end{itemize}\item All the algorithms, except ARPACK (5), use as convergence criterion the test
190 $$
191 \frac{1}{ \sqrt{\mu_{min}} }
192 \norm{ \K \mathbf{ \hat{u} }^h - \M \mathbf{ \hat{u} }^h \hat{\lambda}^h }_{2}
193 < \varepsilon \hat{\lambda}^h
194 $$
195 where $\mu_{min}$ is the smallest eigenvalue of the mass matrix $\M$ and
196 $\varepsilon$ is the tolerance provided in the control file.
197 Note that the following estimate holds
198 $$
199 \norm{ \mathbf{z} }_{\M^{-1}} \leq \frac{1}{ \sqrt{\mu_{min}} } \norm{ \mathbf{z} }_{2}.
200 $$
201 \item Note that no test is performed against the possible stagnation of the algorithms.
202 \end{itemize}
203
204 \begin{thebibliography}{99}
205 \bibitem{Arbenz:2003:CAM}
206 P. Arbenz and R. Lehoucq,
207 A comparison of algorithms for modal analysis in the absence of a sparse direct method,
208 SNL, Technical report SAND2003-1028J.
209 \end{thebibliography}
210
211 \end{document}