TNL::Solvers::Linear::LinearSolver< Matrix > Class Template Reference

Base class for iterative solvers of systems of linear equations. More...

#include <TNL/Solvers/Linear/LinearSolver.h>

Inheritance diagram for TNL::Solvers::Linear::LinearSolver< Matrix >:

Collaboration diagram for TNL::Solvers::Linear::LinearSolver< Matrix >:

Public Types
using	ConstVectorViewType = typename Traits< Matrix >::ConstVectorViewType
	Type for constant vector view.
using	DeviceType = typename Matrix::DeviceType
	Device where the solver will run on and auxillary data will alloacted on.
using	IndexType = typename Matrix::IndexType
	Type for indexing.
using	MatrixPointer = std::shared_ptr< std::add_const_t< MatrixType > >
	Type of shared pointer to the matrix.
using	MatrixType = Matrix
	Type of the matrix representing the linear system.
using	PreconditionerPointer = std::shared_ptr< std::add_const_t< PreconditionerType > >
	Type of shared pointer to the preconditioner.
using	PreconditionerType = Preconditioners::Preconditioner< MatrixType >
	Type of preconditioner.
using	RealType = typename Matrix::RealType
	Floating point type used for computations.
using	VectorViewType = typename Traits< Matrix >::VectorViewType
	Type for vector view.
Public Types inherited from TNL::Solvers::IterativeSolver< Matrix::RealType, Matrix::IndexType >
using	SolverMonitorType
	Type of an object used for monitoring of the convergence.

Public Member Functions
virtual	~LinearSolver ()
	Default destructor.
void	setMatrix (const MatrixPointer &matrix)
	Set the matrix of the linear system.
void	setPreconditioner (const PreconditionerPointer &preconditioner)
	Set the preconditioner.
virtual bool	setup (const Config::ParameterContainer &parameters, const String &prefix="")
	Method for setup of the linear iterative solver based on configuration parameters.
virtual bool	solve (ConstVectorViewType b, VectorViewType x)=0
	Method for solving a linear system.
Public Member Functions inherited from TNL::Solvers::IterativeSolver< Matrix::RealType, Matrix::IndexType >
	IterativeSolver ()=default
	Default constructor.
bool	checkConvergence ()
	Checks whether the convergence occurred already.
bool	checkNextIteration ()
	Checks if the solver is allowed to do the next iteration.
const Matrix::RealType &	getConvergenceResidue () const
	Gets the the convergence threshold.
const Matrix::RealType &	getDivergenceResidue () const
	Gets the limit for the divergence criterion.
const Matrix::IndexType &	getIterations () const
	Gets the number of iterations performed by the solver so far.
const Matrix::IndexType &	getMaxIterations () const
	Gets the maximal number of iterations the solver is allowed to perform.
const Matrix::IndexType &	getMinIterations () const
	Gets the minimal number of iterations the solver is supposed to do.
const Matrix::RealType &	getResidue () const
	Gets the residue reached at the current iteration.
bool	nextIteration ()
	Proceeds to the next iteration.
void	resetIterations ()
	Sets the the number of the current iterations to zero.
void	setConvergenceResidue (const Matrix::RealType &convergenceResidue)
	Sets the threshold for the convergence.
void	setDivergenceResidue (const Matrix::RealType &divergenceResidue)
	Sets the residue limit for the divergence criterion.
void	setMaxIterations (const Matrix::IndexType &maxIterations)
	Sets the maximal number of iterations the solver is allowed to perform.
void	setMinIterations (const Matrix::IndexType &minIterations)
	Sets the minimal number of iterations the solver is supposed to do.
void	setRefreshRate (const Matrix::IndexType &refreshRate)
	Sets the refresh rate (in milliseconds) for the solver monitor.
void	setResidue (const Matrix::RealType &residue)
	Sets the residue reached at the current iteration.
void	setSolverMonitor (SolverMonitorType &solverMonitor)
	Sets the solver monitor object.
bool	setup (const Config::ParameterContainer &parameters, const std::string &prefix="")
	Method for setup of the iterative solver based on configuration parameters.

Static Public Member Functions
static void	configSetup (Config::ConfigDescription &config, const String &prefix="")
	This method defines configuration entries for setup of the linear iterative solver.
