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: 826627 $ $Date: 2009-10-19 06:27:47 -0400 (Mon, 19 Oct 2009) $
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 * @return the V matrix
051 */
052 RealMatrix getV();
053
054 /**
055 * Returns the block diagonal matrix D of the decomposition.
056 * <p>D is a block diagonal matrix.</p>
057 * <p>Real eigenvalues are on the diagonal while complex values are on
058 * 2x2 blocks { {real +imaginary}, {-imaginary, real} }.</p>
059 * @return the D matrix
060 * @see #getRealEigenvalues()
061 * @see #getImagEigenvalues()
062 */
063 RealMatrix getD();
064
065 /**
066 * Returns the transpose of the matrix V of the decomposition.
067 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
068 * <p>The columns of V are the eigenvectors of the original matrix.</p>
069 * @return the transpose of the V matrix
070 */
071 RealMatrix getVT();
072
073 /**
074 * Returns a copy of the real parts of the eigenvalues of the original matrix.
075 * @return a copy of the real parts of the eigenvalues of the original matrix
076 * @see #getD()
077 * @see #getRealEigenvalue(int)
078 * @see #getImagEigenvalues()
079 */
080 double[] getRealEigenvalues();
081
082 /**
083 * Returns the real part of the i<sup>th</sup> eigenvalue of the original matrix.
084 * @param i index of the eigenvalue (counting from 0)
085 * @return real part of the i<sup>th</sup> eigenvalue of the original matrix
086 * @see #getD()
087 * @see #getRealEigenvalues()
088 * @see #getImagEigenvalue(int)
089 */
090 double getRealEigenvalue(int i);
091
092 /**
093 * Returns a copy of the imaginary parts of the eigenvalues of the original matrix.
094 * @return a copy of the imaginary parts of the eigenvalues of the original matrix
095 * @see #getD()
096 * @see #getImagEigenvalue(int)
097 * @see #getRealEigenvalues()
098 */
099 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 × X = B solution in exact linear sense.
127 * @return a solver
128 */
129 DecompositionSolver getSolver();
130
131 }