Debian Codegraph @

include/deal.II/lac/slepc_spectral_transformation.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_spectral_transformation_h
17 # define dealii_slepc_spectral_transformation_h
18
19
20 # include <deal.II/base/config.h>
21
22 # ifdef DEAL_II_WITH_SLEPC
23
24 # include <deal.II/lac/exceptions.h>
25 # include <deal.II/lac/petsc_solver.h>
26
27 # include <petscksp.h>
28
29 # include <slepceps.h>
30
31 # include <memory>
32
33 DEAL_II_NAMESPACE_OPEN
34
35 // Forward declaration
36 # ifndef DOXYGEN
37 namespace PETScWrappers
38 {
39 // forward declarations
40 class SolverBase;
41 } // namespace PETScWrappers
42 # endif
43
44 namespace SLEPcWrappers
45 {
46 // forward declaration
47 class SolverBase;
48
49 /**
50 * Base class for spectral transformation classes using the SLEPc solvers
51 * which are selected based on flags passed to the spectral transformation.
52 *
53 * <code>SLEPcWrappers::TransformationXXX</code>, where <code>XXX</code> is
54 * your favourite transformation type, can then be implemented in
55 * application codes in the following way for <code>XXX=INVERT</code> with
56 * the solver object <code>eigensolver</code>:
57 * @code
58 * // Set a transformation, this one shifts the eigenspectrum by 3.142..
59 * SLEPcWrappers::TransformationShift::AdditionalData
60 * additional_data(3.142);
61 * SLEPcWrappers::TransformationShift shift(mpi_communicator,additional_data);
62 * eigensolver.set_transformation(shift);
63 * @endcode
64 * and later calling the <code>solve()</code> function as usual:
65 * @code
66 * SolverControl solver_control (1000, 1e-9);
67 * SolverArnoldi system (solver_control, mpi_communicator);
68 * eigensolver.solve (A, B, lambda, x, size_of_spectrum);
69 * @endcode
70 *
71 * @note These options can also be set at the command line.
72 *
73 * @ingroup SLEPcWrappers
74 */
75 class TransformationBase
76 {
77 protected:
78 /**
79 * Constructor.
80 */
81 explicit TransformationBase(const MPI_Comm mpi_communicator);
82
83 public:
84 /**
85 * Destructor.
86 */
87 virtual ~TransformationBase();
88
89 /**
90 * Set a flag to indicate how the transformed matrices are being stored in
91 * the spectral transformations.
92 *
93 * The possible values are given by the enumerator STMatMode in the SLEPc
94 * library
95 * https://slepc.upv.es/documentation/current/docs/manualpages/ST/STMatMode.html
96 */
97 void
98 set_matrix_mode(const STMatMode mode);
99
100 /**
101 * Set solver to be used when solving a system of linear algebraic
102 * equations inside the eigensolver.
103 */
104 void
105 set_solver(const PETScWrappers::SolverBase &solver);
106
107 protected:
108 /**
109 * SLEPc spectral transformation object.
110 */
111 ST st;
112
113 // Make the solver class a friend, since it needs to set spectral
114 // transformation object.
115 friend class SolverBase;
116 };
117
118 /**
119 * An implementation of the transformation interface using the SLEPc Shift.
120 *
121 * @ingroup SLEPcWrappers
122 */
123 class TransformationShift : public TransformationBase
124 {
125 public:
126 /**
127 * Standardized data struct to pipe additional data to the solver.
128 */
129 struct AdditionalData
130 {
131 /**
132 * Constructor. By default, set the shift parameter to zero.
133 */
134 explicit AdditionalData(const double shift_parameter = 0);
135
136 /**
137 * Shift parameter.
138 */
139 const double shift_parameter;
140 };
141
142
143 /**
144 * Constructor.
145 */
146 explicit TransformationShift(const MPI_Comm mpi_communicator,
147 const AdditionalData &data = AdditionalData());
148
149
150 protected:
151 /**
152 * Store a copy of the flags for this particular solver.
153 */
154 const AdditionalData additional_data;
155 };
156
157 /**
158 * An implementation of the transformation interface using the SLEPc Shift
159 * and Invert.
160 *
161 * @ingroup SLEPcWrappers
162 */
163 class TransformationShiftInvert : public TransformationBase
164 {
165 public:
166 /**
167 * Standardized data struct to pipe additional data to the solver.
168 */
169 struct AdditionalData
170 {
171 /**
172 * Constructor. By default, set the shift parameter to zero.
173 */
174 explicit AdditionalData(const double shift_parameter = 0);
175
176 /**
177 * Shift parameter.
178 */
179 const double shift_parameter;
180 };
181
182
183 /**
184 * Constructor.
185 */
186 explicit TransformationShiftInvert(
187 const MPI_Comm mpi_communicator,
188 const AdditionalData &data = AdditionalData());
189
190 protected:
191 /**
192 * Store a copy of the flags for this particular solver.
193 */
194 const AdditionalData additional_data;
195
196 // Make the solver class a friend, since it may need to set target
197 // equal the provided shift value.
198 friend class SolverBase;
199 };
200
201 /**
202 * An implementation of the transformation interface using the SLEPc Cayley.
203 *
204 * @ingroup SLEPcWrappers
205 */
206 class TransformationCayley : public TransformationBase
207 {
208 public:
209 /**
210 * Standardized data struct to pipe additional data to the solver.
211 */
212 struct AdditionalData
213 {
214 /**
215 * Constructor. Requires two shift parameters
216 */
217 explicit AdditionalData(const double shift_parameter = 0,
218 const double antishift_parameter = 0);
219
220 /**
221 * Shift parameter.
222 */
223 const double shift_parameter;
224
225 /**
226 * Antishift parameter.
227 */
228 const double antishift_parameter;
229 };
230
231
232 /**
233 * Constructor.
234 */
235 explicit TransformationCayley(
236 const MPI_Comm mpi_communicator,
237 const AdditionalData &data = AdditionalData());
238
239 protected:
240 /**
241 * Store a copy of the flags for this particular solver.
242 */
243 const AdditionalData additional_data;
244 };
245
246 } // namespace SLEPcWrappers
247
248 DEAL_II_NAMESPACE_CLOSE
249
250 # else
251
252 // Make sure the scripts that create the C++20 module input files have
253 // something to latch on if the preprocessor #ifdef above would
254 // otherwise lead to an empty content of the file.
255 DEAL_II_NAMESPACE_OPEN
256 DEAL_II_NAMESPACE_CLOSE
257
258 # endif // DEAL_II_WITH_SLEPC
259
260 /*-------------------- slepc_spectral_transformation.h ------------------*/
261
262 #endif
263
264 /*-------------------- slepc_spectral_transformation.h ------------------*/