EigenSolver.h

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
// Copyright (C) 2010,2012 Jitse Niesen <jitse@maths.leeds.ac.uk>
//
// This Source Code Form is subject to the terms of the Mozilla
// Public License v. 2.0. If a copy of the MPL was not distributed
// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0
 
#ifndef EIGEN_EIGENSOLVER_H
#define EIGEN_EIGENSOLVER_H
 
#include "./RealSchur.h"
 
// IWYU pragma: private
#include "./InternalHeaderCheck.h"
 
namespace Eigen {

template <typename MatrixType_>
class EigenSolver {
 public:
  using MatrixType = MatrixType_;
 
  enum {
    RowsAtCompileTime = MatrixType::RowsAtCompileTime,
    ColsAtCompileTime = MatrixType::ColsAtCompileTime,
    Options = internal::plain_object_options<MatrixType>::value,
    MaxRowsAtCompileTime = MatrixType::MaxRowsAtCompileTime,
    MaxColsAtCompileTime = MatrixType::MaxColsAtCompileTime
  };

  using Scalar = typename MatrixType::Scalar;
  using RealScalar = typename NumTraits<Scalar>::Real;
  using Index = Eigen::Index;  

  using PlainMatrixType =
      Matrix<Scalar, RowsAtCompileTime, ColsAtCompileTime, Options, MaxRowsAtCompileTime, MaxColsAtCompileTime>;

  using ComplexScalar = internal::make_complex_t<Scalar>;

  using EigenvalueType = Matrix<ComplexScalar, ColsAtCompileTime, 1, Options & ~RowMajor, MaxColsAtCompileTime, 1>;

  using EigenvectorsType =
      Matrix<ComplexScalar, RowsAtCompileTime, ColsAtCompileTime, Options, MaxRowsAtCompileTime, MaxColsAtCompileTime>;

  EigenSolver() : m_eivalues(), m_isInitialized(false), m_eigenvectorsOk(false), m_realSchur(), m_tmp() {}

  explicit EigenSolver(Index size)
      : m_eivalues(size), m_isInitialized(false), m_eigenvectorsOk(false), m_realSchur(size), m_tmp(size) {}

  template <typename InputType>
  explicit EigenSolver(const EigenBase<InputType>& matrix, bool computeEigenvectors = true)
      : m_eivalues(matrix.cols()),
        m_isInitialized(false),
        m_eigenvectorsOk(false),
        m_realSchur(matrix.derived(), computeEigenvectors),
        m_tmp(matrix.cols()) {
    check_template_parameters();
    computeFromSchur(computeEigenvectors);
  }

  template <typename InputType>
  explicit EigenSolver(EigenBase<InputType>& matrix, bool computeEigenvectors = true)
      : m_eivalues(matrix.cols()),
        m_isInitialized(false),
        m_eigenvectorsOk(false),
        m_realSchur(matrix.derived(), computeEigenvectors),
        m_tmp(matrix.cols()) {
    check_template_parameters();
    computeFromSchur(computeEigenvectors);
  }

  EigenvectorsType eigenvectors() const;

  const PlainMatrixType& pseudoEigenvectors() const {
    eigen_assert(m_isInitialized && "EigenSolver is not initialized.");
    eigen_assert(m_eigenvectorsOk && "The eigenvectors have not been computed together with the eigenvalues.");
    return m_realSchur.m_matU;
  }

  PlainMatrixType pseudoEigenvalueMatrix() const;

  const EigenvalueType& eigenvalues() const {
    eigen_assert(m_isInitialized && "EigenSolver is not initialized.");
    return m_eivalues;
  }

  template <typename InputType>
  EigenSolver& compute(const EigenBase<InputType>& matrix, bool computeEigenvectors = true);

  ComputationInfo info() const {
    eigen_assert(m_isInitialized && "EigenSolver is not initialized.");
    return m_info;
  }

  EigenSolver& setMaxIterations(Index maxIters) {
    m_realSchur.setMaxIterations(maxIters);
    return *this;
  }

  Index getMaxIterations() const { return m_realSchur.getMaxIterations(); }
 
 private:
  EigenSolver& computeFromSchur(bool computeEigenvectors);
  void doComputeEigenvectors();
 
 protected:
  static void check_template_parameters() {
    EIGEN_STATIC_ASSERT_NON_INTEGER(Scalar);
    EIGEN_STATIC_ASSERT(!NumTraits<Scalar>::IsComplex, NUMERIC_TYPE_MUST_BE_REAL);
  }
 