Static Public Member Functions inherited from TNL::Solvers::IterativeSolver< Matrix::RealType, Matrix::IndexType >
static void	configSetup (Config::ConfigDescription &config, const std::string &prefix="")
	This method defines configuration entries for setup of the iterative solver.

Protected Attributes
MatrixPointer	matrix = nullptr
PreconditionerPointer	preconditioner = nullptr
Protected Attributes inherited from TNL::Solvers::IterativeSolver< Matrix::RealType, Matrix::IndexType >
Matrix::RealType	convergenceResidue
Matrix::IndexType	currentIteration
Matrix::RealType	currentResidue
Matrix::RealType	divergenceResidue
Matrix::IndexType	maxIterations
Matrix::IndexType	minIterations
Matrix::IndexType	refreshRate
std::ofstream	residualHistoryFile
std::string	residualHistoryFileName
IterativeSolverMonitor< Matrix::RealType, Matrix::IndexType > *	solverMonitor

Detailed Description

template<typename Matrix>
class TNL::Solvers::Linear::LinearSolver< Matrix >

Base class for iterative solvers of systems of linear equations.

To use the linear solver, one needs to first set the matrix of the linear system by means of the method LinearSolver::setMatrix. Afterward, one may call the method LinearSolver::solve which accepts the right-hand side vector b and a vector x to which the solution will be stored. One may also use appropriate preconditioner to speed-up the convergence - see the method LinearSolver::setPreconditioner.

Template Parameters

Matrix

is type of matrix representing the linear system.

The following example demonstrates the use iterative linear solvers:

#include <iostream>
#include <memory>
#include <TNL/Matrices/SparseMatrix.h>
#include <TNL/Devices/Host.h>
#include <TNL/Devices/Cuda.h>
#include <TNL/Solvers/Linear/TFQMR.h>
 
template< typename Device >
void
iterativeLinearSolverExample()
{
   /***
    * Set the following matrix (dots represent zero matrix elements):
    *
    *   /  2.5 -1    .    .    .   \
    *   | -1    2.5 -1    .    .   |
    *   |  .   -1    2.5 -1.   .   |
    *   |  .    .   -1    2.5 -1   |
    *   \  .    .    .   -1    2.5 /
    */
   using MatrixType = TNL::Matrices::SparseMatrix< double, Device >;
   using Vector = TNL::Containers::Vector< double, Device >;
   const int size( 5 );
   auto matrix_ptr = std::make_shared< MatrixType >();
   matrix_ptr->setDimensions( size, size );
   matrix_ptr->setRowCapacities( Vector( { 2, 3, 3, 3, 2 } ) );
 
   auto f = [ = ] __cuda_callable__( typename MatrixType::RowView & row ) mutable
   {
      const int rowIdx = row.getRowIndex();
      if( rowIdx == 0 ) {
         row.setElement( 0, rowIdx, 2.5 );     // diagonal element
         row.setElement( 1, rowIdx + 1, -1 );  // element above the diagonal
      }
      else if( rowIdx == size - 1 ) {
         row.setElement( 0, rowIdx - 1, -1.0 );  // element below the diagonal
         row.setElement( 1, rowIdx, 2.5 );       // diagonal element
      }
      else {
         row.setElement( 0, rowIdx - 1, -1.0 );  // element below the diagonal
         row.setElement( 1, rowIdx, 2.5 );       // diagonal element
         row.setElement( 2, rowIdx + 1, -1.0 );  // element above the diagonal
      }
   };
 
   /***
    * Set the matrix elements.
    */
   matrix_ptr->forAllRows( f );
   std::cout << *matrix_ptr << std::endl;
 
   /***
    * Set the right-hand side vector.
    */
   Vector x( size, 1.0 );
   Vector b( size );
   matrix_ptr->vectorProduct( x, b );
   x = 0.0;
   std::cout << "Vector b = " << b << std::endl;
 
   /***
    * Solve the linear system.
    */
   using LinearSolver = TNL::Solvers::Linear::TFQMR< MatrixType >;
   LinearSolver solver;
   solver.setMatrix( matrix_ptr );
   solver.setConvergenceResidue( 1.0e-6 );
   solver.solve( b, x );
   std::cout << "Vector x = " << x << std::endl;
}
 
