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 */
017package org.apache.commons.math3.linear;
018
019import org.apache.commons.math3.exception.NumberIsTooLargeException;
020import org.apache.commons.math3.exception.util.LocalizedFormats;
021import org.apache.commons.math3.util.FastMath;
022import 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 1538368 2013-11-03 13:57:37Z erans $
052 * @since 2.0 (changed to concrete class in 3.0)
053 */
054public 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++;
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}