    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    }