Eigen  5.0.1-dev+master
 
Loading...
Searching...
No Matches
RankRevealingBase.h
1// This file is part of Eigen, a lightweight C++ template library
2// for linear algebra.
3//
4// This Source Code Form is subject to the terms of the Mozilla
5// Public License v. 2.0. If a copy of the MPL was not distributed
6// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
7// SPDX-FileCopyrightText: The Eigen Authors
8// SPDX-License-Identifier: MPL-2.0
9
10#ifndef EIGEN_RANK_REVEALING_BASE_H
11#define EIGEN_RANK_REVEALING_BASE_H
12
13// IWYU pragma: private
14#include "./InternalHeaderCheck.h"
15
16namespace Eigen {
17
18namespace internal {
19
28template <typename BlockType, typename NormsType>
29bool column_norms_with_fallback(const BlockType& block, NormsType& norms) {
30 using RealScalar = typename NumTraits<typename BlockType::Scalar>::Real;
31 norms = block.colwise().norm();
32 if (block.size() == 0) return false;
33 const RealScalar maxnorm = norms.maxCoeff();
34 const RealScalar smallest_accurate =
35 RealScalar(2) * numext::sqrt((std::numeric_limits<RealScalar>::min)() * RealScalar(block.rows())) /
36 NumTraits<RealScalar>::epsilon();
37 // Comparisons against finite bounds, which survive -ffinite-math-only, unlike isfinite().
38 if (EIGEN_PREDICT_FALSE(!(maxnorm >= smallest_accurate && maxnorm <= NumTraits<RealScalar>::highest()))) {
39 norms = block.colwise().stableNorm();
40 return true;
41 }
42 return false;
43}
44
45} // end namespace internal
46
57template <typename Derived>
58class RankRevealingBase {
59 public:
60 using Scalar = typename internal::traits<Derived>::Scalar;
61 using RealScalar = typename NumTraits<Scalar>::Real;
62
63 RankRevealingBase()
64 : m_usePrescribedThreshold(false),
65 m_prescribedThreshold(RealScalar(0)),
66 m_maxpivot(RealScalar(0)),
67 m_nonzero_pivots(0) {}
69 /** Allows to prescribe a threshold to be used by certain methods, such as rank(),
70 * which need to determine when pivots are to be considered nonzero. This is not used for the
71 * decomposition itself, except by CompleteOrthogonalDecomposition, whose rank is determined by compute().
72 *
73 * When it needs to get the threshold value, Eigen calls threshold(). By default, this is
74 * \f$ 4 \, \min(rows, cols) \, \epsilon \f$, where \f$ \epsilon \f$ is \c NumTraits<Scalar>::epsilon() and
75 * \a rows and \a cols are the dimensions of the decomposed matrix.
76 * Once you have called the present method setThreshold(const RealScalar&),
77 * your value is used instead.
78 *
79 * \param threshold The new value to use as the threshold.
80 *
81 * A pivot will be considered nonzero if its absolute value is strictly greater than
82 * \f$ threshold \times \vert maxpivot \vert \f$
83 * where maxpivot is the biggest pivot.
84 *
85 * If you want to come back to the default behavior, call setThreshold(Default_t)
86 */
87 Derived& setThreshold(const RealScalar& threshold) {
88 m_usePrescribedThreshold = true;
89 m_prescribedThreshold = threshold;
90 return self();
91 }
92
101 Derived& setThreshold(Default_t) {
102 m_usePrescribedThreshold = false;
103 return self();
104 }
105
110 RealScalar threshold() const {
111 eigen_assert(self().m_isInitialized || m_usePrescribedThreshold);
112 // Higham's backward error bound: ||ΔA||₂ ≤ c·min(m,n)·u·||A||₂.
113 // The factor of 4 covers the constant c.
114 return m_usePrescribedThreshold
115 ? m_prescribedThreshold
116 : NumTraits<Scalar>::epsilon() * RealScalar(4 * (std::min)(self().rows(), self().cols()));
117 }
118
125 inline Index rank() const {
126 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
127 RealScalar premultiplied_threshold = numext::abs(m_maxpivot) * threshold();
128 Index result = 0;
129 for (Index i = 0; i < m_nonzero_pivots; ++i) result += (self().pivotCoeff(i) > premultiplied_threshold);
130 return result;
131 }
132
139 inline Index dimensionOfKernel() const {
140 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
141 return self().cols() - rank();
144 /** \returns true if the matrix of which *this is the decomposition represents an injective
145 * linear map, i.e. has trivial kernel; false otherwise.
147 * \note This method has to determine which pivots should be considered nonzero.
148 * For that, it uses the threshold value that you can control by calling
149 * setThreshold(const RealScalar&).
150 */
151 inline bool isInjective() const {
152 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
153 return rank() == self().cols();
154 }
155
163 inline bool isSurjective() const {
164 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
165 return rank() == self().rows();
166 }
167
174 inline bool isInvertible() const {
175 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
176 return isInjective() && isSurjective();
177 }
178
186 inline Index nonzeroPivots() const {
187 eigen_assert(self().m_isInitialized && "Decomposition is not initialized.");
188 return m_nonzero_pivots;
189 }
190
194 RealScalar maxPivot() const { return m_maxpivot; }
195
196 protected:
197 bool m_usePrescribedThreshold;
198 RealScalar m_prescribedThreshold;
199 RealScalar m_maxpivot;
200 Index m_nonzero_pivots;
201
202 private:
203 Derived& self() { return static_cast<Derived&>(*this); }
204 const Derived& self() const { return static_cast<const Derived&>(*this); }
205};
206
207} // end namespace Eigen
208
209#endif // EIGEN_RANK_REVEALING_BASE_H
Index dimensionOfKernel() const
Definition RankRevealingBase.h:139
bool isInjective() const
Definition RankRevealingBase.h:151
bool isSurjective() const
Definition RankRevealingBase.h:163
Derived & setThreshold(Default_t)
Definition RankRevealingBase.h:101
Derived & setThreshold(const RealScalar &threshold)
Definition RankRevealingBase.h:87
Index nonzeroPivots() const
Definition RankRevealingBase.h:186
RealScalar threshold() const
Definition RankRevealingBase.h:110
RealScalar maxPivot() const
Definition RankRevealingBase.h:194
Index rank() const
Definition RankRevealingBase.h:125
bool isInvertible() const
Definition RankRevealingBase.h:174