1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.math.linear;
19
20
21
22 /**
23 * An interface to classes that implement an algorithm to calculate the
24 * Singular Value Decomposition of a real matrix.
25 * <p>The Singular Value Decomposition of matrix A is a set of three matrices:
26 * U, Σ and V such that A = U × Σ × V<sup>T</sup>.
27 * Let A be an m × n matrix, then U is an m × m orthogonal matrix,
28 * Σ is a m × n diagonal matrix with positive diagonal elements,
29 * and V is an n × n orthogonal matrix.</p>
30 * <p>This interface is similar to the class with similar name from the now defunct
31 * <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a> library, with the
32 * following changes:</p>
33 * <ul>
34 * <li>the <code>norm2</code> method which has been renamed as {@link #getNorm()
35 * getNorm},</li>
36 * <li>the <code>cond</code> method which has been renamed as {@link
37 * #getConditionNumber() getConditionNumber},</li>
38 * <li>the <code>rank</code> method which has been renamed as {@link #getRank()
39 * getRank},</li>
40 * <li>a {@link #getUT() getUT} method has been added,</li>
41 * <li>a {@link #getVT() getVT} method has been added,</li>
42 * <li>a {@link #getSolver() getSolver} method has been added,</li>
43 * <li>a {@link #getCovariance(double) getCovariance} method has been added.</li>
44 * </ul>
45 * @see <a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">MathWorld</a>
46 * @see <a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">Wikipedia</a>
47 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
48 * @since 2.0
49 */
50 public interface SingularValueDecomposition {
51
52 /**
53 * Returns the matrix U of the decomposition.
54 * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
55 * @return the U matrix
56 * @see #getUT()
57 */
58 RealMatrix getU();
59
60 /**
61 * Returns the transpose of the matrix U of the decomposition.
62 * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
63 * @return the U matrix (or null if decomposed matrix is singular)
64 * @see #getU()
65 */
66 RealMatrix getUT();
67
68 /**
69 * Returns the diagonal matrix Σ of the decomposition.
70 * <p>Σ is a diagonal matrix. The singular values are provided in
71 * non-increasing order, for compatibility with Jama.</p>
72 * @return the Σ matrix
73 */
74 RealMatrix getS();
75
76 /**
77 * Returns the diagonal elements of the matrix Σ of the decomposition.
78 * <p>The singular values are provided in non-increasing order, for
79 * compatibility with Jama.</p>
80 * @return the diagonal elements of the Σ matrix
81 */
82 double[] getSingularValues();
83
84 /**
85 * Returns the matrix V of the decomposition.
86 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
87 * @return the V matrix (or null if decomposed matrix is singular)
88 * @see #getVT()
89 */
90 RealMatrix getV();
91
92 /**
93 * Returns the transpose of the matrix V of the decomposition.
94 * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
95 * @return the V matrix (or null if decomposed matrix is singular)
96 * @see #getV()
97 */
98 RealMatrix getVT();
99
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 }