Template Numerical Library: TNL::Solvers::Eigen::experimental Namespace Reference

Template Numerical Library version\ main:c7077e4fd

Loading...
Searching...
No Matches
Functions
TNL::Solvers::Eigen::experimental Namespace Reference
Experimental API

Namespace for experimental eigenvalue solvers. More...

## Functions
template<typename MatrixType>
std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > | powerIteration (const MatrixType &matrix, const typename MatrixType::RealType &epsilon, const int &maxIterations=100000)
| Calculates the largest eigenvalue and its corresponding eigenvector of a given matrix using the power iteration method.
template<typename MatrixType>
std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > | powerIteration (const MatrixType &matrix, const typename MatrixType::RealType &epsilon, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType > &initialVec, const int &maxIterations=100000)
| Calculates the largest eigenvalue and its corresponding eigenvector of a given matrix using the power iteration method.
template<typename MatrixType>
std::tuple< MatrixType, MatrixType, int > | QRAlgorithm (MatrixType matrix, const typename MatrixType::RealType &epsilon, const TNL::Matrices::Factorization::QR::FactorizationMethod &QRMethod, const int &maxIterations=10000)
| Computes the eigenvalues and eigenvectors of a matrix using the QR iteration algorithm with a specified QR factorization method.
template<typename MatrixType>
std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > | shiftedPowerIteration (const MatrixType &matrix, const typename MatrixType::RealType &epsilon, const typename MatrixType::RealType &shiftValue, const int &maxIterations=100000)
| Calculates an eigenvalue and its corresponding eigenvector of a matrix using the shifted power iteration method.
template<typename MatrixType>
std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > | shiftedPowerIteration (const MatrixType &matrix, const typename MatrixType::RealType &epsilon, const typename MatrixType::RealType &shiftValue, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType > &initialVec, const int &maxIterations=100000)
| Calculates an eigenvalue and its corresponding eigenvector of a matrix using the shifted power iteration method.

## Detailed Description

Namespace for experimental eigenvalue solvers.

Warning
  Experimental API: This interface is experimental and may be incomplete, unstable, or subject to change without notice.

## Function Documentation

## ◆ powerIteration() [1/2]

template<typename MatrixType>

std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > TNL::Solvers::Eigen::experimental::powerIteration | ( | const MatrixType & | matrix,
|  | const typename MatrixType::RealType & | epsilon,
|  | const int & | maxIterations = 100000 )

Calculates the largest eigenvalue and its corresponding eigenvector of a given matrix using the power iteration method.

This function implements the power iteration algorithm to find the largest eigenvalue and its associated eigenvector for a square matrix. The process involves repeatedly applying the matrix to an initial vector, normalizing the resulting vector, and checking for convergence against a specified precision threshold.

Template Parameters

  MatrixType | Type of the matrix, which defines both the data type of the matrix elements (e.g., float, double) and the computational device (e.g., CPU, GPU). The matrix must define two nested types: RealType (the data type of the elements) and DeviceType (the device where data is stored and operations are executed).

Parameters

  matrix | The square matrix for which to calculate the largest eigenvalue and associated eigenvector. The matrix type determines both the element data type and the device used for computation.
  epsilon | Precision threshold for convergence. The iterative process halts when the difference between successive iterations falls below this value. This should be of the same type as MatrixType::RealType.
  maxIterations | (Optional) Maximum number of iterations to perform. Defaults to 100000. If this limit is reached before convergence, the function returns the last computed values with the iteration count set to 0.

Returns
  A tuple containing:
  - The largest eigenvalue of the matrix (of type MatrixType::RealType).
  - The eigenvector associated with the largest eigenvalue (of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>).
  - The number of iterations performed to reach convergence (of type int). A value of 0 indicates non-convergence within the specified maximum number of iterations, and -1 indicates a computational error resulting in NaN.

Exceptions

  std::invalid_argument | Thrown if the input matrix is not square, is zero-sized, or if the initial vector size does not match the matrix dimensions.

Note
  Without an initial vector argument, the function generates a random initial vector appropriate for the matrix size and type. The nature of the initial vector can affect the convergence speed of the algorithm.

## ◆ powerIteration() [2/2]

template<typename MatrixType>

