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    package org.apache.commons.math3.linear;
018    
019    import org.apache.commons.math3.exception.NumberIsTooLargeException;
020    import org.apache.commons.math3.exception.util.LocalizedFormats;
021    import org.apache.commons.math3.util.FastMath;
022    import org.apache.commons.math3.util.Precision;
023    
024    /**
025     * Calculates the compact Singular Value Decomposition of a matrix.
026     * <p>
027     * The Singular Value Decomposition of matrix A is a set of three matrices: U,
028     * &Sigma; and V such that A = U &times; &Sigma; &times; V<sup>T</sup>. Let A be
029     * a m &times; n matrix, then U is a m &times; p orthogonal matrix, &Sigma; is a
030     * p &times; p diagonal matrix with positive or null elements, V is a p &times;
031     * n orthogonal matrix (hence V<sup>T</sup> is also orthogonal) where
032     * p=min(m,n).
033     * </p>
034     * <p>This class is similar to the class with similar name from the
035     * <a href="http://math.nist.gov/javanumerics/jama/">JAMA</a> library, with the
036     * following changes:</p>
037     * <ul>
038     *   <li>the {@code norm2} method which has been renamed as {@link #getNorm()
039     *   getNorm},</li>
040     *   <li>the {@code cond} method which has been renamed as {@link
041     *   #getConditionNumber() getConditionNumber},</li>
042     *   <li>the {@code rank} method which has been renamed as {@link #getRank()
043     *   getRank},</li>
044     *   <li>a {@link #getUT() getUT} method has been added,</li>
045     *   <li>a {@link #getVT() getVT} method has been added,</li>
046     *   <li>a {@link #getSolver() getSolver} method has been added,</li>
047     *   <li>a {@link #getCovariance(double) getCovariance} method has been added.</li>
048     * </ul>
049     * @see <a href="http://mathworld.wolfram.com/SingularValueDecomposition.html">MathWorld</a>
050     * @see <a href="http://en.wikipedia.org/wiki/Singular_value_decomposition">Wikipedia</a>
051     * @version $Id: SingularValueDecomposition.java 1456931 2013-03-15 12:34:35Z luc $
052     * @since 2.0 (changed to concrete class in 3.0)
053     */
054    public class SingularValueDecomposition {
055        /** Relative threshold for small singular values. */
056        private static final double EPS = 0x1.0p-52;
057        /** Absolute threshold for small singular values. */
058        private static final double TINY = 0x1.0p-966;
059        /** Computed singular values. */
060        private final double[] singularValues;
061        /** max(row dimension, column dimension). */
062        private final int m;
063        /** min(row dimension, column dimension). */
064        private final int n;
065        /** Indicator for transposed matrix. */
066        private final boolean transposed;
067        /** Cached value of U matrix. */
068        private final RealMatrix cachedU;
069        /** Cached value of transposed U matrix. */
070        private RealMatrix cachedUt;
071        /** Cached value of S (diagonal) matrix. */
072        private RealMatrix cachedS;
073        /** Cached value of V matrix. */
074        private final RealMatrix cachedV;
075        /** Cached value of transposed V matrix. */
076        private RealMatrix cachedVt;
077        /**
078         * Tolerance value for small singular values, calculated once we have
079         * populated "singularValues".
080         **/
081        private final double tol;
082    
083        /**
084         * Calculates the compact Singular Value Decomposition of the given matrix.
085         *
086         * @param matrix Matrix to decompose.
087         */
088        public SingularValueDecomposition(final RealMatrix matrix) {
089            final double[][] A;
090    
091             // "m" is always the largest dimension.
092            if (matrix.getRowDimension() < matrix.getColumnDimension()) {
093                transposed = true;
094                A = matrix.transpose().getData();
095                m = matrix.getColumnDimension();
096                n = matrix.getRowDimension();
097            } else {
098                transposed = false;
099                A = matrix.getData();
100                m = matrix.getRowDimension();
101                n = matrix.getColumnDimension();
102            }
103    
104            singularValues = new double[n];
105            final double[][] U = new double[m][n];
106            final double[][] V = new double[n][n];
107            final double[] e = new double[n];
108            final double[] work = new double[m];
109            // Reduce A to bidiagonal form, storing the diagonal elements
110            // in s and the super-diagonal elements in e.
111            final int nct = FastMath.min(m - 1, n);
112            final int nrt = FastMath.max(0, n - 2);
113            for (int k = 0; k < FastMath.max(nct, nrt); k++) {
114                if (k < nct) {
115                    // Compute the transformation for the k-th column and
116                    // place the k-th diagonal in s[k].
117                    // Compute 2-norm of k-th column without under/overflow.
118                    singularValues[k] = 0;
119                    for (int i = k; i < m; i++) {
120                        singularValues[k] = FastMath.hypot(singularValues[k], A[i][k]);
121                    }
122                    if (singularValues[k] != 0) {
123                        if (A[k][k] < 0) {
124                            singularValues[k] = -singularValues[k];
125                        }
126                        for (int i = k; i < m; i++) {
127                            A[i][k] /= singularValues[k];
128                        }
129                        A[k][k] += 1;
130                    }
131                    singularValues[k] = -singularValues[k];
132                }
133                for (int j = k + 1; j < n; j++) {
134                    if (k < nct &&
135                        singularValues[k] != 0) {
136                        // Apply the transformation.
137                        double t = 0;
138                        for (int i = k; i < m; i++) {
139                            t += A[i][k] * A[i][j];
140                        }
141                        t = -t / A[k][k];
142                        for (int i = k; i < m; i++) {
143                            A[i][j] += t * A[i][k];
144                        }
145                    }
146                    // Place the k-th row of A into e for the
147                    // subsequent calculation of the row transformation.
148                    e[j] = A[k][j];
149                }
150                if (k < nct) {
151                    // Place the transformation in U for subsequent back
152                    // multiplication.
153                    for (int i = k; i < m; i++) {
154                        U[i][k] = A[i][k];
155                    }
156                }
157                if (k < nrt) {
158                    // Compute the k-th row transformation and place the
159                    // k-th super-diagonal in e[k].
160                    // Compute 2-norm without under/overflow.
161                    e[k] = 0;
162                    for (int i = k + 1; i < n; i++) {
163                        e[k] = FastMath.hypot(e[k], e[i]);
164                    }
165                    if (e[k] != 0) {
166                        if (e[k + 1] < 0) {
167                            e[k] = -e[k];
168                        }
169                        for (int i = k + 1; i < n; i++) {
170                            e[i] /= e[k];
171                        }
172                        e[k + 1] += 1;
173                    }
174                    e[k] = -e[k];
175                    if (k + 1 < m &&
176                        e[k] != 0) {
177                        // Apply the transformation.
178                        for (int i = k + 1; i < m; i++) {
179                            work[i] = 0;
180                        }
181                        for (int j = k + 1; j < n; j++) {
182                            for (int i = k + 1; i < m; i++) {
183                                work[i] += e[j] * A[i][j];
184                            }
185                        }
186                        for (int j = k + 1; j < n; j++) {
187                            final double t = -e[j] / e[k + 1];
188                            for (int i = k + 1; i < m; i++) {
189                                A[i][j] += t * work[i];
190                            }
191                        }
192                    }
193    
194                    // Place the transformation in V for subsequent
195                    // back multiplication.
196                    for (int i = k + 1; i < n; i++) {
197                        V[i][k] = e[i];
198                    }
199                }
200            }
201            // Set up the final bidiagonal matrix or order p.
202            int p = n;
203            if (nct < n) {
204                singularValues[nct] = A[nct][nct];
205            }
206            if (m < p) {
207                singularValues[p - 1] = 0;
208            }
209            if (nrt + 1 < p) {
210                e[nrt] = A[nrt][p - 1];
211            }
212            e[p - 1] = 0;
213    
214            // Generate U.
215            for (int j = nct; j < n; j++) {
216                for (int i = 0; i < m; i++) {
217                    U[i][j] = 0;
218                }
219                U[j][j] = 1;
220            }
221            for (int k = nct - 1; k >= 0; k--) {
222                if (singularValues[k] != 0) {
223                    for (int j = k + 1; j < n; j++) {
224                        double t = 0;
225                        for (int i = k; i < m; i++) {
226                            t += U[i][k] * U[i][j];
227                        }
228                        t = -t / U[k][k];
229                        for (int i = k; i < m; i++) {
230                            U[i][j] += t * U[i][k];
231                        }
232                    }
233                    for (int i = k; i < m; i++) {
234                        U[i][k] = -U[i][k];
235                    }
236                    U[k][k] = 1 + U[k][k];
237                    for (int i = 0; i < k - 1; i++) {
238                        U[i][k] = 0;
239                    }
240                } else {
241                    for (int i = 0; i < m; i++) {
242                        U[i][k] = 0;
243                    }
244                    U[k][k] = 1;
245                }
246            }
247    
248            // Generate V.
249            for (int k = n - 1; k >= 0; k--) {
250                if (k < nrt &&
251                    e[k] != 0) {
252                    for (int j = k + 1; j < n; j++) {
253                        double t = 0;
254                        for (int i = k + 1; i < n; i++) {
255                            t += V[i][k] * V[i][j];
256                        }
257                        t = -t / V[k + 1][k];
258                        for (int i = k + 1; i < n; i++) {
259                            V[i][j] += t * V[i][k];
260                        }
261                    }
262                }
263                for (int i = 0; i < n; i++) {
264                    V[i][k] = 0;
265                }
266                V[k][k] = 1;
267            }
268    
269            // Main iteration loop for the singular values.
270            final int pp = p - 1;
271            int iter = 0;
272            while (p > 0) {
273                int k;
274                int kase;
275                // Here is where a test for too many iterations would go.
276                // This section of the program inspects for
277                // negligible elements in the s and e arrays.  On
278                // completion the variables kase and k are set as follows.
279                // kase = 1     if s(p) and e[k-1] are negligible and k<p
280                // kase = 2     if s(k) is negligible and k<p
281                // kase = 3     if e[k-1] is negligible, k<p, and
282                //              s(k), ..., s(p) are not negligible (qr step).
283                // kase = 4     if e(p-1) is negligible (convergence).
284                for (k = p - 2; k >= 0; k--) {
285                    final double threshold
286                        = TINY + EPS * (FastMath.abs(singularValues[k]) +
287                                        FastMath.abs(singularValues[k + 1]));
288    
289                    // the following condition is written this way in order
290                    // to break out of the loop when NaN occurs, writing it
291                    // as "if (FastMath.abs(e[k]) <= threshold)" would loop
292                    // indefinitely in case of NaNs because comparison on NaNs
293                    // always return false, regardless of what is checked
294                    // see issue MATH-947
295                    if (!(FastMath.abs(e[k]) > threshold)) {
296                        e[k] = 0;
297                        break;
298                    }
299    
300                }
301    
302                if (k == p - 2) {
303                    kase = 4;
304                } else {
305                    int ks;
306                    for (ks = p - 1; ks >= k; ks--) {
307                        if (ks == k) {
308                            break;
309                        }
310                        final double t = (ks != p ? FastMath.abs(e[ks]) : 0) +
311                            (ks != k + 1 ? FastMath.abs(e[ks - 1]) : 0);
312                        if (FastMath.abs(singularValues[ks]) <= TINY + EPS * t) {
313                            singularValues[ks] = 0;
314                            break;
315                        }
316                    }
317                    if (ks == k) {
318                        kase = 3;
319                    } else if (ks == p - 1) {
320                        kase = 1;
321                    } else {
322                        kase = 2;
323                        k = ks;
324                    }
325                }
326                k++;
327                // Perform the task indicated by kase.
328                switch (kase) {
329                    // Deflate negligible s(p).
330                    case 1: {
331                        double f = e[p - 2];
332                        e[p - 2] = 0;
333                        for (int j = p - 2; j >= k; j--) {
334                            double t = FastMath.hypot(singularValues[j], f);
335                            final double cs = singularValues[j] / t;
336                            final double sn = f / t;
337                            singularValues[j] = t;
338                            if (j != k) {
339                                f = -sn * e[j - 1];
340                                e[j - 1] = cs * e[j - 1];
341                            }
342    
343                            for (int i = 0; i < n; i++) {
344                                t = cs * V[i][j] + sn * V[i][p - 1];
345                                V[i][p - 1] = -sn * V[i][j] + cs * V[i][p - 1];
346                                V[i][j] = t;
347                            }
348                        }
349                    }
350                    break;
351                    // Split at negligible s(k).
352                    case 2: {
353                        double f = e[k - 1];
354                        e[k - 1] = 0;
355                        for (int j = k; j < p; j++) {
356                            double t = FastMath.hypot(singularValues[j], f);
357                            final double cs = singularValues[j] / t;
358                            final double sn = f / t;
359                            singularValues[j] = t;
360                            f = -sn * e[j];
361                            e[j] = cs * e[j];
362    
363                            for (int i = 0; i < m; i++) {
364                                t = cs * U[i][j] + sn * U[i][k - 1];
365                                U[i][k - 1] = -sn * U[i][j] + cs * U[i][k - 1];
366                                U[i][j] = t;
367                            }
368                        }
369                    }
370                    break;
371                    // Perform one qr step.
372                    case 3: {
373                        // Calculate the shift.
374                        final double maxPm1Pm2 = FastMath.max(FastMath.abs(singularValues[p - 1]),
375                                                              FastMath.abs(singularValues[p - 2]));
376                        final double scale = FastMath.max(FastMath.max(FastMath.max(maxPm1Pm2,
377                                                                                    FastMath.abs(e[p - 2])),
378                                                                       FastMath.abs(singularValues[k])),
379                                                          FastMath.abs(e[k]));
380                        final double sp = singularValues[p - 1] / scale;
381                        final double spm1 = singularValues[p - 2] / scale;
382                        final double epm1 = e[p - 2] / scale;
383                        final double sk = singularValues[k] / scale;
384                        final double ek = e[k] / scale;
385                        final double b = ((spm1 + sp) * (spm1 - sp) + epm1 * epm1) / 2.0;
386                        final double c = (sp * epm1) * (sp * epm1);
387                        double shift = 0;
388                        if (b != 0 ||
389                            c != 0) {
390                            shift = FastMath.sqrt(b * b + c);
391                            if (b < 0) {
392                                shift = -shift;
393                            }
394                            shift = c / (b + shift);
395                        }
396                        double f = (sk + sp) * (sk - sp) + shift;
397                        double g = sk * ek;
398                        // Chase zeros.
399                        for (int j = k; j < p - 1; j++) {
400                            double t = FastMath.hypot(f, g);
401                            double cs = f / t;
402                            double sn = g / t;
403                            if (j != k) {
404                                e[j - 1] = t;
405                            }
406                            f = cs * singularValues[j] + sn * e[j];
407                            e[j] = cs * e[j] - sn * singularValues[j];
408                            g = sn * singularValues[j + 1];
409                            singularValues[j + 1] = cs * singularValues[j + 1];
410    
411                            for (int i = 0; i < n; i++) {
412                                t = cs * V[i][j] + sn * V[i][j + 1];
413                                V[i][j + 1] = -sn * V[i][j] + cs * V[i][j + 1];
414                                V[i][j] = t;
415                            }
416                            t = FastMath.hypot(f, g);
417                            cs = f / t;
418                            sn = g / t;
419                            singularValues[j] = t;
420                            f = cs * e[j] + sn * singularValues[j + 1];
421                            singularValues[j + 1] = -sn * e[j] + cs * singularValues[j + 1];
422                            g = sn * e[j + 1];
423                            e[j + 1] = cs * e[j + 1];
424                            if (j < m - 1) {
425                                for (int i = 0; i < m; i++) {
426                                    t = cs * U[i][j] + sn * U[i][j + 1];
427                                    U[i][j + 1] = -sn * U[i][j] + cs * U[i][j + 1];
428                                    U[i][j] = t;
429                                }
430                            }
431                        }
432                        e[p - 2] = f;
433                        iter = iter + 1;
434                    }
435                    break;
436                    // Convergence.
437                    default: {
438                        // Make the singular values positive.
439                        if (singularValues[k] <= 0) {
440                            singularValues[k] = singularValues[k] < 0 ? -singularValues[k] : 0;
441    
442                            for (int i = 0; i <= pp; i++) {
443                                V[i][k] = -V[i][k];
444                            }
445                        }
446                        // Order the singular values.
447                        while (k < pp) {
448                            if (singularValues[k] >= singularValues[k + 1]) {
449                                break;
450                            }
451                            double t = singularValues[k];
452                            singularValues[k] = singularValues[k + 1];
453                            singularValues[k + 1] = t;
454                            if (k < n - 1) {
455                                for (int i = 0; i < n; i++) {
456                                    t = V[i][k + 1];
457                                    V[i][k + 1] = V[i][k];
458                                    V[i][k] = t;
459                                }
460                            }
461                            if (k < m - 1) {
462                                for (int i = 0; i < m; i++) {
463                                    t = U[i][k + 1];
464                                    U[i][k + 1] = U[i][k];
465                                    U[i][k] = t;
466                                }
467                            }
468                            k++;
469                        }
470                        iter = 0;
471                        p--;
472                    }
473                    break;
474                }
475            }
476    
477            // Set the small value tolerance used to calculate rank and pseudo-inverse
478            tol = FastMath.max(m * singularValues[0] * EPS,
479                               FastMath.sqrt(Precision.SAFE_MIN));
480    
481            if (!transposed) {
482                cachedU = MatrixUtils.createRealMatrix(U);
483                cachedV = MatrixUtils.createRealMatrix(V);
484            } else {
485                cachedU = MatrixUtils.createRealMatrix(V);
486                cachedV = MatrixUtils.createRealMatrix(U);
487            }
488        }
489    
490        /**
491         * Returns the matrix U of the decomposition.
492         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
493         * @return the U matrix
494         * @see #getUT()
495         */
496        public RealMatrix getU() {
497            // return the cached matrix
498            return cachedU;
499    
500        }
501    
502        /**
503         * Returns the transpose of the matrix U of the decomposition.
504         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
505         * @return the U matrix (or null if decomposed matrix is singular)
506         * @see #getU()
507         */
508        public RealMatrix getUT() {
509            if (cachedUt == null) {
510                cachedUt = getU().transpose();
511            }
512            // return the cached matrix
513            return cachedUt;
514        }
515    
516        /**
517         * Returns the diagonal matrix &Sigma; of the decomposition.
518         * <p>&Sigma; is a diagonal matrix. The singular values are provided in
519         * non-increasing order, for compatibility with Jama.</p>
520         * @return the &Sigma; matrix
521         */
522        public RealMatrix getS() {
523            if (cachedS == null) {
524                // cache the matrix for subsequent calls
525                cachedS = MatrixUtils.createRealDiagonalMatrix(singularValues);
526            }
527            return cachedS;
528        }
529    
530        /**
531         * Returns the diagonal elements of the matrix &Sigma; of the decomposition.
532         * <p>The singular values are provided in non-increasing order, for
533         * compatibility with Jama.</p>
534         * @return the diagonal elements of the &Sigma; matrix
535         */
536        public double[] getSingularValues() {
537            return singularValues.clone();
538        }
539    
540        /**
541         * Returns the matrix V of the decomposition.
542         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
543         * @return the V matrix (or null if decomposed matrix is singular)
544         * @see #getVT()
545         */
546        public RealMatrix getV() {
547            // return the cached matrix
548            return cachedV;
549        }
550    
551        /**
552         * Returns the transpose of the matrix V of the decomposition.
553         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
554         * @return the V matrix (or null if decomposed matrix is singular)
555         * @see #getV()
556         */
557        public RealMatrix getVT() {
558            if (cachedVt == null) {
559                cachedVt = getV().transpose();
560            }
561            // return the cached matrix
562            return cachedVt;
563        }
564    
565        /**
566         * Returns the n &times; n covariance matrix.
567         * <p>The covariance matrix is V &times; J &times; V<sup>T</sup>
568         * where J is the diagonal matrix of the inverse of the squares of
569         * the singular values.</p>
570         * @param minSingularValue value below which singular values are ignored
571         * (a 0 or negative value implies all singular value will be used)
572         * @return covariance matrix
573         * @exception IllegalArgumentException if minSingularValue is larger than
574         * the largest singular value, meaning all singular values are ignored
575         */
576        public RealMatrix getCovariance(final double minSingularValue) {
577            // get the number of singular values to consider
578            final int p = singularValues.length;
579            int dimension = 0;
580            while (dimension < p &&
581                   singularValues[dimension] >= minSingularValue) {
582                ++dimension;
583            }
584    
585            if (dimension == 0) {
586                throw new NumberIsTooLargeException(LocalizedFormats.TOO_LARGE_CUTOFF_SINGULAR_VALUE,
587                                                    minSingularValue, singularValues[0], true);
588            }
589    
590            final double[][] data = new double[dimension][p];
591            getVT().walkInOptimizedOrder(new DefaultRealMatrixPreservingVisitor() {
592                /** {@inheritDoc} */
593                @Override
594                public void visit(final int row, final int column,
595                        final double value) {
596                    data[row][column] = value / singularValues[row];
597                }
598            }, 0, dimension - 1, 0, p - 1);
599    
600            RealMatrix jv = new Array2DRowRealMatrix(data, false);
601            return jv.transpose().multiply(jv);
602        }
603    
604        /**
605         * Returns the L<sub>2</sub> norm of the matrix.
606         * <p>The L<sub>2</sub> norm is max(|A &times; u|<sub>2</sub> /
607         * |u|<sub>2</sub>), where |.|<sub>2</sub> denotes the vectorial 2-norm
608         * (i.e. the traditional euclidian norm).</p>
609         * @return norm
610         */
611        public double getNorm() {
612            return singularValues[0];
613        }
614    
615        /**
616         * Return the condition number of the matrix.
617         * @return condition number of the matrix
618         */
619        public double getConditionNumber() {
620            return singularValues[0] / singularValues[n - 1];
621        }
622    
623        /**
624         * Computes the inverse of the condition number.
625         * In cases of rank deficiency, the {@link #getConditionNumber() condition
626         * number} will become undefined.
627         *
628         * @return the inverse of the condition number.
629         */
630        public double getInverseConditionNumber() {
631            return singularValues[n - 1] / singularValues[0];
632        }
633    
634        /**
635         * Return the effective numerical matrix rank.
636         * <p>The effective numerical rank is the number of non-negligible
637         * singular values. The threshold used to identify non-negligible
638         * terms is max(m,n) &times; ulp(s<sub>1</sub>) where ulp(s<sub>1</sub>)
639         * is the least significant bit of the largest singular value.</p>
640         * @return effective numerical matrix rank
641         */
642        public int getRank() {
643            int r = 0;
644            for (int i = 0; i < singularValues.length; i++) {
645                if (singularValues[i] > tol) {
646                    r++;
647                }
648            }
649            return r;
650        }
651    
652        /**
653         * Get a solver for finding the A &times; X = B solution in least square sense.
654         * @return a solver
655         */
656        public DecompositionSolver getSolver() {
657            return new Solver(singularValues, getUT(), getV(), getRank() == m, tol);
658        }
659    
660        /** Specialized solver. */
661        private static class Solver implements DecompositionSolver {
662            /** Pseudo-inverse of the initial matrix. */
663            private final RealMatrix pseudoInverse;
664            /** Singularity indicator. */
665            private boolean nonSingular;
666    
667            /**
668             * Build a solver from decomposed matrix.
669             *
670             * @param singularValues Singular values.
671             * @param uT U<sup>T</sup> matrix of the decomposition.
672             * @param v V matrix of the decomposition.
673             * @param nonSingular Singularity indicator.
674             * @param tol tolerance for singular values
675             */
676            private Solver(final double[] singularValues, final RealMatrix uT,
677                           final RealMatrix v, final boolean nonSingular, final double tol) {
678                final double[][] suT = uT.getData();
679                for (int i = 0; i < singularValues.length; ++i) {
680                    final double a;
681                    if (singularValues[i] > tol) {
682                        a = 1 / singularValues[i];
683                    } else {
684                        a = 0;
685                    }
686                    final double[] suTi = suT[i];
687                    for (int j = 0; j < suTi.length; ++j) {
688                        suTi[j] *= a;
689                    }
690                }
691                pseudoInverse = v.multiply(new Array2DRowRealMatrix(suT, false));
692                this.nonSingular = nonSingular;
693            }
694    
695            /**
696             * Solve the linear equation A &times; X = B in least square sense.
697             * <p>
698             * The m&times;n matrix A may not be square, the solution X is such that
699             * ||A &times; X - B|| is minimal.
700             * </p>
701             * @param b Right-hand side of the equation A &times; X = B
702             * @return a vector X that minimizes the two norm of A &times; X - B
703             * @throws org.apache.commons.math3.exception.DimensionMismatchException
704             * if the matrices dimensions do not match.
705             */
706            public RealVector solve(final RealVector b) {
707                return pseudoInverse.operate(b);
708            }
709    
710            /**
711             * Solve the linear equation A &times; X = B in least square sense.
712             * <p>
713             * The m&times;n matrix A may not be square, the solution X is such that
714             * ||A &times; X - B|| is minimal.
715             * </p>
716             *
717             * @param b Right-hand side of the equation A &times; X = B
718             * @return a matrix X that minimizes the two norm of A &times; X - B
719             * @throws org.apache.commons.math3.exception.DimensionMismatchException
720             * if the matrices dimensions do not match.
721             */
722            public RealMatrix solve(final RealMatrix b) {
723                return pseudoInverse.multiply(b);
724            }
725    
726            /**
727             * Check if the decomposed matrix is non-singular.
728             *
729             * @return {@code true} if the decomposed matrix is non-singular.
730             */
731            public boolean isNonSingular() {
732                return nonSingular;
733            }
734    
735            /**
736             * Get the pseudo-inverse of the decomposed matrix.
737             *
738             * @return the inverse matrix.
739             */
740            public RealMatrix getInverse() {
741                return pseudoInverse;
742            }
743        }
744    }