View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.linear;
19  
20  
21  /**
22   * An interface to classes that implement an algorithm to calculate the 
23   * eigen decomposition of a real matrix.
24   * <p>The eigen decomposition of matrix A is a set of two matrices:
25   * V and D such that A = V &times; D &times; V<sup>T</sup>.
26   * A, V and D are all m &times; m matrices.</p>
27   * <p>This interface is similar in spirit to the <code>EigenvalueDecomposition</code>
28   * class from the now defunct <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a>
29   * library, with the following changes:</p>
30   * <ul>
31   *   <li>a {@link #getVT() getVt} method has been added,</li>
32   *   <li>two {@link #getRealEigenvalue(int) getRealEigenvalue} and {@link #getImagEigenvalue(int)
33   *   getImagEigenvalue} methods to pick up a single eigenvalue have been added,</li>
34   *   <li>a {@link #getEigenvector(int) getEigenvector} method to pick up a single
35   *   eigenvector has been added,</li>
36   *   <li>a {@link #getDeterminant() getDeterminant} method has been added.</li>
37   *   <li>a {@link #getSolver() getSolver} method has been added.</li>
38   * </ul>
39   * @see <a href="http://mathworld.wolfram.com/EigenDecomposition.html">MathWorld</a>
40   * @see <a href="http://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix">Wikipedia</a>
41   * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
42   * @since 2.0
43   */
44  public interface EigenDecomposition {
45  
46      /**
47       * Returns the matrix V of the decomposition. 
48       * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
49       * <p>The columns of V are the eigenvectors of the original matrix.</p>
50       * @return the V matrix
51       */
52      RealMatrix getV();
53  
54      /**
55       * Returns the block diagonal matrix D of the decomposition. 
56       * <p>D is a block diagonal matrix.</p>
57       * <p>Real eigenvalues are on the diagonal while complex values are on
58       * 2x2 blocks { {real +imaginary}, {-imaginary, real} }.</p>
59       * @return the D matrix
60       * @see #getRealEigenvalues()
61       * @see #getImagEigenvalues()
62       */
63      RealMatrix getD();
64  
65      /**
66       * Returns the transpose of the matrix V of the decomposition. 
67       * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
68       * <p>The columns of V are the eigenvectors of the original matrix.</p>
69       * @return the transpose of the V matrix
70       */
71      RealMatrix getVT();
72  
73      /**
74       * Returns a copy of the real parts of the eigenvalues of the original matrix.
75       * @return a copy of the real parts of the eigenvalues of the original matrix
76       * @see #getD()
77       * @see #getRealEigenvalue(int)
78       * @see #getImagEigenvalues()
79       */
80      double[] getRealEigenvalues();
81  
82      /**
83       * Returns the real part of the i<sup>th</sup> eigenvalue of the original matrix.
84       * @param i index of the eigenvalue (counting from 0)
85       * @return real part of the i<sup>th</sup> eigenvalue of the original matrix
86       * @see #getD()
87       * @see #getRealEigenvalues()
88       * @see #getImagEigenvalue(int)
89       */
90      double getRealEigenvalue(int i);
91  
92      /**
93       * Returns a copy of the imaginary parts of the eigenvalues of the original matrix.
94       * @return a copy of the imaginary parts of the eigenvalues of the original matrix
95       * @see #getD()
96       * @see #getImagEigenvalue(int)
97       * @see #getRealEigenvalues()
98       */
99      double[] getImagEigenvalues();
100 
101     /**
102      * Returns the imaginary part of the i<sup>th</sup> eigenvalue of the original matrix.
103      * @param i index of the eigenvalue (counting from 0)
104      * @return imaginary part of the i<sup>th</sup> eigenvalue of the original matrix
105      * @see #getD()
106      * @see #getImagEigenvalues()
107      * @see #getRealEigenvalue(int)
108      */
109     double getImagEigenvalue(int i);
110 
111     /**
112      * Returns a copy of the i<sup>th</sup> eigenvector of the original matrix.
113      * @param i index of the eigenvector (counting from 0)
114      * @return copy of the i<sup>th</sup> eigenvector of the original matrix
115      * @see #getD()
116      */
117     RealVector getEigenvector(int i);
118 
119     /**
120      * Return the determinant of the matrix
121      * @return determinant of the matrix
122      */
123     double getDeterminant();
124 
125     /**
126      * Get a solver for finding the A &times; X = B solution in exact linear sense.
127      * @return a solver
128      */
129     DecompositionSolver getSolver();
130 
131 }