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    }