include/opencascade/math_EigenValuesSearcher.hxx

0001 // Created on: 2005-12-15
0002 // Created by: Julia GERASIMOVA
0003 // Copyright (c) 2005-2014 OPEN CASCADE SAS
0004 //
0005 // This file is part of Open CASCADE Technology software library.
0006 //
0007 // This library is free software; you can redistribute it and/or modify it under
0008 // the terms of the GNU Lesser General Public License version 2.1 as published
0009 // by the Free Software Foundation, with special exception defined in the file
0010 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0011 // distribution for complete text of the license and disclaimer of any warranty.
0012 //
0013 // Alternatively, this file may be used under the terms of Open CASCADE
0014 // commercial license or contractual agreement.
0015
0016 #ifndef _math_EigenValuesSearcher_HeaderFile
0017 #define _math_EigenValuesSearcher_HeaderFile
0018
0019 #include <Standard.hxx>
0020 #include <Standard_DefineAlloc.hxx>
0021 #include <Standard_Handle.hxx>
0022
0023 #include <Standard_Integer.hxx>
0024 #include <NCollection_Array1.hxx>
0025 #include <Standard_Real.hxx>
0026 #include <math_Vector.hxx>
0027 #include <NCollection_Array2.hxx>
0028
0029 //! This class finds eigenvalues and eigenvectors of real symmetric tridiagonal matrices.
0030 //!
0031 //! The implementation uses the QR algorithm with implicit shifts for numerical stability.
0032 //! All computed eigenvalues are real (since the matrix is symmetric), and eigenvectors
0033 //! are orthonormal. The class handles the complete eigendecomposition:
0034 //! A * V = V * D, where A is the input matrix, V contains eigenvectors as columns,
0035 //! and D is diagonal with eigenvalues.
0036 //!
0037 //! Key features:
0038 //! - Robust QR algorithm implementation
0039 //! - Numerical stability through implicit shifts
0040 //! - Complete eigenvalue/eigenvector computation
0041 //! - Proper handling of degenerate cases
0042 class math_EigenValuesSearcher
0043 {
0044 public:
0045   DEFINE_STANDARD_ALLOC
0046
0047   Standard_EXPORT math_EigenValuesSearcher(const NCollection_Array1<double>& theDiagonal,
0048                                            const NCollection_Array1<double>& theSubdiagonal);
0049
0050   //! Returns true if computation is performed successfully.
0051   //! Computation may fail due to numerical issues or invalid input.
0052   Standard_EXPORT bool IsDone() const;
0053
0054   //! Returns the dimension of the tridiagonal matrix.
0055   Standard_EXPORT int Dimension() const;
0056
0057   //! Returns the specified eigenvalue.
0058   //! Eigenvalues are returned in the order they were computed by the algorithm,
0059   //! which may not be sorted. Use sorting if ordered eigenvalues are needed.
0060   //!
0061   //! @param theIndex index of the desired eigenvalue (1-based indexing)
0062   //! @return the eigenvalue at the specified index
0063   Standard_EXPORT double EigenValue(const int theIndex) const;
0064
0065   //! Returns the specified eigenvector.
0066   //! The returned eigenvector is normalized and orthogonal to all other eigenvectors.
0067   //! The eigenvector satisfies: A * v = lambda * v, where A is the original matrix,
0068   //! v is the eigenvector, and lambda is the corresponding eigenvalue.
0069   //!
0070   //! @param theIndex index of the desired eigenvector (1-based indexing)
0071   //! @return the normalized eigenvector corresponding to EigenValue(theIndex)
0072   Standard_EXPORT math_Vector EigenVector(const int theIndex) const;
0073
0074 private:
0075   NCollection_Array1<double> myDiagonal;     //!< Copy of input diagonal elements
0076   NCollection_Array1<double> mySubdiagonal;  //!< Copy of input subdiagonal elements
0077   bool                       myIsDone;       //!< Computation success flag
0078   int                        myN;            //!< Matrix dimension
0079   NCollection_Array1<double> myEigenValues;  //!< Computed eigenvalues
0080   NCollection_Array2<double> myEigenVectors; //!< Computed eigenvectors stored column-wise
0081 };
0082
0083 #endif // _math_EigenValuesSearcher_HeaderFile