std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > TNL::Solvers::Eigen::experimental::powerIteration | ( | const MatrixType & | matrix,
|  | const typename MatrixType::RealType & | epsilon,
|  | TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType > & | initialVec,
|  | const int & | maxIterations = 100000 )

Calculates the largest eigenvalue and its corresponding eigenvector of a given matrix using the power iteration method.

This function implements the power iteration algorithm to find the largest eigenvalue and its associated eigenvector for a square matrix. The process involves repeatedly applying the matrix to an initial vector, normalizing the resulting vector, and checking for convergence against a specified precision threshold.

Template Parameters

  MatrixType | Type of the matrix, which defines both the data type of the matrix elements (e.g., float, double) and the computational device (e.g., CPU, GPU). The matrix must define two nested types: RealType (the data type of the elements) and DeviceType (the device where data is stored and operations are executed).

Parameters

  matrix | The square matrix for which to calculate the largest eigenvalue and associated eigenvector. The matrix type determines both the element data type and the device used for computation.
  epsilon | Precision threshold for convergence. The iterative process halts when the difference between successive iterations falls below this value. This should be of the same type as MatrixType::RealType.
  initialVec | The initial vector to start the iteration with. This vector must have the same size as the matrix dimensions and should not be the zero vector. It is of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>.
  maxIterations | (Optional) Maximum number of iterations to perform. Defaults to 100000. If this limit is reached before convergence, the function returns the last computed values with the iteration count set to 0.

Returns
  A tuple containing:
  - The largest eigenvalue of the matrix (of type MatrixType::RealType).
  - The eigenvector associated with the largest eigenvalue (of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>).
  - The number of iterations performed to reach convergence (of type int). A value of 0 indicates non-convergence within the specified maximum number of iterations, and -1 indicates a computational error resulting in NaN.

Exceptions

  std::invalid_argument | Thrown if the input matrix is not square, is zero-sized, or if the initial vector's size does not match the matrix dimensions.

## ◆ QRAlgorithm()

template<typename MatrixType>

std::tuple< MatrixType, MatrixType, int > TNL::Solvers::Eigen::experimental::QRAlgorithm | ( | MatrixType | matrix,
|  | const typename MatrixType::RealType & | epsilon,
|  | const TNL::Matrices::Factorization::QR::FactorizationMethod & | QRMethod,
|  | const int & | maxIterations = 10000 )

Computes the eigenvalues and eigenvectors of a matrix using the QR iteration algorithm with a specified QR factorization method.

This function implements the QR algorithm to find the eigenvalues and eigenvectors of a square matrix by repeatedly applying QR factorization and recombining the factorized matrices. The matrix converges to an upper triangular form with eigenvalues on the diagonal, and the product of Q matrices across iterations converges to the eigenvector matrix.

Template Parameters

  MatrixType | Type of matrix, which defines both the data type of the matrix elements (e.g., float, double) and the computational device (e.g., CPU, GPU). The matrix must define a nested type RealType, representing the data type of the elements.

Parameters

  matrix | The square matrix for which to compute eigenvalues and eigenvectors. Non-square matrices are not supported. The data type and computational device are determined by the matrix type.
  epsilon | The convergence threshold for the algorithm. The iteration process is considered complete when all off-diagonal elements in the current matrix are smaller than this value. This should be of type MatrixType::RealType.
  QRMethod | An enum class specifying the QR factorization method to use (e.g., Gram-Schmidt, Givens rotations, Householder reflections). This choice impacts the algorithm's efficiency and numerical stability.
  maxIterations | (Optional) The maximum number of iterations to perform, defaulting to 10000. If this limit is reached before convergence, the function terminates, returning the last computed matrices and an iteration count of -1.

Returns
  A tuple comprising three elements:
  - The matrix converged to an upper triangular form, with eigenvalues on the diagonal (of type MatrixType).
  - The matrix of eigenvectors corresponding to the eigenvalues (of type MatrixType).
  - The number of iterations conducted (of type int), where -1 indicates that the iteration limit was reached without achieving convergence.

Exceptions

  std::invalid_argument | Thrown if the matrix is not square or is zero-sized.

## ◆ shiftedPowerIteration() [1/2]

template<typename MatrixType>

