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 &times; D &times; V<sup>T</sup>.
026     * A, V and D are all m &times; 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 &times; X = B solution in exact linear sense.
133         * @return a solver
134         */
135        DecompositionSolver getSolver();
136    
137    }