int
main( int argc, char* argv[] )
{
   std::cout << "Solving linear system on host: " << std::endl;
   iterativeLinearSolverExample< TNL::Devices::Sequential >();
 
#ifdef __CUDACC__
   std::cout << "Solving linear system on CUDA device: " << std::endl;
   iterativeLinearSolverExample< TNL::Devices::Cuda >();
#endif
}

The result looks as follows:

Solving linear system on host: 
Row: 0 ->     0:2.5     1:-1  
Row: 1 ->     0:-1      1:2.5     2:-1  
Row: 2 ->     1:-1      2:2.5     3:-1  
Row: 3 ->     2:-1      3:2.5     4:-1  
Row: 4 ->     3:-1      4:2.5 
 
Vector b = [ 1.5, 0.5, 0.5, 0.5, 1.5 ]
Vector x = [ 1, 1, 1, 1, 1 ]
Solving linear system on CUDA device: 
Row: 0 ->     0:2.5     1:-1  
Row: 1 ->     0:-1      1:2.5     2:-1  
Row: 2 ->     1:-1      2:2.5     3:-1  
Row: 3 ->     2:-1      3:2.5     4:-1  
Row: 4 ->     3:-1      4:2.5 
 
Vector b = [ 1.5, 0.5, 0.5, 0.5, 1.5 ]
Vector x = [ 1, 1, 1, 1, 1 ]

See also TNL::Solvers::IterativeSolverMonitor for monitoring of iterative solvers.

Member Typedef Documentation

DeviceType

template<typename Matrix>

using TNL::Solvers::Linear::LinearSolver< Matrix >::DeviceType = typename Matrix::DeviceType

Device where the solver will run on and auxillary data will alloacted on.

See Devices::Host or Devices::Cuda.

Member Function Documentation

configSetup()

template<typename Matrix>

static void TNL::Solvers::Linear::LinearSolver< Matrix >::configSetup ( Config::ConfigDescription & config, const String & prefix = "" )

inlinestatic

This method defines configuration entries for setup of the linear iterative solver.

See IterativeSolver::configSetup.

Parameters

config	contains description of configuration parameters.
prefix	is a prefix of particular configuration entries.

setMatrix()

template<typename Matrix>

void TNL::Solvers::Linear::LinearSolver< Matrix >::setMatrix ( const MatrixPointer & matrix )

inline

Set the matrix of the linear system.

Parameters

matrix

is a shared pointer to the matrix of the linear system

setPreconditioner()

template<typename Matrix>

void TNL::Solvers::Linear::LinearSolver< Matrix >::setPreconditioner ( const PreconditionerPointer & preconditioner )

inline

Set the preconditioner.

Parameters

preconditioner

is a shared pointer to preconditioner.

setup()

template<typename Matrix>

virtual bool TNL::Solvers::Linear::LinearSolver< Matrix >::setup ( const Config::ParameterContainer & parameters, const String & prefix = "" )

inlinevirtual

Method for setup of the linear iterative solver based on configuration parameters.

Parameters

parameters	contains values of the define configuration entries.
prefix	is a prefix of particular configuration entries.

Reimplemented in TNL::Solvers::Linear::BICGStab< Matrix >, TNL::Solvers::Linear::BICGStabL< Matrix >, TNL::Solvers::Linear::GMRES< Matrix >, TNL::Solvers::Linear::IDRs< Matrix >, TNL::Solvers::Linear::Jacobi< Matrix >, and TNL::Solvers::Linear::SOR< Matrix >.

solve()

template<typename Matrix>

virtual bool TNL::Solvers::Linear::LinearSolver< Matrix >::solve ( ConstVectorViewType b, VectorViewType x )

pure virtual

Method for solving a linear system.

The linear system is defined by the matrix given by the method LinearSolver::setMatrix and by the right-hand side vector represented by the vector b. The result is stored in the vector b. The solver can be accelerated with appropriate preconditioner set by the methods LinearSolver::setPreconditioner.

Parameters

b	vector with the right-hand side of the linear system.
x	vector for the solution of the linear system.

Returns

true if the solver converged.

false if the solver did not converge.

Example

#include <iostream>
#include <memory>
#include <TNL/Matrices/SparseMatrix.h>
#include <TNL/Devices/Host.h>
#include <TNL/Devices/Cuda.h>
#include <TNL/Solvers/Linear/TFQMR.h>
 
