001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math.linear;
019
020
021 /**
022 * An interface to classes that implement an algorithm to calculate the
023 * eigen decomposition of a real matrix.
024 * <p>The eigen decomposition of matrix A is a set of two matrices:
025 * V and D such that A = V × D × V<sup>T</sup>.
026 * A, V and D are all m × m matrices.</p>
027 * <p>This interface is similar in spirit to the <code>EigenvalueDecomposition</code>
028 * class from the <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a>
029 * library, with the following changes:</p>
030 * <ul>
031 * <li>a {@link #getVT() getVt} method has been added,</li>
032 * <li>two {@link #getRealEigenvalue(int) getRealEigenvalue} and {@link #getImagEigenvalue(int)
033 * getImagEigenvalue} methods to pick up a single eigenvalue have been added,</li>
034 * <li>a {@link #getEigenvector(int) getEigenvector} method to pick up a single
035 * eigenvector has been added,</li>
036 * <li>a {@link #getDeterminant() getDeterminant} method has been added.</li>
037 * <li>a {@link #getSolver() getSolver} method has been added.</li>
038 * </ul>
039 * @see <a href="http://mathworld.wolfram.com/EigenDecomposition.html">MathWorld</a>
040 * @see <a href="http://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix">Wikipedia</a>
041 * @version $Revision: 997726 $ $Date: 2010-09-16 14:39:51 +0200 (jeu. 16 sept. 2010) $
042 * @since 2.0
043 */
044 public interface EigenDecomposition {
045
046 /**
047 * Returns the matrix V of the decomposition.
048 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
049 * <p>The columns of V are the eigenvectors of the original matrix.</p>
050 * <p>No assumption is made about the orientation of the system axes formed
051 * by the columns of V (e.g. in a 3-dimension space, V can form a left-
052 * or right-handed system).</p>
053 * @return the V matrix
054 */
055 RealMatrix getV();
056
057 /**
058 * Returns the block diagonal matrix D of the decomposition.
059 * <p>D is a block diagonal matrix.</p>
060 * <p>Real eigenvalues are on the diagonal while complex values are on
061 * 2x2 blocks { {real +imaginary}, {-imaginary, real} }.</p>
062 * @return the D matrix
063 * @see #getRealEigenvalues()
064 * @see #getImagEigenvalues()
065 */
066 RealMatrix getD();
067
068 /**
069 * Returns the transpose of the matrix V of the decomposition.
070 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
071 * <p>The columns of V are the eigenvectors of the original matrix.</p>
072 * <p>No assumption is made about the orientation of the system axes formed
073 * by the columns of V (e.g. in a 3-dimension space, V can form a left-
074 * or right-handed system).</p>
075 * @return the transpose of the V matrix
076 */
077 RealMatrix getVT();
078
079 /**
080 * Returns a copy of the real parts of the eigenvalues of the original matrix.
081 * @return a copy of the real parts of the eigenvalues of the original matrix
082 * @see #getD()
083 * @see #getRealEigenvalue(int)
084 * @see #getImagEigenvalues()
085 */
086 double[] getRealEigenvalues();
087
088 /**
089 * Returns the real part of the i<sup>th</sup> eigenvalue of the original matrix.
090 * @param i index of the eigenvalue (counting from 0)
091 * @return real part of the i<sup>th</sup> eigenvalue of the original matrix
092 * @see #getD()
093 * @see #getRealEigenvalues()
094 * @see #getImagEigenvalue(int)
095 */
096 double getRealEigenvalue(int i);
097
098 /**
099 * Returns a copy of the imaginary parts of the eigenvalues of the original matrix.
100 * @return a copy of the imaginary parts of the eigenvalues of the original matrix
101 * @see #getD()
102 * @see #getImagEigenvalue(int)
103 * @see #getRealEigenvalues()
104 */
105 double[] getImagEigenvalues();
106
107 /**
108 * Returns the imaginary part of the i<sup>th</sup> eigenvalue of the original matrix.
109 * @param i index of the eigenvalue (counting from 0)
110 * @return imaginary part of the i<sup>th</sup> eigenvalue of the original matrix
111 * @see #getD()
112 * @see #getImagEigenvalues()
113 * @see #getRealEigenvalue(int)
114 */
115 double getImagEigenvalue(int i);
116
117 /**
118 * Returns a copy of the i<sup>th</sup> eigenvector of the original matrix.
119 * @param i index of the eigenvector (counting from 0)
120 * @return copy of the i<sup>th</sup> eigenvector of the original matrix
121 * @see #getD()
122 */
123 RealVector getEigenvector(int i);
124
125 /**
126 * Return the determinant of the matrix
127 * @return determinant of the matrix
128 */
129 double getDeterminant();
130
131 /**
132 * Get a solver for finding the A × X = B solution in exact linear sense.
133 * @return a solver
134 */
135 DecompositionSolver getSolver();
136
137 }