std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > TNL::Solvers::Eigen::experimental::shiftedPowerIteration | ( | const MatrixType & | matrix,
|  | const typename MatrixType::RealType & | epsilon,
|  | const typename MatrixType::RealType & | shiftValue,
|  | const int & | maxIterations = 100000 )

Calculates an eigenvalue and its corresponding eigenvector of a matrix using the shifted power iteration method.

This function extends the standard power iteration method by adding a specified shift value to the diagonal of the matrix. It is useful when the largest eigenvalue converges slowly.

Template Parameters

  MatrixType | Type of the matrix, which defines both the data type of the matrix elements (e.g., float, double) and the computational device (e.g., CPU, GPU). The matrix must define two nested types: RealType (the data type of the elements) and DeviceType (the device where data is stored and operations are executed).

Parameters

  matrix | The matrix for which to calculate the eigenvalue and eigenvector. The matrix type determines both the element data type and the device used for computation.
  epsilon | Precision threshold for convergence. The iterative process halts when the difference between successive iterations falls below this value. This should be of the same type as MatrixType::RealType.
  shiftValue | Shift value applied to the matrix spectrum to accelerate convergence. This should be of the same type as MatrixType::RealType.
  maxIterations | (Optional) Maximum number of iterations to perform. Defaults to 100000. If this limit is reached before convergence, the function returns the last computed values with the iteration count set to 0.

Returns
  A tuple containing:
  - The largest eigenvalue of the matrix (of type MatrixType::RealType).
  - The eigenvector associated with the largest eigenvalue (of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>).
  - The number of iterations performed to reach convergence (of type int). A value of 0 indicates non-convergence within the specified maximum number of iterations, and -1 indicates a computational error resulting in NaN.

Exceptions

  std::invalid_argument | Thrown if the matrix is not square, is zero-sized, or if the initial vector size does not match the matrix dimensions.

Note
  Without an initial vector argument, the function generates a random initial vector appropriate for the matrix size and type. The nature of the initial vector can affect the convergence speed of the algorithm.

## ◆ shiftedPowerIteration() [2/2]

template<typename MatrixType>

std::tuple< typename MatrixType::RealType, TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType >, int > TNL::Solvers::Eigen::experimental::shiftedPowerIteration | ( | const MatrixType & | matrix,
|  | const typename MatrixType::RealType & | epsilon,
|  | const typename MatrixType::RealType & | shiftValue,
|  | TNL::Containers::Vector< typename MatrixType::RealType, typename MatrixType::DeviceType > & | initialVec,
|  | const int & | maxIterations = 100000 )

Calculates an eigenvalue and its corresponding eigenvector of a matrix using the shifted power iteration method.

This function extends the standard power iteration method by adding a specified shift value to the diagonal of the matrix. It is useful when the largest eigenvalue converges slowly.

Template Parameters

  MatrixType | Type of the matrix, which defines both the data type of the matrix elements (e.g., float, double) and the computational device (e.g., CPU, GPU). The matrix must define two nested types: RealType (the data type of the elements) and DeviceType (the device where data is stored and operations are executed).

Parameters

  matrix | The matrix for which to calculate the eigenvalue and eigenvector. The matrix type determines both the element data type and the device used for computation.
  epsilon | Precision threshold for convergence. The iterative process halts when the difference between successive iterations falls below this value. This should be of the same type as MatrixType::RealType.
  shiftValue | Shift value applied to the matrix spectrum to accelerate convergence. This should be of the same type as MatrixType::RealType.
  initialVec | The initial vector to start the iteration with. This vector must have the same size as the matrix dimensions and should not be the zero vector. It is of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>.
  maxIterations | (Optional) Maximum number of iterations to perform. Defaults to 100000. If this limit is reached before convergence, the function returns the last computed values with the iteration count set to 0.

Returns
  A tuple containing:
  - The largest eigenvalue of the matrix (of type MatrixType::RealType).
  - The eigenvector associated with the largest eigenvalue (of type TNL::Containers::Vector<typename MatrixType::RealType, typename MatrixType::DeviceType>).
  - The number of iterations performed to reach convergence (of type int). A value of 0 indicates non-convergence within the specified maximum number of iterations, and -1 indicates a computational error resulting in NaN.

Exceptions

  std::invalid_argument | Thrown if the matrix is not square, is zero-sized, or if the initial vector size does not match the matrix dimensions.