Public Types | Public Member Functions | Protected Member Functions | Protected Attributes
HouseholderSequence< VectorsType, CoeffsType, Side > Class Template Reference

Sequence of Householder reflections acting on subspaces with decreasing size. More...

#include <HouseholderSequence.h>

+ Inheritance diagram for HouseholderSequence< VectorsType, CoeffsType, Side >:

List of all members.

Public Types

typedef HouseholderSequence
< VectorsType, typename
internal::conditional
< NumTraits< Scalar >
::IsComplex, typename
internal::remove_all< typename
CoeffsType::ConjugateReturnType >
::type, CoeffsType >::type,
Side > 
ConjugateReturnType
typedef internal::traits
< HouseholderSequence
< VectorsType, CoeffsType,
Side > >::StorageKind 
StorageKind

Public Member Functions

void addTo (Dest &dst) const
ConjugateReturnType adjoint () const
 Adjoint (conjugate transpose) of the Householder sequence.
template<typename Dest >
void applyThisOnTheLeft (Dest &dst) const
template<typename Dest , typename Workspace >
void applyThisOnTheLeft (Dest &dst, Workspace &workspace) const
template<typename Dest >
void applyThisOnTheRight (Dest &dst) const
template<typename Dest , typename Workspace >
void applyThisOnTheRight (Dest &dst, Workspace &workspace) const
Index cols () const
 Number of columns of transformation viewed as a matrix.
ConjugateReturnType conjugate () const
 Complex conjugate of the Householder sequence.
HouseholderSequence
< VectorsType, CoeffsType,
Side > & 
const_cast_derived () const
const HouseholderSequence
< VectorsType, CoeffsType,
Side > & 
const_derived () const
HouseholderSequence
< VectorsType, CoeffsType,
Side > & 
derived ()
const HouseholderSequence
< VectorsType, CoeffsType,
Side > & 
derived () const
const EssentialVectorType essentialVector (Index k) const
 Essential part of a Householder vector.
void evalTo (Dest &dst) const
template<typename DestType >
void evalTo (DestType &dst) const
template<typename Dest , typename Workspace >
void evalTo (Dest &dst, Workspace &workspace) const
 HouseholderSequence (const VectorsType &v, const CoeffsType &h)
 Constructor.
 HouseholderSequence (const HouseholderSequence &other)
 Copy constructor.
ConjugateReturnType 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.
Index rows () const
 Number of rows of transformation viewed as a matrix.
HouseholderSequencesetLength (Index length)
 Sets the length of the Householder sequence.
HouseholderSequencesetShift (Index shift)
 Sets the shift of the Householder sequence.
Index shift () const
 Returns the shift of the Householder sequence.
Index size () const
void subTo (Dest &dst) const
HouseholderSequence transpose () const
 Transpose of the Householder sequence.

Protected Member Functions

HouseholderSequencesetTrans (bool trans)
 Sets the transpose flag.
bool trans () const
 Returns the transpose flag.

Protected Attributes

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

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

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()

Member Typedef Documentation

typedef HouseholderSequence< VectorsType, typename internal::conditional<NumTraits<Scalar>::IsComplex, typename internal::remove_all<typename CoeffsType::ConjugateReturnType>::type, CoeffsType>::type, Side > ConjugateReturnType
typedef internal::traits<HouseholderSequence< VectorsType, CoeffsType, Side > >::StorageKind StorageKind
inherited

Constructor & Destructor Documentation

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:

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;
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
See also:
setLength(), setShift()
HouseholderSequence ( const HouseholderSequence< VectorsType, CoeffsType, Side > &  other)
inline

Copy constructor.


Member Function Documentation

void addTo ( Dest &  dst) const
inlineinherited
ConjugateReturnType adjoint ( ) const
inline
void applyThisOnTheLeft ( Dest &  dst) const
inline
void applyThisOnTheLeft ( Dest &  dst,
Workspace &  workspace 
) const
inline
void applyThisOnTheRight ( Dest &  dst) const
inline
void applyThisOnTheRight ( Dest &  dst,
Workspace &  workspace 
) const
inline
Index cols ( void  ) 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.

