    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    /**
    023     * An interface to classes that implement an algorithm to calculate the
    024     * Singular Value Decomposition of a real matrix.
    025     * <p>
    026     * The Singular Value Decomposition of matrix A is a set of three matrices: U,
    027     * &Sigma; and V such that A = U &times; &Sigma; &times; V<sup>T</sup>. Let A be
    028     * a m &times; n matrix, then U is a m &times; p orthogonal matrix, &Sigma; is a
    029     * p &times; p diagonal matrix with positive or null elements, V is a p &times;
    030     * n orthogonal matrix (hence V<sup>T</sup> is also orthogonal) where
    031     * p=min(m,n).
    032     * </p>
    033     * <p>This interface is similar to the class with similar name from the
    034     * <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a> library, with the
    035     * following changes:</p>
    036     * <ul>
    037     *   <li>the <code>norm2</code> method which has been renamed as {@link #getNorm()
    038     *   getNorm},</li>
    039     *   <li>the <code>cond</code> method which has been renamed as {@link
    040     *   #getConditionNumber() getConditionNumber},</li>
    041     *   <li>the <code>rank</code> method which has been renamed as {@link #getRank()
    042     *   getRank},</li>
    043     *   <li>a {@link #getUT() getUT} method has been added,</li>
    044     *   <li>a {@link #getVT() getVT} method has been added,</li>
    045     *   <li>a {@link #getSolver() getSolver} method has been added,</li>
    046     *   <li>a {@link #getCovariance(double) getCovariance} method has been added.</li>
    047     * </ul>
    048     * @see <a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">MathWorld</a>
    049     * @see <a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">Wikipedia</a>
    050     * @version $Revision: 928081 $ $Date: 2010-03-26 23:36:38 +0100 (ven. 26 mars 2010) $
    051     * @since 2.0
    052     */
    053    public interface SingularValueDecomposition {
    054
    055        /**
    056         * Returns the matrix U of the decomposition.
    057         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    058         * @return the U matrix
    059         * @see #getUT()
    060         */
    061        RealMatrix getU();
    062
    063        /**
    064         * Returns the transpose of the matrix U of the decomposition.
    065         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    066         * @return the U matrix (or null if decomposed matrix is singular)
    067         * @see #getU()
    068         */
    069        RealMatrix getUT();
    070
    071        /**
    072         * Returns the diagonal matrix &Sigma; of the decomposition.
    073         * <p>&Sigma; is a diagonal matrix. The singular values are provided in
    074         * non-increasing order, for compatibility with Jama.</p>
    075         * @return the &Sigma; matrix
    076         */
    077        RealMatrix getS();
    078
    079        /**
    080         * Returns the diagonal elements of the matrix &Sigma; of the decomposition.
    081         * <p>The singular values are provided in non-increasing order, for
    082         * compatibility with Jama.</p>
    083         * @return the diagonal elements of the &Sigma; matrix
    084         */
    085        double[] getSingularValues();
    086
    087        /**
    088         * Returns the matrix V of the decomposition.
    089         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    090         * @return the V matrix (or null if decomposed matrix is singular)
    091         * @see #getVT()
    092         */
    093        RealMatrix getV();
    094
    095        /**
    096         * Returns the transpose of the matrix V of the decomposition.
    097         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    098         * @return the V matrix (or null if decomposed matrix is singular)
    099         * @see #getV()
    100         */
    101        RealMatrix getVT();
    102
    103        /**
    104         * Returns the n &times; n covariance matrix.
    105         * <p>The covariance matrix is V &times; J &times; V<sup>T</sup>
    106         * where J is the diagonal matrix of the inverse of the squares of
    107         * the singular values.</p>
    108         * @param minSingularValue value below which singular values are ignored
    109         * (a 0 or negative value implies all singular value will be used)
    110         * @return covariance matrix
    111         * @exception IllegalArgumentException if minSingularValue is larger than
    112         * the largest singular value, meaning all singular values are ignored
    113         */
    114        RealMatrix getCovariance(double minSingularValue) throws IllegalArgumentException;
    115
    116        /**
    117         * Returns the L<sub>2</sub> norm of the matrix.
    118         * <p>The L<sub>2</sub> norm is max(|A &times; u|<sub>2</sub> /
    119         * |u|<sub>2</sub>), where |.|<sub>2</sub> denotes the vectorial 2-norm
    120         * (i.e. the traditional euclidian norm).</p>
    121         * @return norm
    122         */
    123        double getNorm();
    124
    125        /**
    126         * Return the condition number of the matrix.
    127         * @return condition number of the matrix
    128         */
    129        double getConditionNumber();
    130
    131        /**
    132         * Return the effective numerical matrix rank.
    133         * <p>The effective numerical rank is the number of non-negligible
    134         * singular values. The threshold used to identify non-negligible
    135         * terms is max(m,n) &times; ulp(s<sub>1</sub>) where ulp(s<sub>1</sub>)
    136         * is the least significant bit of the largest singular value.</p>
    137         * @return effective numerical matrix rank
    138         */
    139        int getRank();
    140
    141        /**
    142         * Get a solver for finding the A &times; X = B solution in least square sense.
    143         * @return a solver
    144         */
    145        DecompositionSolver getSolver();
    146
    147    }