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

Sequence of Householder reflections acting on subspaces with decreasing size.

Template parameters
VectorsType type of matrix containing the Householder vectors
CoeffsType type of vector containing the Householder coefficients
Side either OnTheLeft (the default) or OnTheRight

Contents

This is defined in the Householder module. #include <Eigen/Householder>

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

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.

Base classes

template<typename Derived>
class EigenBase

Public types

enum (anonymous) { RowsAtCompileTime = internal::traits<HouseholderSequence>::RowsAtCompileTime, ColsAtCompileTime = internal::traits<HouseholderSequence>::ColsAtCompileTime, MaxRowsAtCompileTime = internal::traits<HouseholderSequence>::MaxRowsAtCompileTime, MaxColsAtCompileTime = internal::traits<HouseholderSequence>::MaxColsAtCompileTime }
using AdjointReturnType = HouseholderSequence<VectorsType, typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename CoeffsType::ConjugateReturnType>::type, CoeffsType>::type, Side>
using ConjugateReturnType = HouseholderSequence<typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename VectorsType::ConjugateReturnType>::type, VectorsType>::type, typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename CoeffsType::ConjugateReturnType>::type, CoeffsType>::type, Side>
using ConstHouseholderSequence = HouseholderSequence<typename internal::add_const<VectorsType>::type, typename internal::add_const<CoeffsType>::type, Side>
using Scalar = internal::traits<HouseholderSequence>::Scalar
using TransposeReturnType = HouseholderSequence<typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename VectorsType::ConjugateReturnType>::type, VectorsType>::type, CoeffsType, Side>

Constructors, destructors, conversion operators

HouseholderSequence(const VectorsType& v, const CoeffsType& h)
Constructor.
HouseholderSequence(const HouseholderSequence& other)
Copy constructor.

Public functions

auto adjoint() const -> AdjointReturnType
Adjoint (conjugate transpose) of the Householder sequence.
template<typename Dest>
void applyThisOnTheLeft(Dest& dst, bool inputIsIdentity = false) const
template<typename Dest, typename Workspace>
void applyThisOnTheLeft(Dest& dst, Workspace& workspace, bool inputIsIdentity = false) const
template<typename Dest>
void applyThisOnTheRight(Dest& dst) const
template<typename Dest, typename Workspace>
void applyThisOnTheRight(Dest& dst, Workspace& workspace) const
auto cols() const -> Index
Number of columns of transformation viewed as a matrix.
auto conjugate() const -> ConjugateReturnType
Complex conjugate of the Householder sequence.
template<bool Cond>
auto conjugateIf() const -> internal::conditional<Cond, ConjugateReturnType, ConstHouseholderSequence>::type
auto essentialVector(Index k) const -> const EssentialVectorType
Essential part of a Householder vector.
template<typename DestType>
void evalTo(DestType& dst) const
template<typename Dest, typename Workspace>
void evalTo(Dest& dst, Workspace& workspace) const
auto inverse() const -> AdjointReturnType
Inverse of the Householder sequence (equals the adjoint).
auto length() const -> Index
Returns the length of the Householder sequence.
template<typename OtherDerived>
auto operator*(const MatrixBase<OtherDerived>& other) const -> internal::matrix_type_times_scalar_type<Scalar, OtherDerived>::Type
Computes the product of a Householder sequence with a matrix.
auto rows() const -> Index
Number of rows of transformation viewed as a matrix.
auto setLength(Index length) -> HouseholderSequence&
Sets the length of the Householder sequence.
auto setShift(Index shift) -> HouseholderSequence&
Sets the shift of the Householder sequence.
auto shift() const -> Index
Returns the shift of the Householder sequence.
auto transpose() const -> TransposeReturnType
Transpose of the Householder sequence.

Protected types

enum (anonymous) { BlockSize = 48 }

Protected functions

auto reverseFlag() const -> bool
auto setReverseFlag(bool reverse) -> HouseholderSequence&

Protected variables

CoeffsType::Nested m_coeffs
Index m_length
bool m_reverse
Index m_shift
VectorsType::Nested m_vectors

Enum documentation

template<typename VectorsType, typename CoeffsType, int Side>
enum Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::(anonymous)

Enumerators
RowsAtCompileTime
ColsAtCompileTime
MaxRowsAtCompileTime
MaxColsAtCompileTime

template<typename VectorsType, typename CoeffsType, int Side>
enum Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::(anonymous) protected

Enumerators
BlockSize

Typedef documentation

template<typename VectorsType, typename CoeffsType, int Side>
typedef HouseholderSequence<VectorsType, typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename CoeffsType::ConjugateReturnType>::type, CoeffsType>::type, Side> Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::AdjointReturnType

template<typename VectorsType, typename CoeffsType, int Side>
typedef HouseholderSequence<typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename VectorsType::ConjugateReturnType>::type, VectorsType>::type, typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename CoeffsType::ConjugateReturnType>::type, CoeffsType>::type, Side> Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::ConjugateReturnType