template< typename Device >
void
iterativeLinearSolverExample()
{
   /***
    * Set the following matrix (dots represent zero matrix elements):
    *
    *   /  2.5 -1    .    .    .   \
    *   | -1    2.5 -1    .    .   |
    *   |  .   -1    2.5 -1.   .   |
    *   |  .    .   -1    2.5 -1   |
    *   \  .    .    .   -1    2.5 /
    */
   using MatrixType = TNL::Matrices::SparseMatrix< double, Device >;
   using Vector = TNL::Containers::Vector< double, Device >;
   const int size( 5 );
   auto matrix_ptr = std::make_shared< MatrixType >();
   matrix_ptr->setDimensions( size, size );
   matrix_ptr->setRowCapacities( Vector( { 2, 3, 3, 3, 2 } ) );
 
   auto f = [ = ] __cuda_callable__( typename MatrixType::RowView & row ) mutable
   {
      const int rowIdx = row.getRowIndex();
      if( rowIdx == 0 ) {
         row.setElement( 0, rowIdx, 2.5 );     // diagonal element
         row.setElement( 1, rowIdx + 1, -1 );  // element above the diagonal
      }
      else if( rowIdx == size - 1 ) {
         row.setElement( 0, rowIdx - 1, -1.0 );  // element below the diagonal
         row.setElement( 1, rowIdx, 2.5 );       // diagonal element
      }
      else {
         row.setElement( 0, rowIdx - 1, -1.0 );  // element below the diagonal
         row.setElement( 1, rowIdx, 2.5 );       // diagonal element
         row.setElement( 2, rowIdx + 1, -1.0 );  // element above the diagonal
      }
   };
 
   /***
    * Set the matrix elements.
    */
   matrix_ptr->forAllRows( f );
   std::cout << *matrix_ptr << std::endl;
 
   /***
    * Set the right-hand side vector.
    */
   Vector x( size, 1.0 );
   Vector b( size );
   matrix_ptr->vectorProduct( x, b );
   x = 0.0;
   std::cout << "Vector b = " << b << std::endl;
 
   /***
    * Solve the linear system.
    */
   using LinearSolver = TNL::Solvers::Linear::TFQMR< MatrixType >;
   LinearSolver solver;
   solver.setMatrix( matrix_ptr );
   solver.setConvergenceResidue( 1.0e-6 );
   solver.solve( b, x );
   std::cout << "Vector x = " << x << std::endl;
}
 
int
main( int argc, char* argv[] )
{
   std::cout << "Solving linear system on host: " << std::endl;
   iterativeLinearSolverExample< TNL::Devices::Sequential >();
 
#ifdef __CUDACC__
   std::cout << "Solving linear system on CUDA device: " << std::endl;
   iterativeLinearSolverExample< TNL::Devices::Cuda >();
#endif
}

Output

Solving linear system on host: 
Row: 0 ->     0:2.5     1:-1  
Row: 1 ->     0:-1      1:2.5     2:-1  
Row: 2 ->     1:-1      2:2.5     3:-1  
Row: 3 ->     2:-1      3:2.5     4:-1  
Row: 4 ->     3:-1      4:2.5 
 
Vector b = [ 1.5, 0.5, 0.5, 0.5, 1.5 ]
Vector x = [ 1, 1, 1, 1, 1 ]
Solving linear system on CUDA device: 
Row: 0 ->     0:2.5     1:-1  
Row: 1 ->     0:-1      1:2.5     2:-1  
Row: 2 ->     1:-1      2:2.5     3:-1  
Row: 3 ->     2:-1      3:2.5     4:-1  
Row: 4 ->     3:-1      4:2.5 
 
Vector b = [ 1.5, 0.5, 0.5, 0.5, 1.5 ]
Vector x = [ 1, 1, 1, 1, 1 ]

Implemented in TNL::Solvers::Linear::BICGStab< Matrix >, TNL::Solvers::Linear::BICGStabL< Matrix >, TNL::Solvers::Linear::CG< Matrix >, TNL::Solvers::Linear::GMRES< Matrix >, TNL::Solvers::Linear::IDRs< Matrix >, TNL::Solvers::Linear::Jacobi< Matrix >, TNL::Solvers::Linear::SOR< Matrix >, and TNL::Solvers::Linear::TFQMR< Matrix >.

---

The documentation for this class was generated from the following file:

• src/TNL/Solvers/Linear/LinearSolver.h