Mercurial > hg > de.mpg.mpiwg.itgroup.digilib.plugin

comparison libs/commons-math-2.1/docs/apidocs/src-html/org/apache/commons/math/linear/SingularValueDecomposition.html @ 13:cbf34dd4d7e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
commons-math-2.1 added
author dwinter
date Tue, 04 Jan 2011 10:02:07 +0100
parents
children
comparison
equal deleted inserted replaced
12:970d26a94fb7 13:cbf34dd4d7e6
1 <HTML>
2 <BODY BGCOLOR="white">
3 <PRE>
4 <FONT color="green">001</FONT> /*<a name="line.1"></a>
5 <FONT color="green">002</FONT> * Licensed to the Apache Software Foundation (ASF) under one or more<a name="line.2"></a>
6 <FONT color="green">003</FONT> * contributor license agreements. See the NOTICE file distributed with<a name="line.3"></a>
7 <FONT color="green">004</FONT> * this work for additional information regarding copyright ownership.<a name="line.4"></a>
8 <FONT color="green">005</FONT> * The ASF licenses this file to You under the Apache License, Version 2.0<a name="line.5"></a>
9 <FONT color="green">006</FONT> * (the "License"); you may not use this file except in compliance with<a name="line.6"></a>
10 <FONT color="green">007</FONT> * the License. You may obtain a copy of the License at<a name="line.7"></a>
11 <FONT color="green">008</FONT> *<a name="line.8"></a>
12 <FONT color="green">009</FONT> * http://www.apache.org/licenses/LICENSE-2.0<a name="line.9"></a>
13 <FONT color="green">010</FONT> *<a name="line.10"></a>
14 <FONT color="green">011</FONT> * Unless required by applicable law or agreed to in writing, software<a name="line.11"></a>
15 <FONT color="green">012</FONT> * distributed under the License is distributed on an "AS IS" BASIS,<a name="line.12"></a>
16 <FONT color="green">013</FONT> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<a name="line.13"></a>
17 <FONT color="green">014</FONT> * See the License for the specific language governing permissions and<a name="line.14"></a>
18 <FONT color="green">015</FONT> * limitations under the License.<a name="line.15"></a>
19 <FONT color="green">016</FONT> */<a name="line.16"></a>
20 <FONT color="green">017</FONT> <a name="line.17"></a>
21 <FONT color="green">018</FONT> package org.apache.commons.math.linear;<a name="line.18"></a>
22 <FONT color="green">019</FONT> <a name="line.19"></a>
23 <FONT color="green">020</FONT> <a name="line.20"></a>
24 <FONT color="green">021</FONT> <a name="line.21"></a>
25 <FONT color="green">022</FONT> /**<a name="line.22"></a>
26 <FONT color="green">023</FONT> * An interface to classes that implement an algorithm to calculate the<a name="line.23"></a>
27 <FONT color="green">024</FONT> * Singular Value Decomposition of a real matrix.<a name="line.24"></a>
28 <FONT color="green">025</FONT> * &lt;p&gt;<a name="line.25"></a>
29 <FONT color="green">026</FONT> * The Singular Value Decomposition of matrix A is a set of three matrices: U,<a name="line.26"></a>
30 <FONT color="green">027</FONT> * &amp;Sigma; and V such that A = U &amp;times; &amp;Sigma; &amp;times; V&lt;sup&gt;T&lt;/sup&gt;. Let A be<a name="line.27"></a>
31 <FONT color="green">028</FONT> * a m &amp;times; n matrix, then U is a m &amp;times; p orthogonal matrix, &amp;Sigma; is a<a name="line.28"></a>
32 <FONT color="green">029</FONT> * p &amp;times; p diagonal matrix with positive or null elements, V is a p &amp;times;<a name="line.29"></a>
33 <FONT color="green">030</FONT> * n orthogonal matrix (hence V&lt;sup&gt;T&lt;/sup&gt; is also orthogonal) where<a name="line.30"></a>
34 <FONT color="green">031</FONT> * p=min(m,n).<a name="line.31"></a>
35 <FONT color="green">032</FONT> * &lt;/p&gt;<a name="line.32"></a>
36 <FONT color="green">033</FONT> * &lt;p&gt;This interface is similar to the class with similar name from the<a name="line.33"></a>
37 <FONT color="green">034</FONT> * &lt;a href="http://math.nist.gov/javanumerics/jama/"&gt;JAMA&lt;/a&gt; library, with the<a name="line.34"></a>
38 <FONT color="green">035</FONT> * following changes:&lt;/p&gt;<a name="line.35"></a>
39 <FONT color="green">036</FONT> * &lt;ul&gt;<a name="line.36"></a>
40 <FONT color="green">037</FONT> * &lt;li&gt;the &lt;code&gt;norm2&lt;/code&gt; method which has been renamed as {@link #getNorm()<a name="line.37"></a>
41 <FONT color="green">038</FONT> * getNorm},&lt;/li&gt;<a name="line.38"></a>
42 <FONT color="green">039</FONT> * &lt;li&gt;the &lt;code&gt;cond&lt;/code&gt; method which has been renamed as {@link<a name="line.39"></a>
43 <FONT color="green">040</FONT> * #getConditionNumber() getConditionNumber},&lt;/li&gt;<a name="line.40"></a>
44 <FONT color="green">041</FONT> * &lt;li&gt;the &lt;code&gt;rank&lt;/code&gt; method which has been renamed as {@link #getRank()<a name="line.41"></a>
45 <FONT color="green">042</FONT> * getRank},&lt;/li&gt;<a name="line.42"></a>
46 <FONT color="green">043</FONT> * &lt;li&gt;a {@link #getUT() getUT} method has been added,&lt;/li&gt;<a name="line.43"></a>
47 <FONT color="green">044</FONT> * &lt;li&gt;a {@link #getVT() getVT} method has been added,&lt;/li&gt;<a name="line.44"></a>
48 <FONT color="green">045</FONT> * &lt;li&gt;a {@link #getSolver() getSolver} method has been added,&lt;/li&gt;<a name="line.45"></a>
49 <FONT color="green">046</FONT> * &lt;li&gt;a {@link #getCovariance(double) getCovariance} method has been added.&lt;/li&gt;<a name="line.46"></a>
50 <FONT color="green">047</FONT> * &lt;/ul&gt;<a name="line.47"></a>
51 <FONT color="green">048</FONT> * @see &lt;a href="http://mathworld.wolfram.com/SingularValueDecomposition.html"&gt;MathWorld&lt;/a&gt;<a name="line.48"></a>
52 <FONT color="green">049</FONT> * @see &lt;a href="http://en.wikipedia.org/wiki/Singular_value_decomposition"&gt;Wikipedia&lt;/a&gt;<a name="line.49"></a>
53 <FONT color="green">050</FONT> * @version $Revision: 928081 $ $Date: 2010-03-26 18:36:38 -0400 (Fri, 26 Mar 2010) $<a name="line.50"></a>
54 <FONT color="green">051</FONT> * @since 2.0<a name="line.51"></a>
55 <FONT color="green">052</FONT> */<a name="line.52"></a>
56 <FONT color="green">053</FONT> public interface SingularValueDecomposition {<a name="line.53"></a>
57 <FONT color="green">054</FONT> <a name="line.54"></a>
58 <FONT color="green">055</FONT> /**<a name="line.55"></a>
59 <FONT color="green">056</FONT> * Returns the matrix U of the decomposition.<a name="line.56"></a>
60 <FONT color="green">057</FONT> * &lt;p&gt;U is an orthogonal matrix, i.e. its transpose is also its inverse.&lt;/p&gt;<a name="line.57"></a>
61 <FONT color="green">058</FONT> * @return the U matrix<a name="line.58"></a>
62 <FONT color="green">059</FONT> * @see #getUT()<a name="line.59"></a>
63 <FONT color="green">060</FONT> */<a name="line.60"></a>
64 <FONT color="green">061</FONT> RealMatrix getU();<a name="line.61"></a>
65 <FONT color="green">062</FONT> <a name="line.62"></a>
66 <FONT color="green">063</FONT> /**<a name="line.63"></a>
67 <FONT color="green">064</FONT> * Returns the transpose of the matrix U of the decomposition.<a name="line.64"></a>
68 <FONT color="green">065</FONT> * &lt;p&gt;U is an orthogonal matrix, i.e. its transpose is also its inverse.&lt;/p&gt;<a name="line.65"></a>
69 <FONT color="green">066</FONT> * @return the U matrix (or null if decomposed matrix is singular)<a name="line.66"></a>
70 <FONT color="green">067</FONT> * @see #getU()<a name="line.67"></a>
71 <FONT color="green">068</FONT> */<a name="line.68"></a>
72 <FONT color="green">069</FONT> RealMatrix getUT();<a name="line.69"></a>
73 <FONT color="green">070</FONT> <a name="line.70"></a>
74 <FONT color="green">071</FONT> /**<a name="line.71"></a>
75 <FONT color="green">072</FONT> * Returns the diagonal matrix &amp;Sigma; of the decomposition.<a name="line.72"></a>
76 <FONT color="green">073</FONT> * &lt;p&gt;&amp;Sigma; is a diagonal matrix. The singular values are provided in<a name="line.73"></a>
77 <FONT color="green">074</FONT> * non-increasing order, for compatibility with Jama.&lt;/p&gt;<a name="line.74"></a>
78 <FONT color="green">075</FONT> * @return the &amp;Sigma; matrix<a name="line.75"></a>
79 <FONT color="green">076</FONT> */<a name="line.76"></a>
80 <FONT color="green">077</FONT> RealMatrix getS();<a name="line.77"></a>
81 <FONT color="green">078</FONT> <a name="line.78"></a>
82 <FONT color="green">079</FONT> /**<a name="line.79"></a>
83 <FONT color="green">080</FONT> * Returns the diagonal elements of the matrix &amp;Sigma; of the decomposition.<a name="line.80"></a>
84 <FONT color="green">081</FONT> * &lt;p&gt;The singular values are provided in non-increasing order, for<a name="line.81"></a>
85 <FONT color="green">082</FONT> * compatibility with Jama.&lt;/p&gt;<a name="line.82"></a>
86 <FONT color="green">083</FONT> * @return the diagonal elements of the &amp;Sigma; matrix<a name="line.83"></a>
87 <FONT color="green">084</FONT> */<a name="line.84"></a>
88 <FONT color="green">085</FONT> double[] getSingularValues();<a name="line.85"></a>
89 <FONT color="green">086</FONT> <a name="line.86"></a>
90 <FONT color="green">087</FONT> /**<a name="line.87"></a>
91 <FONT color="green">088</FONT> * Returns the matrix V of the decomposition.<a name="line.88"></a>
92 <FONT color="green">089</FONT> * &lt;p&gt;V is an orthogonal matrix, i.e. its transpose is also its inverse.&lt;/p&gt;<a name="line.89"></a>
93 <FONT color="green">090</FONT> * @return the V matrix (or null if decomposed matrix is singular)<a name="line.90"></a>
94 <FONT color="green">091</FONT> * @see #getVT()<a name="line.91"></a>
95 <FONT color="green">092</FONT> */<a name="line.92"></a>
96 <FONT color="green">093</FONT> RealMatrix getV();<a name="line.93"></a>
97 <FONT color="green">094</FONT> <a name="line.94"></a>
98 <FONT color="green">095</FONT> /**<a name="line.95"></a>
99 <FONT color="green">096</FONT> * Returns the transpose of the matrix V of the decomposition.<a name="line.96"></a>
100 <FONT color="green">097</FONT> * &lt;p&gt;V is an orthogonal matrix, i.e. its transpose is also its inverse.&lt;/p&gt;<a name="line.97"></a>
101 <FONT color="green">098</FONT> * @return the V matrix (or null if decomposed matrix is singular)<a name="line.98"></a>
102 <FONT color="green">099</FONT> * @see #getV()<a name="line.99"></a>
103 <FONT color="green">100</FONT> */<a name="line.100"></a>
104 <FONT color="green">101</FONT> RealMatrix getVT();<a name="line.101"></a>
105 <FONT color="green">102</FONT> <a name="line.102"></a>
106 <FONT color="green">103</FONT> /**<a name="line.103"></a>
107 <FONT color="green">104</FONT> * Returns the n &amp;times; n covariance matrix.<a name="line.104"></a>
108 <FONT color="green">105</FONT> * &lt;p&gt;The covariance matrix is V &amp;times; J &amp;times; V&lt;sup&gt;T&lt;/sup&gt;<a name="line.105"></a>
109 <FONT color="green">106</FONT> * where J is the diagonal matrix of the inverse of the squares of<a name="line.106"></a>
110 <FONT color="green">107</FONT> * the singular values.&lt;/p&gt;<a name="line.107"></a>
111 <FONT color="green">108</FONT> * @param minSingularValue value below which singular values are ignored<a name="line.108"></a>
112 <FONT color="green">109</FONT> * (a 0 or negative value implies all singular value will be used)<a name="line.109"></a>
113 <FONT color="green">110</FONT> * @return covariance matrix<a name="line.110"></a>
114 <FONT color="green">111</FONT> * @exception IllegalArgumentException if minSingularValue is larger than<a name="line.111"></a>
115 <FONT color="green">112</FONT> * the largest singular value, meaning all singular values are ignored<a name="line.112"></a>
116 <FONT color="green">113</FONT> */<a name="line.113"></a>
117 <FONT color="green">114</FONT> RealMatrix getCovariance(double minSingularValue) throws IllegalArgumentException;<a name="line.114"></a>
118 <FONT color="green">115</FONT> <a name="line.115"></a>
119 <FONT color="green">116</FONT> /**<a name="line.116"></a>
120 <FONT color="green">117</FONT> * Returns the L&lt;sub&gt;2&lt;/sub&gt; norm of the matrix.<a name="line.117"></a>
121 <FONT color="green">118</FONT> * &lt;p&gt;The L&lt;sub&gt;2&lt;/sub&gt; norm is max(|A &amp;times; u|&lt;sub&gt;2&lt;/sub&gt; /<a name="line.118"></a>
122 <FONT color="green">119</FONT> * |u|&lt;sub&gt;2&lt;/sub&gt;), where |.|&lt;sub&gt;2&lt;/sub&gt; denotes the vectorial 2-norm<a name="line.119"></a>
123 <FONT color="green">120</FONT> * (i.e. the traditional euclidian norm).&lt;/p&gt;<a name="line.120"></a>
124 <FONT color="green">121</FONT> * @return norm<a name="line.121"></a>
125 <FONT color="green">122</FONT> */<a name="line.122"></a>
126 <FONT color="green">123</FONT> double getNorm();<a name="line.123"></a>
127 <FONT color="green">124</FONT> <a name="line.124"></a>
128 <FONT color="green">125</FONT> /**<a name="line.125"></a>
129 <FONT color="green">126</FONT> * Return the condition number of the matrix.<a name="line.126"></a>
130 <FONT color="green">127</FONT> * @return condition number of the matrix<a name="line.127"></a>
131 <FONT color="green">128</FONT> */<a name="line.128"></a>
132 <FONT color="green">129</FONT> double getConditionNumber();<a name="line.129"></a>
133 <FONT color="green">130</FONT> <a name="line.130"></a>
134 <FONT color="green">131</FONT> /**<a name="line.131"></a>
135 <FONT color="green">132</FONT> * Return the effective numerical matrix rank.<a name="line.132"></a>
136 <FONT color="green">133</FONT> * &lt;p&gt;The effective numerical rank is the number of non-negligible<a name="line.133"></a>
137 <FONT color="green">134</FONT> * singular values. The threshold used to identify non-negligible<a name="line.134"></a>
138 <FONT color="green">135</FONT> * terms is max(m,n) &amp;times; ulp(s&lt;sub&gt;1&lt;/sub&gt;) where ulp(s&lt;sub&gt;1&lt;/sub&gt;)<a name="line.135"></a>
139 <FONT color="green">136</FONT> * is the least significant bit of the largest singular value.&lt;/p&gt;<a name="line.136"></a>
140 <FONT color="green">137</FONT> * @return effective numerical matrix rank<a name="line.137"></a>
141 <FONT color="green">138</FONT> */<a name="line.138"></a>
142 <FONT color="green">139</FONT> int getRank();<a name="line.139"></a>
143 <FONT color="green">140</FONT> <a name="line.140"></a>
144 <FONT color="green">141</FONT> /**<a name="line.141"></a>
145 <FONT color="green">142</FONT> * Get a solver for finding the A &amp;times; X = B solution in least square sense.<a name="line.142"></a>
146 <FONT color="green">143</FONT> * @return a solver<a name="line.143"></a>
147 <FONT color="green">144</FONT> */<a name="line.144"></a>
148 <FONT color="green">145</FONT> DecompositionSolver getSolver();<a name="line.145"></a>
149 <FONT color="green">146</FONT> <a name="line.146"></a>
150 <FONT color="green">147</FONT> }<a name="line.147"></a>
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211 </PRE>
212 </BODY>
213 </HTML>