Reimplemented from EigenBase< HouseholderSequence< VectorsType, CoeffsType, Side > >.

References HouseholderSequence< VectorsType, CoeffsType, Side >::rows().

Referenced by HouseholderSequence< VectorsType, CoeffsType, Side >::evalTo().

ConjugateReturnType conjugate ( ) const
inline
HouseholderSequence< VectorsType, CoeffsType, Side > & const_cast_derived ( ) const
inlineinherited
const HouseholderSequence< VectorsType, CoeffsType, Side > & const_derived ( ) const
inlineinherited
HouseholderSequence< VectorsType, CoeffsType, Side > & derived ( )
inlineinherited
Returns:
a reference to the derived object
const HouseholderSequence< VectorsType, CoeffsType, Side > & derived ( ) const
inlineinherited
Returns:
a const reference to the derived object
const EssentialVectorType essentialVector ( Index  k) const
inline

Essential part of a Householder vector.

   \param[in]  k  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 \form#74. This is a vector of
   length \form#123 containing the last \form#123 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()

References eigen_assert, and HouseholderSequence< VectorsType, CoeffsType, Side >::m_length.

Referenced by HouseholderSequence< VectorsType, CoeffsType, Side >::applyThisOnTheLeft(), HouseholderSequence< VectorsType, CoeffsType, Side >::applyThisOnTheRight(), and HouseholderSequence< VectorsType, CoeffsType, Side >::evalTo().

void evalTo ( Dest &  dst) const
inlineinherited
void evalTo ( DestType &  dst) const
inline
void evalTo ( Dest &  dst,
Workspace &  workspace 
) const
inline
ConjugateReturnType inverse ( ) const
inline

Inverse of the Householder sequence (equals the adjoint).

References HouseholderSequence< VectorsType, CoeffsType, Side >::adjoint().

Index length ( ) const
inline
internal::matrix_type_times_scalar_type<Scalar, OtherDerived>::Type 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.

References HouseholderSequence< VectorsType, CoeffsType, Side >::applyThisOnTheLeft(), and cast().

Index rows ( void  ) const
inline
HouseholderSequence& 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()

References HouseholderSequence< VectorsType, CoeffsType, Side >::length(), and HouseholderSequence< VectorsType, CoeffsType, Side >::m_length.

Referenced by HouseholderSequence< VectorsType, CoeffsType, Side >::conjugate().

HouseholderSequence& 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()

References HouseholderSequence< VectorsType, CoeffsType, Side >::m_shift, and HouseholderSequence< VectorsType, CoeffsType, Side >::shift().

Referenced by HouseholderSequence< VectorsType, CoeffsType, Side >::conjugate().

HouseholderSequence& setTrans ( bool  trans)
inlineprotected

Sets the transpose flag.

   \param [in]  trans  New value of the transpose flag.

   By default, the transpose flag is not set. If the transpose flag is set, then this object represents 

$ H^T = H_{n-1}^T \ldots H_1^T H_0^T $ instead of $ H = H_0 H_1 \ldots H_{n-1} $.

   \sa trans()

References HouseholderSequence< VectorsType, CoeffsType, Side >::m_trans, and HouseholderSequence< VectorsType, CoeffsType, Side >::trans().

Referenced by HouseholderSequence< VectorsType, CoeffsType, Side >::adjoint(), and HouseholderSequence< VectorsType, CoeffsType, Side >::conjugate().

Index shift ( ) const
inline
Index size ( ) const
inlineinherited
Returns:
the number of coefficients, which is rows()*cols().
See also:
rows(), cols(), SizeAtCompileTime.
void subTo ( Dest &  dst) const
inlineinherited
bool trans ( ) const
inlineprotected
HouseholderSequence transpose ( ) const
inline

Member Data Documentation

CoeffsType::Nested m_coeffs
protected
Index m_length
protected
Index m_shift
protected
bool m_trans
protected
VectorsType::Nested m_vectors
protected

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