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: 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 &times; X = B solution in exact linear sense.
127         * @return a solver
128         */
129        DecompositionSolver getSolver();
130    
131    }