ComplexEigenSolver.h

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2009 Claire Maurice
// Copyright (C) 2009 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_COMPLEX_EIGEN_SOLVER_H
#define EIGEN_COMPLEX_EIGEN_SOLVER_H
 
#include "./ComplexSchur.h"
 
// IWYU pragma: private
#include "./InternalHeaderCheck.h"
 
namespace Eigen {

template <typename MatrixType_>
class ComplexEigenSolver {
 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 ComplexScalar = internal::make_complex_t<Scalar>;

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

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

  ComplexEigenSolver() : m_eivec(), m_eivalues(), m_schur(), m_isInitialized(false), m_eigenvectorsOk(false) {}

  explicit ComplexEigenSolver(Index size)
      : m_eivec(size, size), m_eivalues(size), m_schur(size), m_isInitialized(false), m_eigenvectorsOk(false) {}

  template <typename InputType>
  explicit ComplexEigenSolver(const EigenBase<InputType>& matrix, bool computeEigenvectors = true)
      : m_eivec(matrix.rows(), matrix.cols()),
        m_eivalues(matrix.cols()),
        m_schur(matrix.derived(), computeEigenvectors),
        m_isInitialized(false),
        m_eigenvectorsOk(false) {
    computeFromSchur(computeEigenvectors);
  }

  template <typename InputType>
  explicit ComplexEigenSolver(EigenBase<InputType>& matrix, bool computeEigenvectors = true)
      : m_eivec(matrix.rows(), matrix.cols()),
        m_eivalues(matrix.cols()),
        m_schur(matrix.derived(), computeEigenvectors),
        m_isInitialized(false),
        m_eigenvectorsOk(false) {
    computeFromSchur(computeEigenvectors);
  }

  const EigenvectorType& eigenvectors() const {
    eigen_assert(m_isInitialized && "ComplexEigenSolver is not initialized.");
    eigen_assert(m_eigenvectorsOk && "The eigenvectors have not been computed together with the eigenvalues.");
    return m_eivec;
  }

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

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

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

  ComplexEigenSolver& setMaxIterations(Index maxIters) {
    m_schur.setMaxIterations(maxIters);
    return *this;
  }

  Index getMaxIterations() const { return m_schur.getMaxIterations(); }
 
 protected:
  EIGEN_STATIC_ASSERT_NON_INTEGER(Scalar)
 
  EigenvectorType m_eivec;
  EigenvalueType m_eivalues;
  // Holds the Schur form of the last matrix; computing the eigenvectors overwrites T with the eigenvectors of T.
  ComplexSchur<MatrixType> m_schur;
  bool m_isInitialized;
  bool m_eigenvectorsOk;
 
 private:
  ComplexEigenSolver& computeFromSchur(bool computeEigenvectors);
  void doComputeEigenvectors(RealScalar matrixnorm);
  void sortEigenvalues(bool computeEigenvectors);
};
 
template <typename MatrixType>
template <typename InputType>
ComplexEigenSolver<MatrixType>& ComplexEigenSolver<MatrixType>::compute(const EigenBase<InputType>& matrix,
                                                                        bool computeEigenvectors) {
  // this code is inspired from Jampack
  eigen_assert(matrix.cols() == matrix.rows());
 
  // Do a complex Schur decomposition, A = U T U^*
  // The eigenvalues are on the diagonal of T.
  m_schur.compute(matrix.derived(), computeEigenvectors);
  return computeFromSchur(computeEigenvectors);
}

template <typename MatrixType>
ComplexEigenSolver<MatrixType>& ComplexEigenSolver<MatrixType>::computeFromSchur(bool computeEigenvectors) {
  if (m_schur.info() == Success) {
    m_eivalues = m_schur.matrixT().diagonal();
    if (computeEigenvectors) doComputeEigenvectors(m_schur.matrixT().norm());
    sortEigenvalues(computeEigenvectors);
  }
 
  m_isInitialized = true;
  m_eigenvectorsOk = computeEigenvectors;
  return *this;
}
 
template <typename MatrixType>
void ComplexEigenSolver<MatrixType>::doComputeEigenvectors(RealScalar matrixnorm) {
  const Index n = m_eivalues.size();
 
  // Compute X such that T = X D X^(-1), where D is the diagonal of T.
  // The matrix X is unit triangular. It overwrites T column by column from the last one: X(i,k) reads T(i,k) before
  // replacing it, T(i,i+1..k-1) and T(i,i), T(k,k), which lie in columns not yet overwritten, and X(i+1..k-1,k),
  // already computed.
  typename ComplexSchur<MatrixType>::MatrixTType& matX = m_schur.m_matT;
  matX.template triangularView<StrictlyLower>().setZero();
  for (Index k = n - 1; k >= 0; k--) {
    // Compute X(i,k) using the (i,k) entry of the equation X T = D X
    for (Index i = k - 1; i >= 0; i--) {
      matX.coeffRef(i, k) = -matX.coeff(i, k);
      if (k - i - 1 > 0)
        matX.coeffRef(i, k) -= (matX.row(i).segment(i + 1, k - i - 1) * matX.col(k).segment(i + 1, k - i - 1)).value();
      ComplexScalar z = matX.coeff(i, i) - matX.coeff(k, k);
      if (z == ComplexScalar(0)) {
        // If the i-th and k-th eigenvalue are equal, then z equals 0.
        // Use a small value instead, to prevent division by zero.
        numext::real_ref(z) = numext::maxi(std::numeric_limits<RealScalar>::epsilon() * matrixnorm,
                                           (std::numeric_limits<RealScalar>::min)());
      }
      matX.coeffRef(i, k) /= z;
    }
    matX.coeffRef(k, k) = ComplexScalar(1.0, 0.0);
  }
 
  // Compute V as V = U X; now A = U T U^* = U X D X^(-1) U^* = V D V^(-1)
  m_eivec.noalias() = m_schur.matrixU() * matX;
  // .. and normalize the eigenvectors
  for (Index k = 0; k < n; k++) {
    m_eivec.col(k).stableNormalize();
  }
}
 
template <typename MatrixType>
void ComplexEigenSolver<MatrixType>::sortEigenvalues(bool computeEigenvectors) {
  const Index n = m_eivalues.size();
  for (Index i = 0; i < n; i++) {
    Index k;
    m_eivalues.cwiseAbs().tail(n - i).minCoeff(&k);
    if (k != 0) {
      k += i;
      std::swap(m_eivalues[k], m_eivalues[i]);
      if (computeEigenvectors) m_eivec.col(i).swap(m_eivec.col(k));
    }
  }
}
 
}  // end namespace Eigen
 
#endif  // EIGEN_COMPLEX_EIGEN_SOLVER_H