Eigen  3.4.90 (git rev 9589cc4e7fd8e4538bedef80dd36c7738977a8be)
 
Loading...
Searching...
No Matches
Public Member Functions | List of all members
Eigen::HouseholderSequence< VectorsType, CoeffsType, Side > Class Template Reference
Dense matrix and array manipulation » Reference » Householder module

#include <Eigen/src/Householder/HouseholderSequence.h>

Detailed Description

template<typename VectorsType, typename CoeffsType, int Side>
class Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >

Sequence of Householder reflections acting on subspaces with decreasing size.

This is defined in the Householder module.

#include <Eigen/Householder>
Template Parameters
VectorsTypetype of matrix containing the Householder vectors
CoeffsTypetype of vector containing the Householder coefficients
Sideeither OnTheLeft (the default) or OnTheRight

This class represents a product sequence of Householder reflections where the first Householder reflection acts on the whole space, the second Householder reflection leaves the one-dimensional subspace spanned by the first unit vector invariant, the third Householder reflection leaves the two-dimensional subspace spanned by the first two unit vectors invariant, and so on up to the last reflection which leaves all but one dimensions invariant and acts only on the last dimension. Such sequences of Householder reflections are used in several algorithms to zero out certain parts of a matrix. Indeed, the methods HessenbergDecomposition::matrixQ(), Tridiagonalization::matrixQ(), HouseholderQR::householderQ(), and ColPivHouseholderQR::householderQ() all return a HouseholderSequence.

More precisely, the class HouseholderSequence represents an $ n \times n $ matrix $ H $ of the form $ H = \prod_{i=0}^{n-1} H_i $ where the i-th Householder reflection is $ H_i = I - h_i v_i v_i^* $. The i-th Householder coefficient $ h_i $ is a scalar and the i-th Householder vector $v_i $ is a vector of the form

\[v_i = [\underbrace{0, \ldots, 0}_{i-1\mbox{ zeros}}, 1, \underbrace{*, \ldots,*}_{n-i\mbox{ arbitrary entries}} ]. \]

The last $ n-i $ entries of $ v_i $ are called the essential part of the Householder vector.

Typical usages are listed below, where H is a HouseholderSequence:

A.applyOnTheRight(H); // A = A * H
A.applyOnTheLeft(H); // A = H * A
A.applyOnTheRight(H.adjoint()); // A = A * H^*
A.applyOnTheLeft(H.adjoint()); // A = H^* * A
MatrixXd Q = H; // conversion to a dense matrix
Eigen::MatrixXd
Matrix< double, Dynamic, Dynamic > MatrixXd
Dynamic×Dynamic matrix of type double.
Definition Matrix.h:479

In addition to the adjoint, you can also apply the inverse (=adjoint), the transpose, and the conjugate operators.

See the documentation for HouseholderSequence(const VectorsType&, const CoeffsType&) for an example.

See also
MatrixBase::applyOnTheLeft(), MatrixBase::applyOnTheRight()
+ Inheritance diagram for Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >:

Public Member Functions

AdjointReturnType adjoint () const
 Adjoint (conjugate transpose) of the Householder sequence.
 
EIGEN_CONSTEXPR Index cols () const EIGEN_NOEXCEPT
 Number of columns of transformation viewed as a matrix.
 
ConjugateReturnType conjugate () const
 Complex conjugate of the Householder sequence.
 
template<bool Cond>
std::conditional_t< Cond, ConjugateReturnType, ConstHouseholderSequence > conjugateIf () const
 
const EssentialVectorType essentialVector (Index k) const
 Essential part of a Householder vector.
 
 HouseholderSequence (const HouseholderSequence &other)
 Copy constructor.
 
 HouseholderSequence (const VectorsType &v, const CoeffsType &h)
 Constructor.
 
AdjointReturnType inverse () const
 Inverse of the Householder sequence (equals the adjoint).
 
Index length () const
 Returns the length of the Householder sequence.
 
template<typename OtherDerived>
internal::matrix_type_times_scalar_type< Scalar, OtherDerived >::Type operator* (const MatrixBase< OtherDerived > &other) const
 Computes the product of a Householder sequence with a matrix.
 
EIGEN_CONSTEXPR Index rows () const EIGEN_NOEXCEPT
 Number of rows of transformation viewed as a matrix.
 
