Line data Source code
1 : // The libMesh Finite Element Library.
2 : // Copyright (C) 2002-2025 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
3 :
4 : // This library is free software; you can redistribute it and/or
5 : // modify it under the terms of the GNU Lesser General Public
6 : // License as published by the Free Software Foundation; either
7 : // version 2.1 of the License, or (at your option) any later version.
8 :
9 : // This library is distributed in the hope that it will be useful,
10 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 : // Lesser General Public License for more details.
13 :
14 : // You should have received a copy of the GNU Lesser General Public
15 : // License along with this library; if not, write to the Free Software
16 : // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 :
18 :
19 :
20 : #ifndef LIBMESH_EIGEN_SOLVER_H
21 : #define LIBMESH_EIGEN_SOLVER_H
22 :
23 :
24 : #include "libmesh/libmesh_config.h"
25 : #ifdef LIBMESH_HAVE_SLEPC
26 :
27 : // Local includes
28 : #include "libmesh/libmesh_common.h"
29 : #include "libmesh/reference_counted_object.h"
30 : #include "libmesh/libmesh.h"
31 : #include "libmesh/parallel_object.h"
32 : #include "libmesh/enum_solver_package.h" // SLEPC_SOLVERS
33 :
34 : // C++ includes
35 : #include <memory>
36 :
37 : namespace libMesh
38 : {
39 :
40 : // forward declarations
41 : template <typename T> class SparseMatrix;
42 : template <typename T> class ShellMatrix;
43 : template <typename T> class NumericVector;
44 : class SolverConfiguration;
45 : enum EigenSolverType : int;
46 : enum EigenProblemType : int;
47 : enum PositionOfSpectrum : int;
48 :
49 : /**
50 : * This class provides an interface to solvers for eigenvalue
51 : * problems.
52 : *
53 : * \author Steffen Peterson
54 : * \date 2005
55 : * \brief Base class which defines the interface for solving eigenproblems.
56 : */
57 : template <typename T>
58 16 : class EigenSolver : public ReferenceCountedObject<EigenSolver<T>>,
59 : public ParallelObject
60 : {
61 : public:
62 :
63 : /**
64 : * Constructor. Initializes Solver data structures
65 : */
66 : EigenSolver (const Parallel::Communicator & comm_in);
67 :
68 : /**
69 : * Destructor.
70 : */
71 : virtual ~EigenSolver ();
72 :
73 : /**
74 : * Builds an \p EigenSolver using the linear solver package specified by
75 : * \p solver_package
76 : */
77 : static std::unique_ptr<EigenSolver<T>> build(const Parallel::Communicator & comm_in,
78 : const SolverPackage solver_package = SLEPC_SOLVERS);
79 :
80 : /**
81 : * \returns \p true if the data structures are
82 : * initialized, false otherwise.
83 : */
84 1042 : bool initialized () const { return _is_initialized; }
85 :
86 : /**
87 : * \returns \p The value of the flag which controls whether libmesh
88 : * closes the eigenproblem matrices before solving. \p true by
89 : * default.
90 : */
91 0 : bool get_close_matrix_before_solve() const
92 : {
93 : libmesh_experimental();
94 0 : return _close_matrix_before_solve;
95 : }
96 :
97 : /**
98 : * Set the flag which controls whether libmesh closes the
99 : * eigenproblem matrices before solving.
100 : */
101 0 : void set_close_matrix_before_solve(bool val)
102 : {
103 : libmesh_experimental();
104 0 : _close_matrix_before_solve = val;
105 0 : }
106 :
107 : /**
108 : * Release all memory and clear data structures.
109 : */
110 0 : virtual void clear () {}
111 :
112 : /**
113 : * Initialize data structures if not done so already.
114 : */
115 : virtual void init () = 0;
116 :
117 : /**
118 : * \returns The type of eigensolver to use.
119 : */
120 0 : EigenSolverType eigen_solver_type () const { return _eigen_solver_type; }
121 :
122 : /**
123 : * \returns The type of the eigen problem.
124 : */
125 0 : EigenProblemType eigen_problem_type () const { return _eigen_problem_type;}
126 :
127 : /**
128 : * \returns The position of the spectrum to compute.
129 : */
130 0 : PositionOfSpectrum position_of_spectrum () const
131 0 : { return _position_of_spectrum;}
132 :
133 : /**
134 : * Sets the type of eigensolver to use.
135 : */
136 0 : void set_eigensolver_type (const EigenSolverType est)
137 0 : { _eigen_solver_type = est; }
138 :
139 : /**
140 : * Sets the type of the eigenproblem.
141 : */
142 6 : void set_eigenproblem_type ( EigenProblemType ept)
143 278 : {_eigen_problem_type = ept;}
144 :
145 : /**
146 : * Sets the position of the spectrum.
147 : */
148 0 : void set_position_of_spectrum (PositionOfSpectrum pos)
149 13 : {_position_of_spectrum= pos;}
150 :
151 : void set_position_of_spectrum (Real pos);
152 : void set_position_of_spectrum (Real pos, PositionOfSpectrum target);
153 :
154 : /**
155 : * Solves the standard eigenproblem involving the SparseMatrix \p matrix_A.
156 : *
157 : * \returns The number of converged eigenpairs and the number of
158 : * iterations.
159 : */
160 : virtual std::pair<unsigned int, unsigned int> solve_standard (SparseMatrix<T> & matrix_A,
161 : int nev,
162 : int ncv,
163 : const double tol,
164 : const unsigned int m_its) = 0;
165 :
166 : /**
167 : * Solves the standard eigenproblem involving the ShellMatrix \p matrix_A.
168 : *
169 : * \returns The number of converged eigenpairs and the number of
170 : * iterations.
171 : */
172 : virtual std::pair<unsigned int, unsigned int> solve_standard (ShellMatrix<T> & matrix_A,
173 : int nev,
174 : int ncv,
175 : const double tol,
176 : const unsigned int m_its) = 0;
177 :
178 : /**
179 : * Solves the standard eigenproblem involving the ShellMatrix \p matrix_A and
180 : * the preconditioning matrix \p precond.
181 : *
182 : * \returns The number of converged eigenpairs and the number of
183 : * iterations.
184 : */
185 : virtual std::pair<unsigned int, unsigned int> solve_standard (ShellMatrix<T> & matrix_A,
186 : SparseMatrix<T> & precond,
187 : int nev,
188 : int ncv,
189 : const double tol,
190 : const unsigned int m_its) = 0;
191 :
192 : /**
193 : * Solves the standard eigenproblem involving the ShellMatrix \p matrix_A and
194 : * the shell preconditioning matrix \p precond.
195 : *
196 : * \returns The number of converged eigenpairs and the number of
197 : * iterations.
198 : */
199 : virtual std::pair<unsigned int, unsigned int> solve_standard (ShellMatrix<T> & matrix_A,
200 : ShellMatrix<T> & precond,
201 : int nev,
202 : int ncv,
203 : const double tol,
204 : const unsigned int m_its) = 0;
205 :
206 : /**
207 : * Solves the generalized eigenproblem involving SparseMatrices \p matrix_A
208 : * and \p matrix_B.
209 : *
210 : * \returns The number of converged eigenpairs and the number of
211 : * iterations.
212 : */
213 : virtual std::pair<unsigned int, unsigned int> solve_generalized (SparseMatrix<T> & matrix_A,
214 : SparseMatrix<T> & matrix_B,
215 : int nev,
216 : int ncv,
217 : const double tol,
218 : const unsigned int m_its) = 0;
219 :
220 : /**
221 : * Solves the generalized eigenproblem with ShellMatrix \p matrix_A
222 : * and SparseMatrix \p matrix_B.
223 : *
224 : * \returns The number of converged eigenpairs and the number of
225 : * iterations.
226 : */
227 : virtual std::pair<unsigned int, unsigned int> solve_generalized (ShellMatrix<T> & matrix_A,
228 : SparseMatrix<T> & matrix_B,
229 : int nev,
230 : int ncv,
231 : const double tol,
232 : const unsigned int m_its) = 0;
233 :
234 : /**
235 : * Solves the generalized eigenproblem with SparseMatrix \p matrix_A
236 : * and ShellMatrix \p matrix_B.
237 : *
238 : * \returns The number of converged eigenpairs and the number of
239 : * iterations.
240 : */
241 : virtual std::pair<unsigned int, unsigned int> solve_generalized (SparseMatrix<T> & matrix_A,
242 : ShellMatrix<T> & matrix_B,
243 : int nev,
244 : int ncv,
245 : const double tol,
246 : const unsigned int m_its) = 0;
247 :
248 : /**
249 : * Solves the generalized eigenproblem involving ShellMatrices \p
250 : * matrix_A and \p matrix_B.
251 : *
252 : * \returns The number of converged eigenpairs and the number of
253 : * iterations.
254 : */
255 : virtual std::pair<unsigned int, unsigned int> solve_generalized (ShellMatrix<T> & matrix_A,
256 : ShellMatrix<T> & matrix_B,
257 : int nev,
258 : int ncv,
259 : const double tol,
260 : const unsigned int m_its) = 0;
261 :
262 : /**
263 : * Solves the generalized eigenproblem involving ShellMatrices \p
264 : * matrix_A, \p matrix_B and the SparseMatrix precond.
265 : *
266 : * \returns The number of converged eigenpairs and the number of
267 : * iterations.
268 : */
269 : virtual std::pair<unsigned int, unsigned int> solve_generalized (ShellMatrix<T> & matrix_A,
270 : ShellMatrix<T> & matrix_B,
271 : SparseMatrix<T> & precond,
272 : int nev,
273 : int ncv,
274 : const double tol,
275 : const unsigned int m_its) = 0;
276 :
277 : /**
278 : * Solves the generalized eigenproblem involving ShellMatrices \p
279 : * matrix_A, \p matrix_B and the shell preconditioning matrix.
280 : *
281 : * \returns The number of converged eigenpairs and the number of
282 : * iterations.
283 : */
284 : virtual std::pair<unsigned int, unsigned int> solve_generalized (ShellMatrix<T> & matrix_A,
285 : ShellMatrix<T> & matrix_B,
286 : ShellMatrix<T> & precond,
287 : int nev,
288 : int ncv,
289 : const double tol,
290 : const unsigned int m_its) = 0;
291 :
292 :
293 : /**
294 : * \returns The \p ith eigenvalue (real and imaginary part),
295 : * and copies the \p ith eigenvector into the \p solution vector.
296 : */
297 : virtual std::pair<Real, Real> get_eigenpair (dof_id_type i,
298 : NumericVector<T> & solution) = 0;
299 :
300 : /**
301 : * \returns The \p ith eigenvalue (real and imaginary part).
302 : *
303 : * Same as above function, except it does not copy the eigenvector.
304 : */
305 : virtual std::pair<Real, Real> get_eigenvalue (dof_id_type i) = 0;
306 :
307 : /**
308 : * Attach a deflation space defined by a single vector.
309 : */
310 : virtual void attach_deflation_space(NumericVector<T> & deflation_vector) = 0;
311 :
312 : /**
313 : * Provide one basis vector for the initial guess
314 : */
315 : virtual void set_initial_space(NumericVector<T> & initial_space_in) = 0;
316 :
317 : /**
318 : * Set the solver configuration object.
319 : */
320 : void set_solver_configuration(SolverConfiguration & solver_configuration);
321 :
322 : protected:
323 :
324 : /**
325 : * Enum stating which type of eigensolver to use.
326 : */
327 : EigenSolverType _eigen_solver_type;
328 :
329 : /**
330 : * Enum stating which type of eigen problem we deal with.
331 : */
332 : EigenProblemType _eigen_problem_type;
333 :
334 : /**
335 : * Enum stating where to evaluate the spectrum.
336 : */
337 : PositionOfSpectrum _position_of_spectrum;
338 :
339 : /**
340 : * Flag indicating if the data structures have been initialized.
341 : */
342 : bool _is_initialized;
343 :
344 : /**
345 : * Optionally store a SolverOptions object that can be used
346 : * to set parameters like solver type, tolerances and iteration limits.
347 : */
348 : SolverConfiguration * _solver_configuration;
349 :
350 : Real _target_val;
351 :
352 : bool _close_matrix_before_solve;
353 : };
354 :
355 : } // namespace libMesh
356 :
357 : #endif // LIBMESH_HAVE_SLEPC
358 :
359 : #endif // LIBMESH_EIGEN_SOLVER_H
|
