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