HouseholderSequence & setLength (Index length)
 Sets the length of the Householder sequence.
 
HouseholderSequence & setShift (Index shift)
 Sets the shift of the Householder sequence.
 
Index shift () const
 Returns the shift of the Householder sequence.
 
TransposeReturnType transpose () const
 Transpose of the Householder sequence.
 
- Public Member Functions inherited from Eigen::EigenBase< HouseholderSequence< VectorsType, CoeffsType, Side > >
EIGEN_CONSTEXPR Index cols () const EIGEN_NOEXCEPT
 
constexpr HouseholderSequence< VectorsType, CoeffsType, Side > & derived ()
 
constexpr const HouseholderSequence< VectorsType, CoeffsType, Side > & derived () const
 
EIGEN_CONSTEXPR Index rows () const EIGEN_NOEXCEPT
 
EIGEN_CONSTEXPR Index size () const EIGEN_NOEXCEPT
 

Additional Inherited Members

- Public Types inherited from Eigen::EigenBase< HouseholderSequence< VectorsType, CoeffsType, Side > >
typedef Eigen::Index Index
 The interface type of indices.
 

Constructor & Destructor Documentation

◆ HouseholderSequence()

template<typename VectorsType, typename CoeffsType, int Side>
Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::HouseholderSequence ( const VectorsType & v,
const CoeffsType & h )
inline

Constructor.

Parameters
[in]vMatrix containing the essential parts of the Householder vectors
[in]hVector containing the Householder coefficients

Constructs the Householder sequence with coefficients given by h and vectors given by v. The i-th Householder coefficient $ h_i $ is given by h(i) and the essential part of the i-th Householder vector $ v_i $ is given by v(k,i) with k > i (the subdiagonal part of the i-th column). If v has fewer columns than rows, then the Householder sequence contains as many Householder reflections as there are columns.

Note
The HouseholderSequence object stores v and h by reference.

Example:

Matrix3d v = Matrix3d::Random();
cout << "The matrix v is:" << endl;
cout << v << endl;
Vector3d v0(1, v(1, 0), v(2, 0));
cout << "The first Householder vector is: v_0 = " << v0.transpose() << endl;
Vector3d v1(0, 1, v(2, 1));
cout << "The second Householder vector is: v_1 = " << v1.transpose() << endl;
Vector3d v2(0, 0, 1);
cout << "The third Householder vector is: v_2 = " << v2.transpose() << endl;
Vector3d h = Vector3d::Random();
cout << "The Householder coefficients are: h = " << h.transpose() << endl;
Matrix3d H0 = Matrix3d::Identity() - h(0) * v0 * v0.adjoint();
cout << "The first Householder reflection is represented by H_0 = " << endl;
cout << H0 << endl;
Matrix3d H1 = Matrix3d::Identity() - h(1) * v1 * v1.adjoint();
cout << "The second Householder reflection is represented by H_1 = " << endl;
cout << H1 << endl;
Matrix3d H2 = Matrix3d::Identity() - h(2) * v2 * v2.adjoint();
cout << "The third Householder reflection is represented by H_2 = " << endl;
cout << H2 << endl;
cout << "Their product is H_0 H_1 H_2 = " << endl;
cout << H0 * H1 * H2 << endl;
HouseholderSequence<Matrix3d, Vector3d> hhSeq(v, h);
Matrix3d hhSeqAsMatrix(hhSeq);
cout << "If we construct a HouseholderSequence from v and h" << endl;
cout << "and convert it to a matrix, we get:" << endl;
cout << hhSeqAsMatrix << endl;
Eigen::Vector3d
Matrix< double, 3, 1 > Vector3d
3×1 vector of type double.
Definition Matrix.h:479
Eigen::Matrix3d
Matrix< double, 3, 3 > Matrix3d
3×3 matrix of type double.
Definition Matrix.h:479

Output: 

The matrix v is:
 0.696  0.334  0.445
 0.205  -0.47 -0.633
-0.415  0.928 0.0241
The first Householder vector is: v_0 =      1  0.205 -0.415
The second Householder vector is: v_1 =     0     1 0.928
The third Householder vector is: v_2 = 0 0 1
The Householder coefficients are: h = 0.0723  0.432 -0.046
The first Householder reflection is represented by H_0 = 
  0.928 -0.0148    0.03
