Another set of UI messages fixes and tweaks! No functional changes.
[blender.git] / extern / Eigen3 / Eigen / src / Eigenvalues / MatrixBaseEigenvalues.h
1 // This file is part of Eigen, a lightweight C++ template library
2 // for linear algebra.
3 //
4 // Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
5 // Copyright (C) 2010 Jitse Niesen <jitse@maths.leeds.ac.uk>
6 //
7 // Eigen is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU Lesser General Public
9 // License as published by the Free Software Foundation; either
10 // version 3 of the License, or (at your option) any later version.
11 //
12 // Alternatively, you can redistribute it and/or
13 // modify it under the terms of the GNU General Public License as
14 // published by the Free Software Foundation; either version 2 of
15 // the License, or (at your option) any later version.
16 //
17 // Eigen is distributed in the hope that it will be useful, but WITHOUT ANY
18 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
19 // FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License or the
20 // GNU General Public License for more details.
21 //
22 // You should have received a copy of the GNU Lesser General Public
23 // License and a copy of the GNU General Public License along with
24 // Eigen. If not, see <http://www.gnu.org/licenses/>.
25
26 #ifndef EIGEN_MATRIXBASEEIGENVALUES_H
27 #define EIGEN_MATRIXBASEEIGENVALUES_H
28
29 namespace internal {
30
31 template<typename Derived, bool IsComplex>
32 struct eigenvalues_selector
33 {
34   // this is the implementation for the case IsComplex = true
35   static inline typename MatrixBase<Derived>::EigenvaluesReturnType const
36   run(const MatrixBase<Derived>& m)
37   {
38     typedef typename Derived::PlainObject PlainObject;
39     PlainObject m_eval(m);
40     return ComplexEigenSolver<PlainObject>(m_eval, false).eigenvalues();
41   }
42 };
43
44 template<typename Derived>
45 struct eigenvalues_selector<Derived, false>
46 {
47   static inline typename MatrixBase<Derived>::EigenvaluesReturnType const
48   run(const MatrixBase<Derived>& m)
49   {
50     typedef typename Derived::PlainObject PlainObject;
51     PlainObject m_eval(m);
52     return EigenSolver<PlainObject>(m_eval, false).eigenvalues();
53   }
54 };
55
56 } // end namespace internal
57
58 /** \brief Computes the eigenvalues of a matrix 
59   * \returns Column vector containing the eigenvalues.
60   *
61   * \eigenvalues_module
62   * This function computes the eigenvalues with the help of the EigenSolver
63   * class (for real matrices) or the ComplexEigenSolver class (for complex
64   * matrices). 
65   *
66   * The eigenvalues are repeated according to their algebraic multiplicity,
67   * so there are as many eigenvalues as rows in the matrix.
68   *
69   * The SelfAdjointView class provides a better algorithm for selfadjoint
70   * matrices.
71   *
72   * Example: \include MatrixBase_eigenvalues.cpp
73   * Output: \verbinclude MatrixBase_eigenvalues.out
74   *
75   * \sa EigenSolver::eigenvalues(), ComplexEigenSolver::eigenvalues(),
76   *     SelfAdjointView::eigenvalues()
77   */
78 template<typename Derived>
79 inline typename MatrixBase<Derived>::EigenvaluesReturnType
80 MatrixBase<Derived>::eigenvalues() const
81 {
82   typedef typename internal::traits<Derived>::Scalar Scalar;
83   return internal::eigenvalues_selector<Derived, NumTraits<Scalar>::IsComplex>::run(derived());
84 }
85
86 /** \brief Computes the eigenvalues of a matrix
87   * \returns Column vector containing the eigenvalues.
88   *
89   * \eigenvalues_module
90   * This function computes the eigenvalues with the help of the
91   * SelfAdjointEigenSolver class.  The eigenvalues are repeated according to
92   * their algebraic multiplicity, so there are as many eigenvalues as rows in
93   * the matrix.
94   *
95   * Example: \include SelfAdjointView_eigenvalues.cpp
96   * Output: \verbinclude SelfAdjointView_eigenvalues.out
97   *
98   * \sa SelfAdjointEigenSolver::eigenvalues(), MatrixBase::eigenvalues()
99   */
100 template<typename MatrixType, unsigned int UpLo> 
101 inline typename SelfAdjointView<MatrixType, UpLo>::EigenvaluesReturnType
102 SelfAdjointView<MatrixType, UpLo>::eigenvalues() const
103 {
104   typedef typename SelfAdjointView<MatrixType, UpLo>::PlainObject PlainObject;
105   PlainObject thisAsMatrix(*this);
106   return SelfAdjointEigenSolver<PlainObject>(thisAsMatrix, false).eigenvalues();
107 }
108
109
110
111 /** \brief Computes the L2 operator norm
112   * \returns Operator norm of the matrix.
113   *
114   * \eigenvalues_module
115   * This function computes the L2 operator norm of a matrix, which is also
116   * known as the spectral norm. The norm of a matrix \f$ A \f$ is defined to be
117   * \f[ \|A\|_2 = \max_x \frac{\|Ax\|_2}{\|x\|_2} \f]
118   * where the maximum is over all vectors and the norm on the right is the
119   * Euclidean vector norm. The norm equals the largest singular value, which is
120   * the square root of the largest eigenvalue of the positive semi-definite
121   * matrix \f$ A^*A \f$.
122   *
123   * The current implementation uses the eigenvalues of \f$ A^*A \f$, as computed
124   * by SelfAdjointView::eigenvalues(), to compute the operator norm of a
125   * matrix.  The SelfAdjointView class provides a better algorithm for
126   * selfadjoint matrices.
127   *
128   * Example: \include MatrixBase_operatorNorm.cpp
129   * Output: \verbinclude MatrixBase_operatorNorm.out
130   *
131   * \sa SelfAdjointView::eigenvalues(), SelfAdjointView::operatorNorm()
132   */
133 template<typename Derived>
134 inline typename MatrixBase<Derived>::RealScalar
135 MatrixBase<Derived>::operatorNorm() const
136 {
137   typename Derived::PlainObject m_eval(derived());
138   // FIXME if it is really guaranteed that the eigenvalues are already sorted,
139   // then we don't need to compute a maxCoeff() here, comparing the 1st and last ones is enough.
140   return internal::sqrt((m_eval*m_eval.adjoint())
141                  .eval()
142                  .template selfadjointView<Lower>()
143                  .eigenvalues()
144                  .maxCoeff()
145                  );
146 }
147
148 /** \brief Computes the L2 operator norm
149   * \returns Operator norm of the matrix.
150   *
151   * \eigenvalues_module
152   * This function computes the L2 operator norm of a self-adjoint matrix. For a
153   * self-adjoint matrix, the operator norm is the largest eigenvalue.
154   *
155   * The current implementation uses the eigenvalues of the matrix, as computed
156   * by eigenvalues(), to compute the operator norm of the matrix.
157   *
158   * Example: \include SelfAdjointView_operatorNorm.cpp
159   * Output: \verbinclude SelfAdjointView_operatorNorm.out
160   *
161   * \sa eigenvalues(), MatrixBase::operatorNorm()
162   */
163 template<typename MatrixType, unsigned int UpLo>
164 inline typename SelfAdjointView<MatrixType, UpLo>::RealScalar
165 SelfAdjointView<MatrixType, UpLo>::operatorNorm() const
166 {
167   return eigenvalues().cwiseAbs().maxCoeff();
168 }
169
170 #endif