Eigen: Eigen::LSMR< MatrixType_, Preconditioner

Searching...

No Matches

#include <Eigen/src/IterativeLinearSolvers/LSMR.h>

Detailed Description

template<typename MatrixType_, typename Preconditioner_>
class Eigen::LSMR< MatrixType_, Preconditioner_ >

An LSMR solver for sparse (or dense) least-squares problems.

This class solves for the least-squares solution of A x = b using the LSMR algorithm of Fong and Saunders. LSMR is based on the Golub-Kahan bidiagonalization and is analytically equivalent to MINRES applied to the normal equation \( A^T A x = A^T b \), so the residual of the normal equation \( ||A^T r|| \) decreases monotonically. In exact arithmetic LSMR returns the minimum-norm least-squares solution. The matrix A can be non-symmetric and rectangular; A and the vectors x and b can be either dense or sparse. LSMR only needs A through the products \( Av \) and \( A^T u \), so a matrix-free operator may be used as well.

Unlike LeastSquaresConjugateGradient, which forms \( A^T A \) implicitly, LSMR works on A directly through the bidiagonalization and is therefore more robust on ill-conditioned problems.

Template Parameters

MatrixType_	the type of the matrix A, can be a dense or a sparse matrix.
Preconditioner_	the type of the preconditioner. Default is IdentityPreconditioner.

This class follows the sparse solver concept .

The maximum number of iterations and the tolerance can be controlled via the setMaxIterations() and setTolerance() methods. The defaults are twice the number of columns of the matrix for the maximum number of iterations and NumTraits<Scalar>::epsilon() for the tolerance. setTolerance() sets both of the algorithm's stopping tolerances atol (relative error assumed in A) and btol (relative error assumed in b); they can also be set independently via setToleranceA() and setToleranceB().

Unlike most other iterative solvers, error() does not report the relative residual \( ||Ax-b||/||b|| \): it reports the estimate \( ||A^T r|| / (||A||\,||r||) \), with \( r = b - Ax \), of the relative residual of the normal equations, the quantity that the least-squares stopping rule bounds by atol.

The setDamping() method enables Tikhonov regularization: with a damping \( \lambda > 0 \) the solver minimizes \( ||Ax-b||^2 + \lambda^2 ||x||^2 \), for which a unique solution always exists. The setConditionLimit() method can be used to stop the iterations as soon as the estimated condition number of A exceeds a given bound.

This class can be used like the other iterative solvers. Here is a typical usage example:

int m = 1000000, n = 10000;
VectorXd x(n), b(m);
SparseMatrix<double> A(m, n);
// fill A and b
LSMR<SparseMatrix<double> > lsmr;
lsmr.compute(A);
x = lsmr.solve(b);
std::cout << "#iterations:     " << lsmr.iterations() << std::endl;
std::cout << "estimated error: " << lsmr.error()      << std::endl;
// update b, and solve again
x = lsmr.solve(b);

By default the iterations start with x=0 as an initial guess of the solution. One can control the start using the solveWithGuess() method.

If a non-default preconditioner is supplied it is applied as a self-adjoint right preconditioner (LSMR is run on \( A M^{-1} z = b \) and the solution recovered from \( M x = z \)); it should therefore be self-adjoint, as DiagonalPreconditioner and IdentityPreconditioner are.

See also: class LeastSquaresConjugateGradient, class ConjugateGradient, SparseLU, SparseQR

Inheritance diagram for Eigen::LSMR< MatrixType_, Preconditioner_ >:

Public Member Functions
RealScalar	conditionLimit () const

RealScalar	damping () const

	LSMR ()

template<typename MatrixDerived>
	LSMR (const EigenBase< MatrixDerived > &A)

LSMR &	setConditionLimit (const RealScalar &conlim)

LSMR &	setDamping (const RealScalar &lambda)

LSMR &	setToleranceA (const RealScalar &atol)

LSMR &	setToleranceB (const RealScalar &btol)

RealScalar	toleranceA () const

RealScalar	toleranceB () const

Public Member Functions inherited from Eigen::IterativeSolverBase< LSMR< MatrixType_, Preconditioner_ > >
LSMR< MatrixType_, Preconditioner_ > &	analyzePattern (const EigenBase< MatrixDerived > &A)

LSMR< MatrixType_, Preconditioner_ > &	compute (const EigenBase< MatrixDerived > &A)

RealScalar	error () const

LSMR< MatrixType_, Preconditioner_ > &	factorize (const EigenBase< MatrixDerived > &A)

ComputationInfo	info () const

Index	iterations () const

	IterativeSolverBase ()

	IterativeSolverBase (const EigenBase< MatrixDerived > &A)

Index	maxIterations () const

Preconditioner &	preconditioner ()

const Preconditioner &	preconditioner () const

LSMR< MatrixType_, Preconditioner_ > &	setMaxIterations (Index maxIters)

LSMR< MatrixType_, Preconditioner_ > &	setTolerance (const RealScalar &tolerance)

const SolveWithGuess< LSMR< MatrixType_, Preconditioner_ >, Rhs, Guess >	solveWithGuess (const MatrixBase< Rhs > &b, const Guess &x0) const