  EigenvalueType m_eivalues;
  bool m_isInitialized;
  bool m_eigenvectorsOk;
  ComputationInfo m_info;
  // Holds the Schur form T and U of the last matrix; computing the eigenvectors overwrites T with the eigenvectors
  // of T and U with the pseudo-eigenvectors.
  RealSchur<MatrixType> m_realSchur;
 
  using ColumnVectorType = Matrix<Scalar, ColsAtCompileTime, 1, Options & ~RowMajor, MaxColsAtCompileTime, 1>;
  ColumnVectorType m_tmp;
};
 
template <typename MatrixType>
typename EigenSolver<MatrixType>::PlainMatrixType EigenSolver<MatrixType>::pseudoEigenvalueMatrix() const {
  eigen_assert(m_isInitialized && "EigenSolver is not initialized.");
  const RealScalar precision = RealScalar(2) * NumTraits<RealScalar>::epsilon();
  const Index n = m_eivalues.rows();
  PlainMatrixType matD = PlainMatrixType::Zero(n, n);
  Index i = 0;
  for (; i < n - 1; ++i) {
    RealScalar real = numext::real(m_eivalues.coeff(i));
    RealScalar imag = numext::imag(m_eivalues.coeff(i));
    matD.coeffRef(i, i) = real;
    if (!internal::isMuchSmallerThan(imag, real, precision)) {
      matD.coeffRef(i, i + 1) = imag;
      matD.coeffRef(i + 1, i) = -imag;
      matD.coeffRef(i + 1, i + 1) = real;
      ++i;
    }
  }
  if (i == n - 1) {
    matD.coeffRef(i, i) = numext::real(m_eivalues.coeff(i));
  }
 
  return matD;
}
 
template <typename MatrixType>
typename EigenSolver<MatrixType>::EigenvectorsType EigenSolver<MatrixType>::eigenvectors() const {
  eigen_assert(m_isInitialized && "EigenSolver is not initialized.");
  eigen_assert(m_eigenvectorsOk && "The eigenvectors have not been computed together with the eigenvalues.");
  const RealScalar precision = RealScalar(2) * NumTraits<RealScalar>::epsilon();
  const PlainMatrixType& eivec = m_realSchur.m_matU;
  Index n = eivec.cols();
  EigenvectorsType matV(n, n);
  for (Index j = 0; j < n; ++j) {
    if (internal::isMuchSmallerThan(numext::imag(m_eivalues.coeff(j)), numext::real(m_eivalues.coeff(j)), precision) ||
        j + 1 == n) {
      // we have a real eigen value
      matV.col(j) = eivec.col(j).template cast<ComplexScalar>();
      matV.col(j).normalize();
    } else {
      // we have a pair of complex eigen values
      for (Index i = 0; i < n; ++i) {
        matV.coeffRef(i, j) = ComplexScalar(eivec.coeff(i, j), eivec.coeff(i, j + 1));
        matV.coeffRef(i, j + 1) = ComplexScalar(eivec.coeff(i, j), -eivec.coeff(i, j + 1));
      }
      matV.col(j).normalize();
      matV.col(j + 1).normalize();
      ++j;
    }
  }
  return matV;
}
 
template <typename MatrixType>
template <typename InputType>
EigenSolver<MatrixType>& EigenSolver<MatrixType>::compute(const EigenBase<InputType>& matrix,
                                                          bool computeEigenvectors) {
  check_template_parameters();
  eigen_assert(matrix.cols() == matrix.rows());
 
  // Reduce to real Schur form.
  m_realSchur.compute(matrix.derived(), computeEigenvectors);
  return computeFromSchur(computeEigenvectors);
}

template <typename MatrixType>
EigenSolver<MatrixType>& EigenSolver<MatrixType>::computeFromSchur(bool computeEigenvectors) {
  using numext::isfinite;
 
  m_info = m_realSchur.info();
 
  if (m_info == Success) {
    const MatrixType& matT = m_realSchur.m_matT;
    const Index n = matT.cols();
 
    // Compute eigenvalues from matT
    m_eivalues.resize(n);
    Index i = 0;
    while (i < n) {
      if (i == n - 1 || matT.coeff(i + 1, i) == Scalar(0)) {
        m_eivalues.coeffRef(i) = matT.coeff(i, i);
        if (!(isfinite)(m_eivalues.coeffRef(i))) {
          m_isInitialized = true;
          m_eigenvectorsOk = false;
          m_info = NumericalIssue;
          return *this;
        }
        ++i;
      } else {
        Scalar p = Scalar(0.5) * (matT.coeff(i, i) - matT.coeff(i + 1, i + 1));
        Scalar z;
        // Compute z = sqrt(abs(p * p + matT.coeff(i+1, i) * matT.coeff(i, i+1)));
        // without overflow
        {
          Scalar t0 = matT.coeff(i + 1, i);
          Scalar t1 = matT.coeff(i, i + 1);
          Scalar maxval = numext::maxi<Scalar>(numext::abs(p), numext::maxi<Scalar>(numext::abs(t0), numext::abs(t1)));
          t0 /= maxval;
          t1 /= maxval;
          Scalar p0 = p / maxval;
          z = maxval * numext::sqrt(numext::abs(p0 * p0 + t0 * t1));
        }
 
        m_eivalues.coeffRef(i) = ComplexScalar(matT.coeff(i + 1, i + 1) + p, z);
        m_eivalues.coeffRef(i + 1) = ComplexScalar(matT.coeff(i + 1, i + 1) + p, -z);
        if (!((isfinite)(m_eivalues.coeffRef(i)) && (isfinite)(m_eivalues.coeffRef(i + 1)))) {
          m_isInitialized = true;
          m_eigenvectorsOk = false;
          m_info = NumericalIssue;
          return *this;
        }
        i += 2;
      }
    }
 
    // Compute eigenvectors.
    if (computeEigenvectors) doComputeEigenvectors();
  } else if (!m_realSchur.m_matT.allFinite()) {
    // RealSchur reports both nonfinite input and iteration exhaustion as NoConvergence.
    m_info = NumericalIssue;
  }
 
  m_isInitialized = true;
  m_eigenvectorsOk = computeEigenvectors;
 
  return *this;
}
 
template <typename MatrixType>
void EigenSolver<MatrixType>::doComputeEigenvectors() {
  // Back-substitution stores the eigenvectors of T over T itself; the back-transformation then turns U into the
  // pseudo-eigenvectors in place, column by column from the last one.
  MatrixType& matT = m_realSchur.m_matT;
  PlainMatrixType& eivec = m_realSchur.m_matU;
  const Index size = eivec.cols();
  const Scalar eps = NumTraits<Scalar>::epsilon();
 
  const Scalar norm = internal::hessenberg_abs_sum<Upper>(matT);
 
  // Backsubstitute to find vectors of upper triangular form
  if (norm == Scalar(0)) {
    return;
  }
 
  for (Index n = size - 1; n >= 0; n--) {
    Scalar p = m_eivalues.coeff(n).real();
    Scalar q = m_eivalues.coeff(n).imag();
 
    // Scalar vector
    if (q == Scalar(0)) {
      Scalar lastr(0), lastw(0);
      Index l = n;
 
      matT.coeffRef(n, n) = Scalar(1);
      for (Index i = n - 1; i >= 0; i--) {
        Scalar w = matT.coeff(i, i) - p;
        Scalar r = matT.row(i).segment(l, n - l + 1).dot(matT.col(n).segment(l, n - l + 1));
 
        if (m_eivalues.coeff(i).imag() < Scalar(0)) {
          lastw = w;
          lastr = r;
        } else {
          l = i;
          if (m_eivalues.coeff(i).imag() == Scalar(0)) {
            if (w != Scalar(0))
              matT.coeffRef(i, n) = -r / w;
            else
              matT.coeffRef(i, n) = -r / (eps * norm);
          } else  // Solve real equations
          {
            Scalar x = matT.coeff(i, i + 1);
            Scalar y = matT.coeff(i + 1, i);
            Scalar denom = (m_eivalues.coeff(i).real() - p) * (m_eivalues.coeff(i).real() - p) +
                           m_eivalues.coeff(i).imag() * m_eivalues.coeff(i).imag();
            Scalar t = (x * lastr - lastw * r) / denom;
            matT.coeffRef(i, n) = t;
            if (numext::abs(x) > numext::abs(lastw))
              matT.coeffRef(i + 1, n) = (-r - w * t) / x;
            else
              matT.coeffRef(i + 1, n) = (-lastr - y * t) / lastw;
          }
 
          // Overflow control
          Scalar t = numext::abs(matT.coeff(i, n));
          if ((eps * t) * t > Scalar(1)) matT.col(n).tail(size - i) /= t;
        }
      }
    } else if (q < Scalar(0) && n > 0)  // Complex vector
    {
      Scalar lastra(0), lastsa(0), lastw(0);
      Index l = n - 1;
 
      // Last vector component imaginary so matrix is triangular
      if (numext::abs(matT.coeff(n, n - 1)) > numext::abs(matT.coeff(n - 1, n))) {
        matT.coeffRef(n - 1, n - 1) = q / matT.coeff(n, n - 1);
        matT.coeffRef(n - 1, n) = -(matT.coeff(n, n) - p) / matT.coeff(n, n - 1);
      } else {
        ComplexScalar cc =
            ComplexScalar(Scalar(0), -matT.coeff(n - 1, n)) / ComplexScalar(matT.coeff(n - 1, n - 1) - p, q);
        matT.coeffRef(n - 1, n - 1) = numext::real(cc);
        matT.coeffRef(n - 1, n) = numext::imag(cc);
      }
      matT.coeffRef(n, n - 1) = Scalar(0);
      matT.coeffRef(n, n) = Scalar(1);
      for (Index i = n - 2; i >= 0; i--) {
        Scalar ra = matT.row(i).segment(l, n - l + 1).dot(matT.col(n - 1).segment(l, n - l + 1));
        Scalar sa = matT.row(i).segment(l, n - l + 1).dot(matT.col(n).segment(l, n - l + 1));
        Scalar w = matT.coeff(i, i) - p;
 
        if (m_eivalues.coeff(i).imag() < Scalar(0)) {
          lastw = w;
          lastra = ra;
          lastsa = sa;
        } else {
          l = i;
          if (m_eivalues.coeff(i).imag() == RealScalar(0)) {
            ComplexScalar cc = ComplexScalar(-ra, -sa) / ComplexScalar(w, q);
            matT.coeffRef(i, n - 1) = numext::real(cc);
            matT.coeffRef(i, n) = numext::imag(cc);
          } else {
            // Solve complex equations
            Scalar x = matT.coeff(i, i + 1);
            Scalar y = matT.coeff(i + 1, i);
            Scalar vr = (m_eivalues.coeff(i).real() - p) * (m_eivalues.coeff(i).real() - p) +
                        m_eivalues.coeff(i).imag() * m_eivalues.coeff(i).imag() - q * q;
            Scalar vi = (m_eivalues.coeff(i).real() - p) * Scalar(2) * q;
            if ((vr == Scalar(0)) && (vi == Scalar(0)))
              vr =
                  eps * norm * (numext::abs(w) + numext::abs(q) + numext::abs(x) + numext::abs(y) + numext::abs(lastw));
 
            ComplexScalar cc = ComplexScalar(x * lastra - lastw * ra + q * sa, x * lastsa - lastw * sa - q * ra) /
                               ComplexScalar(vr, vi);
            matT.coeffRef(i, n - 1) = numext::real(cc);
            matT.coeffRef(i, n) = numext::imag(cc);
            if (numext::abs(x) > (numext::abs(lastw) + numext::abs(q))) {
              matT.coeffRef(i + 1, n - 1) = (-ra - w * matT.coeff(i, n - 1) + q * matT.coeff(i, n)) / x;
              matT.coeffRef(i + 1, n) = (-sa - w * matT.coeff(i, n) - q * matT.coeff(i, n - 1)) / x;
            } else {
              cc = ComplexScalar(-lastra - y * matT.coeff(i, n - 1), -lastsa - y * matT.coeff(i, n)) /
                   ComplexScalar(lastw, q);
              matT.coeffRef(i + 1, n - 1) = numext::real(cc);
              matT.coeffRef(i + 1, n) = numext::imag(cc);
            }
          }
 
          // Overflow control
          Scalar t = numext::maxi<Scalar>(numext::abs(matT.coeff(i, n - 1)), numext::abs(matT.coeff(i, n)));
          if ((eps * t) * t > Scalar(1)) matT.block(i, n - 1, size - i, 2) /= t;
        }
      }
 
      // We handled a pair of complex conjugate eigenvalues, so need to skip them both
      n--;
    } else {
      eigen_assert(0 && "Internal bug in EigenSolver (INF or NaN has not been detected)");  // this should not happen
    }
  }
 
  // Back transformation to get eigenvectors of original matrix
  for (Index j = size - 1; j >= 0; j--) {
    m_tmp.noalias() = eivec.leftCols(j + 1) * matT.col(j).segment(0, j + 1);
    eivec.col(j) = m_tmp;
  }
}
 
}  // end namespace Eigen
 
#endif  // EIGEN_EIGENSOLVER_H