libMesh
linear_solver.h
Go to the documentation of this file.
1 // The libMesh Finite Element Library.
2 // Copyright (C) 2002-2017 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_LINEAR_SOLVER_H
21 #define LIBMESH_LINEAR_SOLVER_H
22 
23 // Local includes
24 #include "libmesh/libmesh_common.h"
25 #include "libmesh/enum_convergence_flags.h"
26 #include "libmesh/enum_solver_package.h"
27 #include "libmesh/enum_solver_type.h"
28 #include "libmesh/enum_preconditioner_type.h"
29 #include "libmesh/enum_subset_solve_mode.h"
30 #include "libmesh/reference_counted_object.h"
31 #include "libmesh/libmesh.h"
32 #include "libmesh/parallel_object.h"
33 #include "libmesh/auto_ptr.h"
34 
35 // C++ includes
36 #include <cstddef>
37 #include <vector>
38 
39 namespace libMesh
40 {
41 
42 // forward declarations
43 template <typename T> class SparseMatrix;
44 template <typename T> class NumericVector;
45 template <typename T> class ShellMatrix;
46 template <typename T> class Preconditioner;
47 class System;
48 class SolverConfiguration;
49 
57 template <typename T>
58 class LinearSolver : public ReferenceCountedObject<LinearSolver<T>>,
59  public ParallelObject
60 {
61 public:
62 
67  LIBMESH_CAN_DEFAULT_TO_COMMWORLD);
68 
72  virtual ~LinearSolver ();
73 
79  const SolverPackage solver_package = libMesh::default_solver_package());
80 
85  bool initialized () const { return _is_initialized; }
86 
90  virtual void clear () {}
91 
96  virtual void init (const char * name = libmesh_nullptr) = 0;
97 
106  virtual void init_names (const System &) {}
107 
111  SolverType solver_type () const { return _solver_type; }
112 
116  void set_solver_type (const SolverType st)
117  { _solver_type = st; }
118 
123 
128 
132  void attach_preconditioner(Preconditioner<T> * preconditioner);
133 
138  virtual void reuse_preconditioner(bool );
139 
145 
153  virtual void restrict_solve_to (const std::vector<unsigned int> * const dofs,
154  const SubsetSolveMode subset_solve_mode=SUBSET_ZERO);
155 
163  virtual std::pair<unsigned int, Real> solve (SparseMatrix<T> &, // System Matrix
164  NumericVector<T> &, // Solution vector
165  NumericVector<T> &, // RHS vector
166  const double, // Stopping tolerance
167  const unsigned int) = 0; // N. Iterations
168 
176  virtual std::pair<unsigned int, Real> adjoint_solve (SparseMatrix<T> &, // System Matrix
177  NumericVector<T> &, // Solution vector
178  NumericVector<T> &, // RHS vector
179  const double, // Stopping tolerance
180  const unsigned int); // N. Iterations
181 
187  virtual std::pair<unsigned int, Real> solve (SparseMatrix<T> &, // System Matrix
188  SparseMatrix<T> &, // Preconditioning Matrix
189  NumericVector<T> &, // Solution vector
190  NumericVector<T> &, // RHS vector
191  const double, // Stopping tolerance
192  const unsigned int) = 0; // N. Iterations
193 
200  std::pair<unsigned int, Real> solve (SparseMatrix<T> & matrix,
201  SparseMatrix<T> * precond_matrix,
202  NumericVector<T> &, // Solution vector
203  NumericVector<T> &, // RHS vector
204  const double, // Stopping tolerance
205  const unsigned int); // N. Iterations
206 
207 
208 
212  virtual std::pair<unsigned int, Real> solve (const ShellMatrix<T> & shell_matrix,
213  NumericVector<T> &, // Solution vector
214  NumericVector<T> &, // RHS vector
215  const double, // Stopping tolerance
216  const unsigned int) = 0; // N. Iterations
217 
218 
224  virtual std::pair<unsigned int, Real> solve (const ShellMatrix<T> & shell_matrix,
225  const SparseMatrix<T> & precond_matrix,
226  NumericVector<T> &, // Solution vector
227  NumericVector<T> &, // RHS vector
228  const double, // Stopping tolerance
229  const unsigned int) = 0; // N. Iterations
230 
231 
236  std::pair<unsigned int, Real> solve (const ShellMatrix<T> & matrix,
237  const SparseMatrix<T> * precond_matrix,
238  NumericVector<T> &, // Solution vector
239  NumericVector<T> &, // RHS vector
240  const double, // Stopping tolerance
241  const unsigned int); // N. Iterations
242 
243 
248  virtual void print_converged_reason() const;
249 
253  virtual LinearConvergenceReason get_converged_reason() const = 0;
254 
258  void set_solver_configuration(SolverConfiguration & solver_configuration);
259 
260 protected:
261 
262 
267 
272 
277 
282 
290 
296 };
297 
298 
299 
300 
301 /*----------------------- inline functions ----------------------------------*/
302 template <typename T>
303 inline
305  ParallelObject (comm_in),
308  _is_initialized (false),
310  same_preconditioner (false),
312 {
313 }
314 
315 
316 
317 template <typename T>
318 inline
320 {
321  this->clear ();
322 }
323 
324 template <typename T>
325 inline
327 {
328  return same_preconditioner;
329 }
330 
331 template <typename T>
332 inline
333 std::pair<unsigned int, Real>
335  SparseMatrix<T> * pc_mat,
336  NumericVector<T> & sol,
337  NumericVector<T> & rhs,
338  const double tol,
339  const unsigned int n_iter)
340 {
341  if (pc_mat)
342  return this->solve(mat, *pc_mat, sol, rhs, tol, n_iter);
343  else
344  return this->solve(mat, sol, rhs, tol, n_iter);
345 }
346 
347 
348 template <typename T>
349 inline
350 std::pair<unsigned int, Real>
352  const SparseMatrix<T> * pc_mat,
353  NumericVector<T> & sol,
354  NumericVector<T> & rhs,
355  const double tol,
356  const unsigned int n_iter)
357 {
358  if (pc_mat)
359  return this->solve(mat, *pc_mat, sol, rhs, tol, n_iter);
360  else
361  return this->solve(mat, sol, rhs, tol, n_iter);
362 }
363 
364 } // namespace libMesh
365 
366 
367 #endif // LIBMESH_LINEAR_SOLVER_H
std::string name(const ElemQuality q)
This function returns a string containing some name for q.
Definition: elem_quality.C:39
virtual void clear()
Release all memory and clear data structures.
Definition: linear_solver.h:90
SolverType _solver_type
Enum stating which type of iterative solver to use.
Encapsulates the MPI_Comm object.
Definition: parallel.h:657
SolverType
Defines an enum for iterative solver types.
virtual ~LinearSolver()
Destructor.
bool initialized() const
Definition: linear_solver.h:85
Preconditioner< T > * _preconditioner
Holds the Preconditioner object to be used for the linear solves.
static UniquePtr< LinearSolver< T > > build(const libMesh::Parallel::Communicator &comm_in, const SolverPackage solver_package=libMesh::default_solver_package())
Builds a LinearSolver using the linear solver package specified by solver_package.
Definition: linear_solver.C:42
Set dofs outside the subset to zero.
SolverPackage
Defines an enum for various linear solver packages.
const class libmesh_nullptr_t libmesh_nullptr
Numeric vector.
Definition: dof_map.h:66
PreconditionerType preconditioner_type() const
Definition: linear_solver.C:83
virtual LinearConvergenceReason get_converged_reason() const =0
The libMesh namespace provides an interface to certain functionality in the library.
std::unique_ptr< T > UniquePtr
Definition: auto_ptr.h:46
Generic sparse matrix.
Definition: dof_map.h:65
SolverPackage default_solver_package()
Definition: libmesh.C:995
This base class can be inherited from to provide interfaces to linear solvers from different packages...
Definition: linear_solver.h:58
PreconditionerType
Defines an enum for preconditioner types.
This class provides a uniform interface for preconditioners.
virtual void init(const char *name=libmesh_nullptr)=0
Initialize data structures if not done so already.
This is the base class for classes which contain information related to any physical process that mig...
Definition: system.h:76
SolverConfiguration * _solver_configuration
Optionally store a SolverOptions object that can be used to set parameters like solver type...
void set_preconditioner_type(const PreconditionerType pct)
Sets the type of preconditioner to use.
Definition: linear_solver.C:93
virtual std::pair< unsigned int, Real > adjoint_solve(SparseMatrix< T > &, NumericVector< T > &, NumericVector< T > &, const double, const unsigned int)
Function to solve the adjoint system.
SolverType solver_type() const
This class stores solver configuration data, e.g.
virtual std::pair< unsigned int, Real > solve(SparseMatrix< T > &, NumericVector< T > &, NumericVector< T > &, const double, const unsigned int)=0
This function calls the solver _solver_type preconditioned with the _preconditioner_type precondition...
void set_solver_type(const SolverType st)
Sets the type of solver to use.
This class implements reference counting.
This class forms the base class for all other classes that are expected to be implemented in parallel...
void attach_preconditioner(Preconditioner< T > *preconditioner)
Attaches a Preconditioner object to be used.
void set_solver_configuration(SolverConfiguration &solver_configuration)
Set the solver configuration object.
LinearSolver(const libMesh::Parallel::Communicator &comm_in LIBMESH_CAN_DEFAULT_TO_COMMWORLD)
Constructor.
virtual void reuse_preconditioner(bool)
Set the same_preconditioner flag, which indicates if we reuse the same preconditioner for subsequent ...
PreconditionerType _preconditioner_type
Enum stating with type of preconditioner to use.
virtual void print_converged_reason() const
Prints a useful message about why the latest linear solve con(di)verged.
LinearConvergenceReason
Linear solver convergence flags (taken from the PETSc flags)
bool same_preconditioner
Boolean flag to indicate whether we want to use an identical preconditioner to the previous solve...
virtual void restrict_solve_to(const std::vector< unsigned int > *const dofs, const SubsetSolveMode subset_solve_mode=SUBSET_ZERO)
After calling this method, all successive solves will be restricted to the given set of dofs...
SubsetSolveMode
defines an enum for the question what happens to the dofs outside the given subset when a system is s...
Generic shell matrix, i.e.
virtual void init_names(const System &)
Apply names to the system to be solved.
bool _is_initialized
Flag indicating if the data structures have been initialized.