void	solveWithGuessInPlace (const Rhs &b, Dest &x) const

RealScalar	tolerance () const

Public Member Functions inherited from Eigen::SparseSolverBase< LSMR< MatrixType_, Preconditioner_ > >
Solve< LSMR< MatrixType_, Preconditioner_ >, Rhs >	solve (const MatrixBase< Rhs > &b) const

Solve< LSMR< MatrixType_, Preconditioner_ >, Rhs >	solve (const SparseMatrixBase< Rhs > &b) const

	SparseSolverBase ()=default

Constructor & Destructor Documentation

◆ LSMR() [1/2]

template<typename MatrixType_, typename Preconditioner_>

Eigen::LSMR< MatrixType_, Preconditioner_ >::LSMR ( )

inline

Default constructor.

◆ LSMR() [2/2]

template<typename MatrixType_, typename Preconditioner_>

template<typename MatrixDerived>

Eigen::LSMR< MatrixType_, Preconditioner_ >::LSMR ( const EigenBase< MatrixDerived > & A )

inlineexplicit

Initialize the solver with matrix A for further Ax=b solving.

This constructor is a shortcut for the default constructor followed by a call to compute().

Warning: this class stores a reference to the matrix A as well as some precomputed values that depend on it. Therefore, if A is changed this class becomes invalid. Call compute() to update it with the new matrix A, or modify a copy of A.

Member Function Documentation

◆ conditionLimit()

template<typename MatrixType_, typename Preconditioner_>

RealScalar Eigen::LSMR< MatrixType_, Preconditioner_ >::conditionLimit ( ) const

inline

Returns: the condition-number limit.

See also: setConditionLimit()

◆ damping()

template<typename MatrixType_, typename Preconditioner_>

RealScalar Eigen::LSMR< MatrixType_, Preconditioner_ >::damping ( ) const

inline

Returns: the damping parameter.

See also: setDamping()

◆ setConditionLimit()

template<typename MatrixType_, typename Preconditioner_>

LSMR & Eigen::LSMR< MatrixType_, Preconditioner_ >::setConditionLimit ( const RealScalar & conlim )

inline

Sets an upper limit on the estimated condition number of A. The iterations stop as soon as the estimate exceeds conlim. The default is 0, which disables the limit (equivalent to 1/epsilon).

◆ setDamping()

template<typename MatrixType_, typename Preconditioner_>

LSMR & Eigen::LSMR< MatrixType_, Preconditioner_ >::setDamping ( const RealScalar & lambda )

inline

Sets the damping parameter \( \lambda \ge 0 \) for Tikhonov regularization. With lambda > 0 the solver minimizes \( ||Ax-b||^2 + \lambda^2 ||x||^2 \). The default is 0 (no damping).

Note: When a non-identity preconditioner \( M \) is used the damping applies in the preconditioned variable, i.e. the solver minimizes \( ||Ax-b||^2 + \lambda^2 ||Mx||^2 \). With the default IdentityPreconditioner this is exactly \( ||Ax-b||^2 + \lambda^2 ||x||^2 \).

◆ setToleranceA()

template<typename MatrixType_, typename Preconditioner_>

LSMR & Eigen::LSMR< MatrixType_, Preconditioner_ >::setToleranceA ( const RealScalar & atol )

inline

Sets the stopping tolerance atol, which bounds the relative error assumed in the entries of A. It drives the least-squares stopping rule \( ||A^T r|| \le atol\,||A||\,||r|| \). If left unset (the default) it falls back to tolerance().

See also: setToleranceB(), setTolerance()

◆ setToleranceB()

template<typename MatrixType_, typename Preconditioner_>

LSMR & Eigen::LSMR< MatrixType_, Preconditioner_ >::setToleranceB ( const RealScalar & btol )

inline

Sets the stopping tolerance btol, which bounds the relative error assumed in the entries of b. It enters the compatible-system stopping rule \( ||r|| \le btol\,||b|| + atol\,||A||\,||x|| \). If left unset (the default) it falls back to tolerance().

See also: setToleranceA(), setTolerance()

◆ toleranceA()

template<typename MatrixType_, typename Preconditioner_>

RealScalar Eigen::LSMR< MatrixType_, Preconditioner_ >::toleranceA ( ) const

inline

Returns: atol, or tolerance() if setToleranceA() has not been called.

See also: setToleranceA()

◆ toleranceB()

template<typename MatrixType_, typename Preconditioner_>

RealScalar Eigen::LSMR< MatrixType_, Preconditioner_ >::toleranceB ( ) const

inline

Returns: btol, or tolerance() if setToleranceB() has not been called.

See also: setToleranceB()

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

/builds/libeigen/eigen/Eigen/src/IterativeLinearSolvers/LSMR.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ LSMR() [1/2]

◆ LSMR() [2/2]

Member Function Documentation

◆ conditionLimit()

◆ damping()

◆ setConditionLimit()

◆ setDamping()

◆ setToleranceA()

◆ setToleranceB()

◆ toleranceA()

◆ toleranceB()