    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 1416643 2012-12-03 19:37:14Z tn $
    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                    if (FastMath.abs(e[k]) <= threshold) {
    289                        e[k] = 0;
    290                        break;
    291                    }
    292                }
    293
    294                if (k == p - 2) {
    295                    kase = 4;
    296                } else {
    297                    int ks;
    298                    for (ks = p - 1; ks >= k; ks--) {
    299                        if (ks == k) {
    300                            break;
    301                        }
    302                        final double t = (ks != p ? FastMath.abs(e[ks]) : 0) +
    303                            (ks != k + 1 ? FastMath.abs(e[ks - 1]) : 0);
    304                        if (FastMath.abs(singularValues[ks]) <= TINY + EPS * t) {
    305                            singularValues[ks] = 0;
    306                            break;
    307                        }
    308                    }
    309                    if (ks == k) {
    310                        kase = 3;
    311                    } else if (ks == p - 1) {
    312                        kase = 1;
    313                    } else {
    314                        kase = 2;
    315                        k = ks;
    316                    }
    317                }
    318                k++;
    319                // Perform the task indicated by kase.
    320                switch (kase) {
    321                    // Deflate negligible s(p).
    322                    case 1: {
    323                        double f = e[p - 2];
    324                        e[p - 2] = 0;
    325                        for (int j = p - 2; j >= k; j--) {
    326                            double t = FastMath.hypot(singularValues[j], f);
    327                            final double cs = singularValues[j] / t;
    328                            final double sn = f / t;
    329                            singularValues[j] = t;
    330                            if (j != k) {
    331                                f = -sn * e[j - 1];
    332                                e[j - 1] = cs * e[j - 1];
    333                            }
    334
    335                            for (int i = 0; i < n; i++) {
    336                                t = cs * V[i][j] + sn * V[i][p - 1];
    337                                V[i][p - 1] = -sn * V[i][j] + cs * V[i][p - 1];
    338                                V[i][j] = t;
    339                            }
    340                        }
    341                    }
    342                    break;
    343                    // Split at negligible s(k).
    344                    case 2: {
    345                        double f = e[k - 1];
    346                        e[k - 1] = 0;
    347                        for (int j = k; j < p; j++) {
    348                            double t = FastMath.hypot(singularValues[j], f);
    349                            final double cs = singularValues[j] / t;
    350                            final double sn = f / t;
    351                            singularValues[j] = t;
    352                            f = -sn * e[j];
    353                            e[j] = cs * e[j];
    354
    355                            for (int i = 0; i < m; i++) {
    356                                t = cs * U[i][j] + sn * U[i][k - 1];
    357                                U[i][k - 1] = -sn * U[i][j] + cs * U[i][k - 1];
    358                                U[i][j] = t;
    359                            }
    360                        }
    361                    }
    362                    break;
    363                    // Perform one qr step.
    364                    case 3: {
    365                        // Calculate the shift.
    366                        final double maxPm1Pm2 = FastMath.max(FastMath.abs(singularValues[p - 1]),
    367                                                              FastMath.abs(singularValues[p - 2]));
    368                        final double scale = FastMath.max(FastMath.max(FastMath.max(maxPm1Pm2,
    369                                                                                    FastMath.abs(e[p - 2])),
    370                                                                       FastMath.abs(singularValues[k])),
    371                                                          FastMath.abs(e[k]));
    372                        final double sp = singularValues[p - 1] / scale;
    373                        final double spm1 = singularValues[p - 2] / scale;
    374                        final double epm1 = e[p - 2] / scale;
    375                        final double sk = singularValues[k] / scale;
    376                        final double ek = e[k] / scale;
    377                        final double b = ((spm1 + sp) * (spm1 - sp) + epm1 * epm1) / 2.0;
    378                        final double c = (sp * epm1) * (sp * epm1);
    379                        double shift = 0;
    380                        if (b != 0 ||
    381                            c != 0) {
    382                            shift = FastMath.sqrt(b * b + c);
    383                            if (b < 0) {
    384                                shift = -shift;
    385                            }
    386                            shift = c / (b + shift);
    387                        }
    388                        double f = (sk + sp) * (sk - sp) + shift;
    389                        double g = sk * ek;
    390                        // Chase zeros.
    391                        for (int j = k; j < p - 1; j++) {
    392                            double t = FastMath.hypot(f, g);
    393                            double cs = f / t;
    394                            double sn = g / t;
    395                            if (j != k) {
    396                                e[j - 1] = t;
    397                            }
    398                            f = cs * singularValues[j] + sn * e[j];
    399                            e[j] = cs * e[j] - sn * singularValues[j];
    400                            g = sn * singularValues[j + 1];
    401                            singularValues[j + 1] = cs * singularValues[j + 1];
    402
    403                            for (int i = 0; i < n; i++) {
    404                                t = cs * V[i][j] + sn * V[i][j + 1];
    405                                V[i][j + 1] = -sn * V[i][j] + cs * V[i][j + 1];
    406                                V[i][j] = t;
    407                            }
    408                            t = FastMath.hypot(f, g);
    409                            cs = f / t;
    410                            sn = g / t;
    411                            singularValues[j] = t;
    412                            f = cs * e[j] + sn * singularValues[j + 1];
    413                            singularValues[j + 1] = -sn * e[j] + cs * singularValues[j + 1];
    414                            g = sn * e[j + 1];
    415                            e[j + 1] = cs * e[j + 1];
    416                            if (j < m - 1) {
    417                                for (int i = 0; i < m; i++) {
    418                                    t = cs * U[i][j] + sn * U[i][j + 1];
    419                                    U[i][j + 1] = -sn * U[i][j] + cs * U[i][j + 1];
    420                                    U[i][j] = t;
    421                                }
    422                            }
    423                        }
    424                        e[p - 2] = f;
    425                        iter = iter + 1;
    426                    }
    427                    break;
    428                    // Convergence.
    429                    default: {
    430                        // Make the singular values positive.
    431                        if (singularValues[k] <= 0) {
    432                            singularValues[k] = singularValues[k] < 0 ? -singularValues[k] : 0;
    433
    434                            for (int i = 0; i <= pp; i++) {
    435                                V[i][k] = -V[i][k];
    436                            }
    437                        }
    438                        // Order the singular values.
    439                        while (k < pp) {
    440                            if (singularValues[k] >= singularValues[k + 1]) {
    441                                break;
    442                            }
    443                            double t = singularValues[k];
    444                            singularValues[k] = singularValues[k + 1];
    445                            singularValues[k + 1] = t;
    446                            if (k < n - 1) {
    447                                for (int i = 0; i < n; i++) {
    448                                    t = V[i][k + 1];
    449                                    V[i][k + 1] = V[i][k];
    450                                    V[i][k] = t;
    451                                }
    452                            }
    453                            if (k < m - 1) {
    454                                for (int i = 0; i < m; i++) {
    455                                    t = U[i][k + 1];
    456                                    U[i][k + 1] = U[i][k];
    457                                    U[i][k] = t;
    458                                }
    459                            }
    460                            k++;
    461                        }
    462                        iter = 0;
    463                        p--;
    464                    }
    465                    break;
    466                }
    467            }
    468
    469            // Set the small value tolerance used to calculate rank and pseudo-inverse
    470            tol = FastMath.max(m * singularValues[0] * EPS,
    471                               FastMath.sqrt(Precision.SAFE_MIN));
    472
    473            if (!transposed) {
    474                cachedU = MatrixUtils.createRealMatrix(U);
    475                cachedV = MatrixUtils.createRealMatrix(V);
    476            } else {
    477                cachedU = MatrixUtils.createRealMatrix(V);
    478                cachedV = MatrixUtils.createRealMatrix(U);
    479            }
    480        }
    481
    482        /**
    483         * Returns the matrix U of the decomposition.
    484         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    485         * @return the U matrix
    486         * @see #getUT()
    487         */
    488        public RealMatrix getU() {
    489            // return the cached matrix
    490            return cachedU;
    491
    492        }
    493
    494        /**
    495         * Returns the transpose of the matrix U of the decomposition.
    496         * <p>U is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    497         * @return the U matrix (or null if decomposed matrix is singular)
    498         * @see #getU()
    499         */
    500        public RealMatrix getUT() {
    501            if (cachedUt == null) {
    502                cachedUt = getU().transpose();
    503            }
    504            // return the cached matrix
    505            return cachedUt;
    506        }
    507
    508        /**
    509         * Returns the diagonal matrix &Sigma; of the decomposition.
    510         * <p>&Sigma; is a diagonal matrix. The singular values are provided in
    511         * non-increasing order, for compatibility with Jama.</p>
    512         * @return the &Sigma; matrix
    513         */
    514        public RealMatrix getS() {
    515            if (cachedS == null) {
    516                // cache the matrix for subsequent calls
    517                cachedS = MatrixUtils.createRealDiagonalMatrix(singularValues);
    518            }
    519            return cachedS;
    520        }
    521
    522        /**
    523         * Returns the diagonal elements of the matrix &Sigma; of the decomposition.
    524         * <p>The singular values are provided in non-increasing order, for
    525         * compatibility with Jama.</p>
    526         * @return the diagonal elements of the &Sigma; matrix
    527         */
    528        public double[] getSingularValues() {
    529            return singularValues.clone();
    530        }
    531
    532        /**
    533         * Returns the matrix V of the decomposition.
    534         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    535         * @return the V matrix (or null if decomposed matrix is singular)
    536         * @see #getVT()
    537         */
    538        public RealMatrix getV() {
    539            // return the cached matrix
    540            return cachedV;
    541        }
    542
    543        /**
    544         * Returns the transpose of the matrix V of the decomposition.
    545         * <p>V is an orthogonal matrix, i.e. its transpose is also its inverse.</p>
    546         * @return the V matrix (or null if decomposed matrix is singular)
    547         * @see #getV()
    548         */
    549        public RealMatrix getVT() {
    550            if (cachedVt == null) {
    551                cachedVt = getV().transpose();
    552            }
    553            // return the cached matrix
    554            return cachedVt;
    555        }
    556
    557        /**
    558         * Returns the n &times; n covariance matrix.
    559         * <p>The covariance matrix is V &times; J &times; V<sup>T</sup>
    560         * where J is the diagonal matrix of the inverse of the squares of
    561         * the singular values.</p>
    562         * @param minSingularValue value below which singular values are ignored
    563         * (a 0 or negative value implies all singular value will be used)
    564         * @return covariance matrix
    565         * @exception IllegalArgumentException if minSingularValue is larger than
    566         * the largest singular value, meaning all singular values are ignored
    567         */
    568        public RealMatrix getCovariance(final double minSingularValue) {
    569            // get the number of singular values to consider
    570            final int p = singularValues.length;
    571            int dimension = 0;
    572            while (dimension < p &&
    573                   singularValues[dimension] >= minSingularValue) {
    574                ++dimension;
    575            }
    576
    577            if (dimension == 0) {
    578                throw new NumberIsTooLargeException(LocalizedFormats.TOO_LARGE_CUTOFF_SINGULAR_VALUE,
    579                                                    minSingularValue, singularValues[0], true);
    580            }
    581
    582            final double[][] data = new double[dimension][p];
    583            getVT().walkInOptimizedOrder(new DefaultRealMatrixPreservingVisitor() {
    584                /** {@inheritDoc} */
    585                @Override
    586                public void visit(final int row, final int column,
    587                        final double value) {
    588                    data[row][column] = value / singularValues[row];
    589                }
    590            }, 0, dimension - 1, 0, p - 1);
    591
    592            RealMatrix jv = new Array2DRowRealMatrix(data, false);
    593            return jv.transpose().multiply(jv);
    594        }
    595
    596        /**
    597         * Returns the L<sub>2</sub> norm of the matrix.
    598         * <p>The L<sub>2</sub> norm is max(|A &times; u|<sub>2</sub> /
    599         * |u|<sub>2</sub>), where |.|<sub>2</sub> denotes the vectorial 2-norm
    600         * (i.e. the traditional euclidian norm).</p>
    601         * @return norm
    602         */
    603        public double getNorm() {
    604            return singularValues[0];
    605        }
    606
    607        /**
    608         * Return the condition number of the matrix.
    609         * @return condition number of the matrix
    610         */
    611        public double getConditionNumber() {
    612            return singularValues[0] / singularValues[n - 1];
    613        }
    614
    615        /**
    616         * Computes the inverse of the condition number.
    617         * In cases of rank deficiency, the {@link #getConditionNumber() condition
    618         * number} will become undefined.
    619         *
    620         * @return the inverse of the condition number.
    621         */
    622        public double getInverseConditionNumber() {
    623            return singularValues[n - 1] / singularValues[0];
    624        }
    625
    626        /**
    627         * Return the effective numerical matrix rank.
    628         * <p>The effective numerical rank is the number of non-negligible
    629         * singular values. The threshold used to identify non-negligible
    630         * terms is max(m,n) &times; ulp(s<sub>1</sub>) where ulp(s<sub>1</sub>)
    631         * is the least significant bit of the largest singular value.</p>
    632         * @return effective numerical matrix rank
    633         */
    634        public int getRank() {
    635            int r = 0;
    636            for (int i = 0; i < singularValues.length; i++) {
    637                if (singularValues[i] > tol) {
    638                    r++;
    639                }
    640            }
    641            return r;
    642        }
    643
    644        /**
    645         * Get a solver for finding the A &times; X = B solution in least square sense.
    646         * @return a solver
    647         */
    648        public DecompositionSolver getSolver() {
    649            return new Solver(singularValues, getUT(), getV(), getRank() == m, tol);
    650        }
    651
    652        /** Specialized solver. */
    653        private static class Solver implements DecompositionSolver {
    654            /** Pseudo-inverse of the initial matrix. */
    655            private final RealMatrix pseudoInverse;
    656            /** Singularity indicator. */
    657            private boolean nonSingular;
    658
    659            /**
    660             * Build a solver from decomposed matrix.
    661             *
    662             * @param singularValues Singular values.
    663             * @param uT U<sup>T</sup> matrix of the decomposition.
    664             * @param v V matrix of the decomposition.
    665             * @param nonSingular Singularity indicator.
    666             * @param tol tolerance for singular values
    667             */
    668            private Solver(final double[] singularValues, final RealMatrix uT,
    669                           final RealMatrix v, final boolean nonSingular, final double tol) {
    670                final double[][] suT = uT.getData();
    671                for (int i = 0; i < singularValues.length; ++i) {
    672                    final double a;
    673                    if (singularValues[i] > tol) {
    674                        a = 1 / singularValues[i];
    675                    } else {
    676                        a = 0;
    677                    }
    678                    final double[] suTi = suT[i];
    679                    for (int j = 0; j < suTi.length; ++j) {
    680                        suTi[j] *= a;
    681                    }
    682                }
    683                pseudoInverse = v.multiply(new Array2DRowRealMatrix(suT, false));
    684                this.nonSingular = nonSingular;
    685            }
    686
    687            /**
    688             * Solve the linear equation A &times; X = B in least square sense.
    689             * <p>
    690             * The m&times;n matrix A may not be square, the solution X is such that
    691             * ||A &times; X - B|| is minimal.
    692             * </p>
    693             * @param b Right-hand side of the equation A &times; X = B
    694             * @return a vector X that minimizes the two norm of A &times; X - B
    695             * @throws org.apache.commons.math3.exception.DimensionMismatchException
    696             * if the matrices dimensions do not match.
    697             */
    698            public RealVector solve(final RealVector b) {
    699                return pseudoInverse.operate(b);
    700            }
    701
    702            /**
    703             * Solve the linear equation A &times; X = B in least square sense.
    704             * <p>
    705             * The m&times;n matrix A may not be square, the solution X is such that
    706             * ||A &times; X - B|| is minimal.
    707             * </p>
    708             *
    709             * @param b Right-hand side of the equation A &times; X = B
    710             * @return a matrix X that minimizes the two norm of A &times; X - B
    711             * @throws org.apache.commons.math3.exception.DimensionMismatchException
    712             * if the matrices dimensions do not match.
    713             */
    714            public RealMatrix solve(final RealMatrix b) {
    715                return pseudoInverse.multiply(b);
    716            }
    717
    718            /**
    719             * Check if the decomposed matrix is non-singular.
    720             *
    721             * @return {@code true} if the decomposed matrix is non-singular.
    722             */
    723            public boolean isNonSingular() {
    724                return nonSingular;
    725            }
    726
    727            /**
    728             * Get the pseudo-inverse of the decomposed matrix.
    729             *
    730             * @return the inverse matrix.
    731             */
    732            public RealMatrix getInverse() {
    733                return pseudoInverse;
    734            }
    735        }
    736    }