-0.0148   0.997 0.00615
   0.03 0.00615   0.988
The second Householder reflection is represented by H_1 = 
     1      0      0
     0  0.568 -0.401
     0 -0.401  0.628
The third Householder reflection is represented by H_2 = 
   1    0    0
   0    1    0
   0    0 1.05
Their product is H_0 H_1 H_2 = 
  0.928 -0.0204  0.0259
-0.0148   0.564  -0.414
   0.03  -0.392   0.646
If we construct a HouseholderSequence from v and h
and convert it to a matrix, we get:
  0.928 -0.0204  0.0259
-0.0148   0.564  -0.414
   0.03  -0.392   0.646
See also
setLength(), setShift()

Member Function Documentation

◆ cols()

template<typename VectorsType, typename CoeffsType, int Side>
EIGEN_CONSTEXPR Index Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::cols ( ) const
inline

Number of columns of transformation viewed as a matrix.

Returns
Number of columns

This equals the dimension of the space that the transformation acts on.

◆ conjugateIf()

template<typename VectorsType, typename CoeffsType, int Side>
template<bool Cond>
std::conditional_t< Cond, ConjugateReturnType, ConstHouseholderSequence > Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::conjugateIf ( ) const
inline
Returns
an expression of the complex conjugate of *this if Cond==true, returns *this otherwise.

◆ essentialVector()

template<typename VectorsType, typename CoeffsType, int Side>
const EssentialVectorType Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::essentialVector ( Index k) const
inline

Essential part of a Householder vector.

Parameters
[in]kIndex of Householder reflection
Returns
Vector containing non-trivial entries of k-th Householder vector

This function returns the essential part of the Householder vector $ v_i $. This is a vector of length $ n-i $ containing the last $ n-i $ entries of the vector

\[v_i = [\underbrace{0, \ldots, 0}_{i-1\mbox{ zeros}}, 1, \underbrace{*, \ldots,*}_{n-i\mbox{ arbitrary entries}} ]. \]

The index $ i $ equals k + shift(), corresponding to the k-th column of the matrix v passed to the constructor.

See also
setShift(), shift()

◆ operator*()

template<typename VectorsType, typename CoeffsType, int Side>
template<typename OtherDerived>
internal::matrix_type_times_scalar_type< Scalar, OtherDerived >::Type Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::operator* ( const MatrixBase< OtherDerived > & other) const
inline

Computes the product of a Householder sequence with a matrix.

Parameters
[in]otherMatrix being multiplied.
Returns
Expression object representing the product.

This function computes $ HM $ where $ H $ is the Householder sequence represented by *this and $ M $ is the matrix other.

◆ rows()

template<typename VectorsType, typename CoeffsType, int Side>
EIGEN_CONSTEXPR Index Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::rows ( ) const
inline

Number of rows of transformation viewed as a matrix.

Returns
Number of rows

This equals the dimension of the space that the transformation acts on.

◆ setLength()

template<typename VectorsType, typename CoeffsType, int Side>
HouseholderSequence & Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::setLength ( Index length)
inline

Sets the length of the Householder sequence.

Parameters
[in]lengthNew value for the length.

By default, the length $ n $ of the Householder sequence $ H = H_0 H_1 \ldots H_{n-1} $ is set to the number of columns of the matrix v passed to the constructor, or the number of rows if that is smaller. After this function is called, the length equals length.

See also
length()

◆ setShift()

template<typename VectorsType, typename CoeffsType, int Side>
HouseholderSequence & Eigen::HouseholderSequence< VectorsType, CoeffsType, Side >::setShift ( Index shift)
inline

Sets the shift of the Householder sequence.

Parameters
[in]shiftNew value for the shift.

By default, a HouseholderSequence object represents $ H = H_0 H_1 \ldots H_{n-1} $ and the i-th column of the matrix v passed to the constructor corresponds to the i-th Householder reflection. After this function is called, the object represents $ H = H_{\mathrm{shift}} H_{\mathrm{shift}+1} \ldots H_{n-1} $ and the i-th column of v corresponds to the (shift+i)-th Householder reflection.

See also
shift()
The documentation for this class was generated from the following files: