Debian Codegraph @

include/deal.II/lac/slepc_solver.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_slepc_solver_h
17 # define dealii_slepc_solver_h
18
19 # include <deal.II/base/config.h>
20
21 # ifdef DEAL_II_WITH_SLEPC
22
23 # include <deal.II/lac/petsc_matrix_base.h>
24 # include <deal.II/lac/slepc_spectral_transformation.h>
25 # include <deal.II/lac/solver_control.h>
26
27 # include <petscconf.h>
28 # include <petscksp.h>
29
30 # include <slepceps.h>
31
32 # include <memory>
33
34 DEAL_II_NAMESPACE_OPEN
35
36 /**
37 * Base namespace for solver classes using the SLEPc solvers which are
38 * selected based on flags passed to the eigenvalue problem solver context.
39 * Derived classes set the right flags to set the right solver.
40 *
41 * The SLEPc solvers are intended to be used for solving the generalized
42 * eigenspectrum problem $(A-\lambda B)x=0$, for $x\neq0$; where $A$ is a
43 * system matrix, $B$ is a @ref GlossMassMatrix "mass matrix", and $\lambda, x$ are a set of
44 * eigenvalues and eigenvectors respectively. The emphasis is on methods and
45 * techniques appropriate for problems in which the associated matrices are
46 * sparse. Most of the methods offered by the SLEPc library are projection
47 * methods or other methods with similar properties; and wrappers are provided
48 * to interface to SLEPc solvers that handle both of these problem sets.
49 *
50 * SLEPcWrappers can be implemented in application codes in the following way:
51 * @code
52 * SolverControl solver_control (1000, 1e-9);
53 * SolverArnoldi system (solver_control, mpi_communicator);
54 * system.solve (A, B, lambda, x, size_of_spectrum);
55 * @endcode
56 * for the generalized eigenvalue problem $Ax=B\lambda x$, where the variable
57 * <code>const unsigned int size_of_spectrum</code> tells SLEPc the number of
58 * eigenvector/eigenvalue pairs to solve for. Additional options and solver
59 * parameters can be passed to the SLEPc solvers before calling
60 * <code>solve()</code>. For example, if the matrices of the general
61 * eigenspectrum problem are not hermitian and the lower eigenvalues are
62 * wanted only, the following code can be implemented before calling
63 * <code>solve()</code>:
64 * @code
65 * system.set_problem_type (EPS_NHEP);
66 * system.set_which_eigenpairs (EPS_SMALLEST_REAL);
67 * @endcode
68 * These options can also be set at the command line.
69 *
70 * See also <code>step-36</code> for a hands-on example.
71 *
72 * For cases when spectral transformations are used in conjunction with
73 * Krylov-type solvers or Davidson-type eigensolvers are employed one can
74 * additionally specify which linear solver and preconditioner to use. This
75 * can be achieved as follows
76 * @code
77 * PETScWrappers::PreconditionBoomerAMG::AdditionalData data;
78 * data.symmetric_operator = true;
79 * PETScWrappers::PreconditionBoomerAMG preconditioner(mpi_communicator, data);
80 * SolverControl linear_solver_control (dof_handler.n_dofs(),
81 * 1e-12, false, false);
82 * PETScWrappers::SolverCG linear_solver(linear_solver_control,
83 * mpi_communicator);
84 * linear_solver.initialize(preconditioner);
85 * SolverControl solver_control (100, 1e-9,false,false);
86 * SLEPcWrappers::SolverKrylovSchur eigensolver(solver_control,
87 * mpi_communicator);
88 * SLEPcWrappers::TransformationShift spectral_transformation(mpi_communicator);
89 * spectral_transformation.set_solver(linear_solver);
90 * eigensolver.set_transformation(spectral_transformation);
91 * eigensolver.solve(stiffness_matrix, mass_matrix,
92 * eigenvalues, eigenfunctions, eigenfunctions.size());
93 * @endcode
94 *
95 * In order to support this usage case, different from PETSc wrappers, the
96 * classes in this namespace are written in such a way that the underlying
97 * SLEPc objects are initialized in constructors. By doing so one also avoid
98 * caching of different settings (such as target eigenvalue or type of the
99 * problem); instead those are applied straight away when the corresponding
100 * functions of the wrapper classes are called.
101 *
102 * An alternative implementation to the one above is to use the API internals
103 * directly within the application code. In this way the calling sequence
104 * requires calling several of SolverBase functions rather than just one. This
105 * freedom is intended for use of the SLEPcWrappers that require a greater
106 * handle on the eigenvalue problem solver context. See also the API of, for
107 * example:
108 * @code
109 * template <typename OutputVector>
110 * void
111 * SolverBase::solve (const PETScWrappers::MatrixBase &A,
112 * const PETScWrappers::MatrixBase &B,
113 * std::vector<PetscScalar> &eigenvalues,
114 * std::vector<OutputVector> &eigenvectors,
115 * const unsigned int n_eigenpairs)
116 * {
117 * ...
118 * }
119 * @endcode
120 * as an example on how to do this.
121 *
122 * For further information and explanations on handling the
123 * @ref SLEPcWrappers "SLEPcWrappers",
124 * see also the
125 * @ref PETScWrappers "PETScWrappers",
126 * on which they depend.
127 *
128 * @ingroup SLEPcWrappers
129 */
130 namespace SLEPcWrappers
131 {
132 /**
133 * Base class for solver classes using the SLEPc solvers. Since solvers in
134 * SLEPc are selected based on flags passed to a generic solver object,
135 * basically all the actual solver calls happen in this class, and derived
136 * classes simply set the right flags to select one solver or another, or to
137 * set certain parameters for individual solvers.
138 *
139 * For examples of how this and its derived classes can be used, including
140 * how to provide preconditioners to the matrix of which eigenvalues are
141 * to be computed, see the documentation of the SolverBase class as well
142 * as the extensive discussions in the documentation of the SLEPcWrappers
143 * namespace.
144 */
145 class SolverBase
146 {
147 public:
148 /**
149 * Constructor. Takes the MPI communicator over which parallel
150 * computations are to happen.
151 */
152 SolverBase(SolverControl &cn, const MPI_Comm mpi_communicator);
153
154 /**
155 * Destructor.
156 */
157 virtual ~SolverBase();
158
159 /**
160 * Composite method that solves the eigensystem $Ax=\lambda x$. The
161 * eigenvector sent in has to have at least one element that we can use as
162 * a template when resizing, since we do not know the parameters of the
163 * specific vector class used (i.e. local_dofs for MPI vectors). However,
164 * while copying eigenvectors, at least twice the memory size of
165 * <tt>eigenvectors</tt> is being used (and can be more). To avoid doing
166 * this, the fairly standard calling sequence executed here is used: Set
167 * up matrices for solving; Actually solve the system; Gather the
168 * solution(s).
169 *
170 * @note Note that the number of converged eigenvectors can be larger than
171 * the number of eigenvectors requested; this is due to a round off error
172 * (success) of the eigenproblem solver context. If this is found to be
173 * the case we simply do not bother with more eigenpairs than requested,
174 * but handle that it may be more than specified by ignoring any extras.
175 * By default one eigenvector/eigenvalue pair is computed.
176 */
177 template <typename OutputVector>
178 void
179 solve(const PETScWrappers::MatrixBase &A,
180 std::vector<PetscScalar> &eigenvalues,
181 std::vector<OutputVector> &eigenvectors,
182 const unsigned int n_eigenpairs = 1);
183
184 /**
185 * Same as above, but here a composite method for solving the system $A
186 * x=\lambda B x$, for real matrices, vectors, and values $A, B, x,
187 * \lambda$.
188 */
189 template <typename OutputVector>
190 void
191 solve(const PETScWrappers::MatrixBase &A,
192 const PETScWrappers::MatrixBase &B,
193 std::vector<PetscScalar> &eigenvalues,
194 std::vector<OutputVector> &eigenvectors,
195 const unsigned int n_eigenpairs = 1);
196
197 /**
198 * Same as above, but here a composite method for solving the system $A
199 * x=\lambda B x$ with real matrices $A, B$ and imaginary eigenpairs $x,
200 * \lambda$.
201 */
202 template <typename OutputVector>
203 void
204 solve(const PETScWrappers::MatrixBase &A,
205 const PETScWrappers::MatrixBase &B,
206 std::vector<double> &real_eigenvalues,
207 std::vector<double> &imag_eigenvalues,
208 std::vector<OutputVector> &real_eigenvectors,
209 std::vector<OutputVector> &imag_eigenvectors,
210 const unsigned int n_eigenpairs = 1);
211
212 /**
213 * Set the initial vector space for the solver.
214 *
215 * By default, SLEPc initializes the starting vector or the initial
216 * subspace randomly.
217 */
218 template <typename Vector>
219 void
220 set_initial_space(const std::vector<Vector> &initial_space);
221
222 /**
223 * Set the spectral transformation to be used.
224 */
225 void
226 set_transformation(SLEPcWrappers::TransformationBase &this_transformation);
227
228 /**
229 * Set target eigenvalues in the spectrum to be computed. By default, no
230 * target is set.
231 */
232 void
233 set_target_eigenvalue(const PetscScalar &this_target);
234
235 /**
236 * Indicate which part of the spectrum is to be computed. By default
237 * largest magnitude eigenvalues are computed.
238 *
239 * @note For other allowed values see the SLEPc documentation.
240 */
241 void
242 set_which_eigenpairs(EPSWhich set_which);
243
244 /**
245 * Specify the type of the eigenspectrum problem. This can be used to
246 * exploit known symmetries of the matrices that make up the
247 * standard/generalized eigenspectrum problem. By default a non-Hermitian
248 * problem is assumed.
249 *
250 * @note For other allowed values see the SLEPc documentation.
251 */
252 void
253 set_problem_type(EPSProblemType set_problem);
254
255 /**
256 * Take the information provided from SLEPc and checks it against
257 * deal.II's own SolverControl objects to see if convergence has been
258 * reached.
259 */
260 void
261 get_solver_state(const SolverControl::State state);
262
263 /**
264 * Exception. Standard exception.
265 */
266 DeclException0(ExcSLEPcWrappersUsageError);
267
268 /**
269 * Exception. SLEPc error with error number.
270 */
271 DeclException1(ExcSLEPcError,
272 int,
273 << " An error with error number " << arg1
274 << " occurred while calling a SLEPc function");
275
276 /**
277 * Exception. Convergence failure on the number of eigenvectors.
278 */
279 DeclException2(ExcSLEPcEigenvectorConvergenceMismatchError,
280 int,
281 int,
282 << " The number of converged eigenvectors is " << arg1
283 << " but " << arg2 << " were requested. ");
284
285 /**
286 * Access to the object that controls convergence.
287 */
288 SolverControl &
289 control() const;
290
291 protected:
292 /**
293 * Reference to the object that controls convergence of the iterative
294 * solver.
295 */
296 SolverControl &solver_control;
297
298 /**
299 * Copy of the MPI communicator object to be used for the solver.
300 */
301 const MPI_Comm mpi_communicator;
302
303 /**
304 * Solve the linear system for <code>n_eigenpairs</code> eigenstates.
305 * Parameter <code>n_converged</code> contains the actual number of
306 * eigenstates that have converged; this can be both fewer or more than
307 * n_eigenpairs, depending on the SLEPc eigensolver used.
308 */
309 void
310 solve(const unsigned int n_eigenpairs, unsigned int *n_converged);
311
312 /**
313 * Access the real parts of solutions for a solved eigenvector problem,
314 * pair index solutions, $\text{index}\,\in\,0\dots
315 * \mathrm{n\_converged}-1$.
316 */
317 void
318 get_eigenpair(const unsigned int index,
319 PetscScalar &eigenvalues,
320 PETScWrappers::VectorBase &eigenvectors);
321
322 /**
323 * Access the real and imaginary parts of solutions for a solved
324 * eigenvector problem, pair index solutions, $\text{index}\,\in\,0\dots
325 * \mathrm{n\_converged}-1$.
326 */
327 void
328 get_eigenpair(const unsigned int index,
329 double &real_eigenvalues,
330 double &imag_eigenvalues,
331 PETScWrappers::VectorBase &real_eigenvectors,
332 PETScWrappers::VectorBase &imag_eigenvectors);
333
334 /**
335 * Initialize solver for the linear system $Ax=\lambda x$. (Note: this is
336 * required before calling solve ())
337 */
338 void
339 set_matrices(const PETScWrappers::MatrixBase &A);
340
341 /**
342 * Same as above, but here initialize solver for the linear system $A
343 * x=\lambda B x$.
344 */
345 void
346 set_matrices(const PETScWrappers::MatrixBase &A,
347 const PETScWrappers::MatrixBase &B);
348
349 protected:
350 /**
351 * Objects for Eigenvalue Problem Solver.
352 */
353 EPS eps;
354
355 private:
356 /**
357 * Convergence reason.
358 */
359 EPSConvergedReason reason;
360
361
362 /**
363 * A function that can be used in SLEPc as a callback to check on
364 * convergence.
365 *
366 * @note This function is not used currently.
367 */
368 static int
369 convergence_test(EPS eps,
370 PetscScalar real_eigenvalue,
371 PetscScalar imag_eigenvalue,
372 PetscReal residual_norm,
373 PetscReal *estimated_error,
374 void *solver_control);
375 };
376
377
378
379 /**
380 * An implementation of the solver interface using the SLEPc Krylov-Schur
381 * solver. Usage: All spectrum, all problem types, complex.
382 *
383 * For examples of how this and its sibling classes can be used, including
384 * how to provide preconditioners to the matrix of which eigenvalues are
385 * to be computed, see the documentation of the SolverBase class as well
386 * as the extensive discussions in the documentation of the SLEPcWrappers
387 * namespace.
388 *
389 * @ingroup SLEPcWrappers
390 */
391 class SolverKrylovSchur : public SolverBase
392 {
393 public:
394 /**
395 * Standardized data struct to pipe additional data to the solver, should
396 * it be needed.
397 */
398 struct AdditionalData
399 {};
400
401 /**
402 * SLEPc solvers will want to have an MPI communicator context over which
403 * computations are parallelized. By default, this carries the same
404 * behavior as the PETScWrappers, but you can change that.
405 */
406 explicit SolverKrylovSchur(
407 SolverControl &cn,
408 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
409 const AdditionalData &data = AdditionalData());
410
411 protected:
412 /**
413 * Store a copy of the flags for this particular solver.
414 */
415 const AdditionalData additional_data;
416 };
417
418
419
420 /**
421 * An implementation of the solver interface using the SLEPc Arnoldi solver.
422 * Usage: All spectrum, all problem types, complex.
423 *
424 * For examples of how this and its sibling classes can be used, including
425 * how to provide preconditioners to the matrix of which eigenvalues are
426 * to be computed, see the documentation of the SolverBase class as well
427 * as the extensive discussions in the documentation of the SLEPcWrappers
428 * namespace.
429 *
430 * @ingroup SLEPcWrappers
431 */
432 class SolverArnoldi : public SolverBase
433 {
434 public:
435 /**
436 * Standardized data struct to pipe additional data to the solver, should
437 * it be needed.
438 */
439 struct AdditionalData
440 {
441 /**
442 * Constructor. By default, set the option of delayed
443 * reorthogonalization to false, i.e. don't do it.
444 */
445 explicit AdditionalData(const bool delayed_reorthogonalization = false);
446
447 /**
448 * Flag for delayed reorthogonalization.
449 */
450 bool delayed_reorthogonalization;
451 };
452
453 /**
454 * SLEPc solvers will want to have an MPI communicator context over which
455 * computations are parallelized. By default, this carries the same
456 * behavior as the PETScWrappers, but you can change that.
457 */
458 explicit SolverArnoldi(SolverControl &cn,
459 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
460 const AdditionalData &data = AdditionalData());
461
462 protected:
463 /**
464 * Store a copy of the flags for this particular solver.
465 */
466 const AdditionalData additional_data;
467 };
468
469
470
471 /**
472 * An implementation of the solver interface using the SLEPc Lanczos solver.
473 * Usage: All spectrum, all problem types, complex.
474 *
475 * For examples of how this and its sibling classes can be used, including
476 * how to provide preconditioners to the matrix of which eigenvalues are
477 * to be computed, see the documentation of the SolverBase class as well
478 * as the extensive discussions in the documentation of the SLEPcWrappers
479 * namespace.
480 *
481 * @ingroup SLEPcWrappers
482 */
483 class SolverLanczos : public SolverBase
484 {
485 public:
486 /**
487 * Standardized data struct to pipe additional data to the solver, should
488 * it be needed.
489 */
490 struct AdditionalData
491 {
492 /**
493 * The type of reorthogonalization used during the Lanczos iteration.
494 */
495 EPSLanczosReorthogType reorthog;
496
497 /**
498 * Constructor. By default sets the type of reorthogonalization used
499 * during the Lanczos iteration to full.
500 */
501 explicit AdditionalData(
502 const EPSLanczosReorthogType r = EPS_LANCZOS_REORTHOG_FULL);
503 };
504
505 /**
506 * SLEPc solvers will want to have an MPI communicator context over which
507 * computations are parallelized. By default, this carries the same
508 * behavior as the PETScWrappers, but you can change that.
509 */
510 explicit SolverLanczos(SolverControl &cn,
511 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
512 const AdditionalData &data = AdditionalData());
513
514 protected:
515 /**
516 * Store a copy of the flags for this particular solver.
517 */
518 const AdditionalData additional_data;
519 };
520
521
522
523 /**
524 * An implementation of the solver interface using the SLEPc Power solver.
525 * Usage: Largest values of spectrum only, all problem types, complex.
526 *
527 * For examples of how this and its sibling classes can be used, including
528 * how to provide preconditioners to the matrix of which eigenvalues are
529 * to be computed, see the documentation of the SolverBase class as well
530 * as the extensive discussions in the documentation of the SLEPcWrappers
531 * namespace.
532 *
533 * @ingroup SLEPcWrappers
534 */
535 class SolverPower : public SolverBase
536 {
537 public:
538 /**
539 * Standardized data struct to pipe additional data to the solver, should
540 * it be needed.
541 */
542 struct AdditionalData
543 {};
544
545 /**
546 * SLEPc solvers will want to have an MPI communicator context over which
547 * computations are parallelized. By default, this carries the same
548 * behavior as the PETScWrappers, but you can change that.
549 */
550 explicit SolverPower(SolverControl &cn,
551 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
552 const AdditionalData &data = AdditionalData());
553
554 protected:
555 /**
556 * Store a copy of the flags for this particular solver.
557 */
558 const AdditionalData additional_data;
559 };
560
561
562
563 /**
564 * An implementation of the solver interface using the SLEPc Davidson
565 * solver. Usage: All problem types.
566 *
567 * For examples of how this and its sibling classes can be used, including
568 * how to provide preconditioners to the matrix of which eigenvalues are
569 * to be computed, see the documentation of the SolverBase class as well
570 * as the extensive discussions in the documentation of the SLEPcWrappers
571 * namespace.
572 *
573 * @ingroup SLEPcWrappers
574 */
575 class SolverGeneralizedDavidson : public SolverBase
576 {
577 public:
578 /**
579 * Standardized data struct to pipe additional data to the solver, should
580 * it be needed.
581 */
582 struct AdditionalData
583 {
584 /**
585 * Use double expansion in search subspace.
586 */
587 bool double_expansion;
588
589 /**
590 * Constructor. By default set double_expansion to false.
591 */
592 explicit AdditionalData(bool double_expansion = false);
593 };
594
595 /**
596 * SLEPc solvers will want to have an MPI communicator context over which
597 * computations are parallelized. By default, this carries the same
598 * behavior as the PETScWrappers, but you can change that.
599 */
600 explicit SolverGeneralizedDavidson(
601 SolverControl &cn,
602 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
603 const AdditionalData &data = AdditionalData());
604
605 protected:
606 /**
607 * Store a copy of the flags for this particular solver.
608 */
609 const AdditionalData additional_data;
610 };
611
612
613
614 /**
615 * An implementation of the solver interface using the SLEPc Jacobi-Davidson
616 * solver. Usage: All problem types.
617 *
618 * For examples of how this and its sibling classes can be used, including
619 * how to provide preconditioners to the matrix of which eigenvalues are
620 * to be computed, see the documentation of the SolverBase class as well
621 * as the extensive discussions in the documentation of the SLEPcWrappers
622 * namespace.
623 *
624 * @ingroup SLEPcWrappers
625 */
626 class SolverJacobiDavidson : public SolverBase
627 {
628 public:
629 /**
630 * Standardized data struct to pipe additional data to the solver, should
631 * it be needed.
632 */
633 struct AdditionalData
634 {};
635
636 /**
637 * SLEPc solvers will want to have an MPI communicator context over which
638 * computations are parallelized. By default, this carries the same
639 * behavior as the PETScWrappers, but you can change that.
640 */
641 explicit SolverJacobiDavidson(
642 SolverControl &cn,
643 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
644 const AdditionalData &data = AdditionalData());
645
646 protected:
647 /**
648 * Store a copy of the flags for this particular solver.
649 */
650 const AdditionalData additional_data;
651 };
652
653
654
655 /**
656 * An implementation of the solver interface using the SLEPc LAPACK direct
657 * solver.
658 *
659 * For examples of how this and its sibling classes can be used, including
660 * how to provide preconditioners to the matrix of which eigenvalues are
661 * to be computed, see the documentation of the SolverBase class as well
662 * as the extensive discussions in the documentation of the SLEPcWrappers
663 * namespace.
664 *
665 * @ingroup SLEPcWrappers
666 */
667 class SolverLAPACK : public SolverBase
668 {
669 public:
670 /**
671 * Standardized data struct to pipe additional data to the solver, should
672 * it be needed.
673 */
674 struct AdditionalData
675 {};
676
677 /**
678 * SLEPc solvers will want to have an MPI communicator context over which
679 * computations are parallelized. By default, this carries the same
680 * behavior as the PETScWrappers, but you can change that.
681 */
682 explicit SolverLAPACK(SolverControl &cn,
683 const MPI_Comm mpi_communicator = PETSC_COMM_SELF,
684 const AdditionalData &data = AdditionalData());
685
686 protected:
687 /**
688 * Store a copy of the flags for this particular solver.
689 */
690 const AdditionalData additional_data;
691 };
692
693
694
695 // --------------------------- inline and template functions -----------
696 /**
697 * This is declared here to make it possible to take a std::vector of
698 * different PETScWrappers vector types
699 */
700 // todo: The logic of these functions can be simplified without breaking
701 // backward compatibility...
702
703 template <typename OutputVector>
704 void
705 SolverBase::solve(const PETScWrappers::MatrixBase &A,
706 std::vector<PetscScalar> &eigenvalues,
707 std::vector<OutputVector> &eigenvectors,
708 const unsigned int n_eigenpairs)
709 {
710 // Panic if the number of eigenpairs wanted is out of bounds.
711 AssertThrow((n_eigenpairs > 0) && (n_eigenpairs <= A.m()),
712 ExcSLEPcWrappersUsageError());
713
714 // Set the matrices of the problem
715 set_matrices(A);
716
717 // and solve
718 unsigned int n_converged = 0;
719 solve(n_eigenpairs, &n_converged);
720
721 if (n_converged > n_eigenpairs)
722 n_converged = n_eigenpairs;
723 AssertThrow(n_converged == n_eigenpairs,
724 ExcSLEPcEigenvectorConvergenceMismatchError(n_converged,
725 n_eigenpairs));
726
727 AssertThrow(eigenvectors.size() != 0, ExcSLEPcWrappersUsageError());
728 eigenvectors.resize(n_converged, eigenvectors.front());
729 eigenvalues.resize(n_converged);
730
731 for (unsigned int index = 0; index < n_converged; ++index)
732 get_eigenpair(index, eigenvalues[index], eigenvectors[index]);
733 }
734
735 template <typename OutputVector>
736 void
737 SolverBase::solve(const PETScWrappers::MatrixBase &A,
738 const PETScWrappers::MatrixBase &B,
739 std::vector<PetscScalar> &eigenvalues,
740 std::vector<OutputVector> &eigenvectors,
741 const unsigned int n_eigenpairs)
742 {
743 // Guard against incompatible matrix sizes:
744 AssertThrow(A.m() == B.m(), ExcDimensionMismatch(A.m(), B.m()));
745 AssertThrow(A.n() == B.n(), ExcDimensionMismatch(A.n(), B.n()));
746
747 // Panic if the number of eigenpairs wanted is out of bounds.
748 AssertThrow((n_eigenpairs > 0) && (n_eigenpairs <= A.m()),
749 ExcSLEPcWrappersUsageError());
750
751 // Set the matrices of the problem
752 set_matrices(A, B);
753
754 // and solve
755 unsigned int n_converged = 0;
756 solve(n_eigenpairs, &n_converged);
757
758 if (n_converged >= n_eigenpairs)
759 n_converged = n_eigenpairs;
760
761 AssertThrow(n_converged == n_eigenpairs,
762 ExcSLEPcEigenvectorConvergenceMismatchError(n_converged,
763 n_eigenpairs));
764 AssertThrow(eigenvectors.size() != 0, ExcSLEPcWrappersUsageError());
765
766 eigenvectors.resize(n_converged, eigenvectors.front());
767 eigenvalues.resize(n_converged);
768
769 for (unsigned int index = 0; index < n_converged; ++index)
770 get_eigenpair(index, eigenvalues[index], eigenvectors[index]);
771 }
772
773 template <typename OutputVector>
774 void
775 SolverBase::solve(const PETScWrappers::MatrixBase &A,
776 const PETScWrappers::MatrixBase &B,
777 std::vector<double> &real_eigenvalues,
778 std::vector<double> &imag_eigenvalues,
779 std::vector<OutputVector> &real_eigenvectors,
780 std::vector<OutputVector> &imag_eigenvectors,
781 const unsigned int n_eigenpairs)
782 {
783 // Guard against incompatible matrix sizes:
784 AssertThrow(A.m() == B.m(), ExcDimensionMismatch(A.m(), B.m()));
785 AssertThrow(A.n() == B.n(), ExcDimensionMismatch(A.n(), B.n()));
786
787 // and incompatible eigenvalue/eigenvector sizes
788 AssertThrow(real_eigenvalues.size() == imag_eigenvalues.size(),
789 ExcDimensionMismatch(real_eigenvalues.size(),
790 imag_eigenvalues.size()));
791 AssertThrow(real_eigenvectors.size() == imag_eigenvectors.size(),
792 ExcDimensionMismatch(real_eigenvectors.size(),
793 imag_eigenvectors.size()));
794
795 // Panic if the number of eigenpairs wanted is out of bounds.
796 AssertThrow((n_eigenpairs > 0) && (n_eigenpairs <= A.m()),
797 ExcSLEPcWrappersUsageError());
798
799 // Set the matrices of the problem
800 set_matrices(A, B);
801
802 // and solve
803 unsigned int n_converged = 0;
804 solve(n_eigenpairs, &n_converged);
805
806 if (n_converged >= n_eigenpairs)
807 n_converged = n_eigenpairs;
808
809 AssertThrow(n_converged == n_eigenpairs,
810 ExcSLEPcEigenvectorConvergenceMismatchError(n_converged,
811 n_eigenpairs));
812 AssertThrow((real_eigenvectors.size() != 0) &&
813 (imag_eigenvectors.size() != 0),
814 ExcSLEPcWrappersUsageError());
815
816 real_eigenvectors.resize(n_converged, real_eigenvectors.front());
817 imag_eigenvectors.resize(n_converged, imag_eigenvectors.front());
818 real_eigenvalues.resize(n_converged);
819 imag_eigenvalues.resize(n_converged);
820
821 for (unsigned int index = 0; index < n_converged; ++index)
822 get_eigenpair(index,
823 real_eigenvalues[index],
824 imag_eigenvalues[index],
825 real_eigenvectors[index],
826 imag_eigenvectors[index]);
827 }
828
829 template <typename VectorType>
830 void
831 SolverBase::set_initial_space(
832 const std::vector<VectorType> &this_initial_space)
833 {
834 std::vector<Vec> vecs(this_initial_space.size());
835
836 for (unsigned int i = 0; i < this_initial_space.size(); ++i)
837 {
838 Assert(this_initial_space[i].l2_norm() > 0.0,
839 ExcMessage("Initial vectors should be nonzero."));
840 vecs[i] = this_initial_space[i];
841 }
842
843 // if the eigensolver supports only a single initial vector, but several
844 // guesses are provided, then all except the first one will be discarded.
845 // One could still build a vector that is rich in the directions of all
846 // guesses, by taking a linear combination of them. (TODO: make function
847 // virtual?)
848
849 const PetscErrorCode ierr =
850 EPSSetInitialSpace(eps, vecs.size(), vecs.data());
851 AssertThrow(ierr == 0, ExcSLEPcError(ierr));
852 }
853
854 } // namespace SLEPcWrappers
855
856 DEAL_II_NAMESPACE_CLOSE
857
858 # else
859
860 // Make sure the scripts that create the C++20 module input files have
861 // something to latch on if the preprocessor #ifdef above would
862 // otherwise lead to an empty content of the file.
863 DEAL_II_NAMESPACE_OPEN
864 DEAL_II_NAMESPACE_CLOSE
865
866 # endif // DEAL_II_WITH_SLEPC
867
868 /*---------------------------- slepc_solver.h ---------------------------*/
869
870 #endif
871
872 /*---------------------------- slepc_solver.h ---------------------------*/