template<typename VectorsType, typename CoeffsType, int Side>
typedef HouseholderSequence<typename internal::add_const<VectorsType>::type, typename internal::add_const<CoeffsType>::type, Side> Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::ConstHouseholderSequence

template<typename VectorsType, typename CoeffsType, int Side>
typedef internal::traits<HouseholderSequence>::Scalar Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::Scalar

template<typename VectorsType, typename CoeffsType, int Side>
typedef HouseholderSequence<typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename VectorsType::ConjugateReturnType>::type, VectorsType>::type, CoeffsType, Side> Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::TransposeReturnType

Function documentation

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

Constructor.

Parameters
v in Matrix containing the essential parts of the Householder vectors
h in Vector 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.

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;

Output:

The matrix v is:
  0.68  0.597  -0.33
-0.211  0.823  0.536
 0.566 -0.605 -0.444
The first Householder vector is: v_0 =      1 -0.211  0.566
The second Householder vector is: v_1 =      0      1 -0.605
The third Householder vector is: v_2 = 0 0 1
The Householder coefficients are: h =   0.108 -0.0452   0.258
The first Householder reflection is represented by H_0 = 
  0.892  0.0228 -0.0611
 0.0228   0.995  0.0129
-0.0611  0.0129   0.965
The second Householder reflection is represented by H_1 = 
      1       0       0
      0    1.05 -0.0273
      0 -0.0273    1.02
The third Householder reflection is represented by H_2 = 
    1     0     0
    0     1     0
    0     0 0.742
Their product is H_0 H_1 H_2 = 
  0.892  0.0255 -0.0466
 0.0228    1.04 -0.0105
-0.0611 -0.0129   0.728
If we construct a HouseholderSequence from v and h
and convert it to a matrix, we get:
  0.892  0.0255 -0.0466
 0.0228    1.04 -0.0105
-0.0611 -0.0129   0.728

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

Copy constructor.

template<typename VectorsType, typename CoeffsType, int Side>
AdjointReturnType Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::adjoint() const

Adjoint (conjugate transpose) of the Householder sequence.

template<typename VectorsType, typename CoeffsType, int Side> template<typename Dest>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::applyThisOnTheLeft(Dest& dst, bool inputIsIdentity = false) const

template<typename VectorsType, typename CoeffsType, int Side> template<typename Dest, typename Workspace>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::applyThisOnTheLeft(Dest& dst, Workspace& workspace, bool inputIsIdentity = false) const

template<typename VectorsType, typename CoeffsType, int Side> template<typename Dest>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::applyThisOnTheRight(Dest& dst) const

template<typename VectorsType, typename CoeffsType, int Side> template<typename Dest, typename Workspace>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::applyThisOnTheRight(Dest& dst, Workspace& workspace) const

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

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.

template<typename VectorsType, typename CoeffsType, int Side>
ConjugateReturnType Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::conjugate() const

Complex conjugate of the Householder sequence.

template<typename VectorsType, typename CoeffsType, int Side> template<bool Cond>
internal::conditional<Cond, ConjugateReturnType, ConstHouseholderSequence>::type Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::conjugateIf() const

Returns an expression of the complex conjugate of *this if Cond==true, returns *this otherwise.

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

Essential part of a Householder vector.

Parameters
k in Index 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.

template<typename VectorsType, typename CoeffsType, int Side> template<typename DestType>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::evalTo(DestType& dst) const

template<typename VectorsType, typename CoeffsType, int Side> template<typename Dest, typename Workspace>
void Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::evalTo(Dest& dst, Workspace& workspace) const

template<typename VectorsType, typename CoeffsType, int Side>
AdjointReturnType Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::inverse() const

Inverse of the Householder sequence (equals the adjoint).

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

Returns the length of the Householder sequence.

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

Computes the product of a Householder sequence with a matrix.

Parameters
other in Matrix 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.

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

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.

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

Sets the length of the Householder sequence.

Parameters
length in New 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.

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

Sets the shift of the Householder sequence.

Parameters
shift in New 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.

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

Returns the shift of the Householder sequence.

template<typename VectorsType, typename CoeffsType, int Side>
TransposeReturnType Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::transpose() const

Transpose of the Householder sequence.

template<typename VectorsType, typename CoeffsType, int Side>
bool Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::reverseFlag() const protected

template<typename VectorsType, typename CoeffsType, int Side>
HouseholderSequence& Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::setReverseFlag(bool reverse) protected

Variable documentation

template<typename VectorsType, typename CoeffsType, int Side>
CoeffsType::Nested Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::m_coeffs protected

template<typename VectorsType, typename CoeffsType, int Side>
Index Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::m_length protected

template<typename VectorsType, typename CoeffsType, int Side>
bool Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::m_reverse protected

template<typename VectorsType, typename CoeffsType, int Side>
Index Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::m_shift protected

template<typename VectorsType, typename CoeffsType, int Side>
VectorsType::Nested Eigen::HouseholderSequence<VectorsType, CoeffsType, Side>::m_vectors protected