mathjs 11.12.0 → 12.1.0

package/lib/esm/function/matrix/eigs/complexEigs.js

@@ -11,6 +11,8 @@ export function createComplexEigs(_ref) {
     abs,
     bignumber,
     diag,
+    size,
+    reshape,
     inv,
     qr,
     usolve,
@@ -31,11 +33,8 @@ export function createComplexEigs(_ref) {
    *
    * @returns {{ values: number[], vectors: number[][] }}
    */
-  function complexEigs(arr, N, prec, type, findVectors) {
-    if (findVectors === undefined) {
-      findVectors = true;
-    }
-
+  function complexEigs(arr, N, prec, type) {
+    var findVectors = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : true;
     // TODO check if any row/col are zero except the diagonal
 
     // make sure corresponding rows and columns have similar magnitude
@@ -44,9 +43,9 @@ export function createComplexEigs(_ref) {
     var R = balance(arr, N, prec, type, findVectors);
 
     // R is the row transformation matrix
-    // arr = A' = R A R⁻¹, A is the original matrix
+    // arr = A' = R A R^-1, A is the original matrix
     // (if findVectors is false, R is undefined)
-    // (And so to return to original matrix: A = R⁻¹ arr R)
+    // (And so to return to original matrix: A = R^-1 arr R)
 
     // TODO if magnitudes of elements vary over many orders,
     // move greatest elements to the top left corner
@@ -56,7 +55,7 @@ export function createComplexEigs(_ref) {
     // updates the transformation matrix R with new row operationsq
     // MODIFIES arr by side effect!
     reduceToHessenberg(arr, N, prec, type, findVectors, R);
-    // still true that original A = R⁻¹ arr R)
+    // still true that original A = R^-1 arr R)
 
     // find eigenvalues
     var {
@@ -67,17 +66,18 @@ export function createComplexEigs(_ref) {
     // values is the list of eigenvalues, C is the column
     // transformation matrix that transforms arr, the hessenberg
     // matrix, to upper triangular
-    // (So U = C⁻¹ arr C and the relationship between current arr
+    // (So U = C^-1 arr C and the relationship between current arr
     // and original A is unchanged.)
 
-    var vectors;
     if (findVectors) {
-      vectors = findEigenvectors(arr, N, C, R, values, prec, type);
-      vectors = matrixFromColumns(...vectors);
+      var eigenvectors = findEigenvectors(arr, N, C, R, values, prec, type);
+      return {
+        values,
+        eigenvectors
+      };
     }
     return {
-      values,
-      vectors
+      values
     };
   }
 
@@ -117,9 +117,8 @@ export function createComplexEigs(_ref) {
         var rowNorm = realzero;
         for (var j = 0; j < N; j++) {
           if (i === j) continue;
-          var c = abs(arr[i][j]); // should be real
-          colNorm = addScalar(colNorm, c);
-          rowNorm = addScalar(rowNorm, c);
+          colNorm = addScalar(colNorm, abs(arr[j][i]));
+          rowNorm = addScalar(rowNorm, abs(arr[i][j]));
         }
         if (!equal(colNorm, 0) && !equal(rowNorm, 0)) {
           // find integer power closest to balancing the matrix
@@ -127,21 +126,21 @@ export function createComplexEigs(_ref) {
           // so that we don't lose any precision due to round-off)
 
           var f = realone;
-          var _c = colNorm;
+          var c = colNorm;
           var rowDivRadix = divideScalar(rowNorm, radix);
           var rowMulRadix = multiplyScalar(rowNorm, radix);
-          while (smaller(_c, rowDivRadix)) {
-            _c = multiplyScalar(_c, radixSq);
+          while (smaller(c, rowDivRadix)) {
+            c = multiplyScalar(c, radixSq);
             f = multiplyScalar(f, radix);
           }
-          while (larger(_c, rowMulRadix)) {
-            _c = divideScalar(_c, radixSq);
+          while (larger(c, rowMulRadix)) {
+            c = divideScalar(c, radixSq);
             f = divideScalar(f, radix);
           }
 
           // check whether balancing is needed
           // condition = (c + rowNorm) / f < 0.95 * (colNorm + rowNorm)
-          var condition = smaller(divideScalar(addScalar(_c, rowNorm), f), multiplyScalar(addScalar(colNorm, rowNorm), 0.95));
+          var condition = smaller(divideScalar(addScalar(c, rowNorm), f), multiplyScalar(addScalar(colNorm, rowNorm), 0.95));
 
           // apply balancing similarity transformation
           if (condition) {
@@ -153,13 +152,13 @@ export function createComplexEigs(_ref) {
               if (i === _j) {
                 continue;
               }
-              arr[i][_j] = multiplyScalar(arr[i][_j], f);
-              arr[_j][i] = multiplyScalar(arr[_j][i], g);
+              arr[i][_j] = multiplyScalar(arr[i][_j], g);
+              arr[_j][i] = multiplyScalar(arr[_j][i], f);
             }
 
             // keep track of transformations
             if (findVectors) {
-              Rdiag[i] = multiplyScalar(Rdiag[i], f);
+              Rdiag[i] = multiplyScalar(Rdiag[i], g);
             }
           }
         }
@@ -167,7 +166,7 @@ export function createComplexEigs(_ref) {
     }
 
     // return the diagonal row transformation matrix
-    return diag(Rdiag);
+    return findVectors ? diag(Rdiag) : null;
   }
 
   /**
@@ -266,7 +265,7 @@ export function createComplexEigs(_ref) {
 
     // The Francis Algorithm
     // The core idea of this algorithm is that doing successive
-    // A' = Q⁺AQ transformations will eventually converge to block-
+    // A' = QtAQ transformations will eventually converge to block-
     // upper-triangular with diagonal blocks either 1x1 or 2x2.
     // The Q here is the one from the QR decomposition, A = QR.
     // Since the eigenvalues of a block-upper-triangular matrix are
@@ -288,7 +287,7 @@ export function createComplexEigs(_ref) {
     // N×N matrix describing the overall transformation done during the QR algorithm
     var Qtotal = findVectors ? diag(Array(N).fill(one)) : undefined;
 
-    // n×n matrix describing the QR transformations done since last convergence
+    // nxn matrix describing the QR transformations done since last convergence
     var Qpartial = findVectors ? diag(Array(n).fill(one)) : undefined;
 
     // last eigenvalue converged before this many steps
@@ -300,7 +299,12 @@ export function createComplexEigs(_ref) {
 
       // Perform the factorization
 
-      var k = 0; // TODO set close to an eigenvalue
+      var k = arr[n - 1][n - 1]; // TODO this is apparently a somewhat
+      // old-fashioned choice; ideally set close to an eigenvalue, or
+      // perhaps better yet switch to the implicit QR version that is sometimes
+      // specifically called the "Francis algorithm" that is alluded to
+      // in the following TODO. (Or perhaps we switch to an independently
+      // optimized third-party package for the linear algebra operations...)
 
       for (var i = 0; i < n; i++) {
         arr[i][i] = subtract(arr[i][i], k);
@@ -414,17 +418,17 @@ export function createComplexEigs(_ref) {
     // this way it is easier to find eigenvectors
     var uniqueValues = [];
     var multiplicities = [];
-    for (var λ of values) {
-      var i = indexOf(uniqueValues, λ, equal);
+    for (var lambda of values) {
+      var i = indexOf(uniqueValues, lambda, equal);
       if (i === -1) {
-        uniqueValues.push(λ);
+        uniqueValues.push(lambda);
         multiplicities.push(1);
       } else {
         multiplicities[i] += 1;
       }
     }
 
-    // find eigenvectors by solving U − λE = 0
+    // find eigenvectors by solving U − lambdaE = 0
     // TODO replace with an iterative eigenvector algorithm
     // (this one might fail for imprecise eigenvalues)
 
@@ -432,41 +436,35 @@ export function createComplexEigs(_ref) {
     var len = uniqueValues.length;
     var b = Array(N).fill(zero);
     var E = diag(Array(N).fill(one));
-
-    // eigenvalues for which usolve failed (due to numerical error)
-    var failedLambdas = [];
     var _loop = function _loop() {
-      var λ = uniqueValues[_i4];
-      var S = subtract(U, multiply(λ, E)); // the characteristic matrix
+      var lambda = uniqueValues[_i4];
+      var S = subtract(U, multiply(lambda, E)); // the characteristic matrix
 
       var solutions = usolveAll(S, b);
       solutions.shift(); // ignore the null vector
 
       // looks like we missed something, try inverse iteration
+      // But if that fails, just presume that the original matrix truly
+      // was defective.
       while (solutions.length < multiplicities[_i4]) {
         var approxVec = inverseIterate(S, N, solutions, prec, type);
-        if (approxVec == null) {
-          // no more vectors were found
-          failedLambdas.push(λ);
+        if (approxVec === null) {
           break;
-        }
+        } // no more vectors were found
         solutions.push(approxVec);
       }
 
       // Transform back into original array coordinates
       var correction = multiply(inv(R), C);
       solutions = solutions.map(v => multiply(correction, v));
-      vectors.push(...solutions.map(v => flatten(v)));
+      vectors.push(...solutions.map(v => ({
+        value: lambda,
+        vector: flatten(v)
+      })));
     };
     for (var _i4 = 0; _i4 < len; _i4++) {
       _loop();
     }
-    if (failedLambdas.length !== 0) {
-      var err = new Error('Failed to find eigenvectors for the following eigenvalues: ' + failedLambdas.join(', '));
-      err.values = values;
-      err.vectors = vectors;
-      throw err;
-    }
     return vectors;
   }
 
@@ -475,7 +473,7 @@ export function createComplexEigs(_ref) {
    * @return {[number,number]}
    */
   function eigenvalues2x2(a, b, c, d) {
-    // λ± = ½ trA ± ½ √( tr²A - 4 detA )
+    // lambda_+- = 1/2 trA +- 1/2 sqrt( tr^2 A - 4 detA )
     var trA = addScalar(a, d);
     var detA = subtract(multiplyScalar(a, d), multiplyScalar(b, c));
     var x = multiplyScalar(trA, 0.5);
@@ -485,7 +483,7 @@ export function createComplexEigs(_ref) {
 
   /**
    * For an 2x2 matrix compute the transformation matrix S,
-   * so that SAS⁻¹ is an upper triangular matrix
+   * so that SAS^-1 is an upper triangular matrix
    * @return {[[number,number],[number,number]]}
    * @see https://math.berkeley.edu/~ogus/old/Math_54-05/webfoils/jordan.pdf
    * @see http://people.math.harvard.edu/~knill/teaching/math21b2004/exhibits/2dmatrices/index.html
@@ -509,23 +507,22 @@ export function createComplexEigs(_ref) {
     }
 
     // matrix is not diagonalizable
-    // compute off-diagonal elements of N = A - λI
-    // N₁₂ = 0 ⇒ S = ( N⃗₁, I⃗₁ )
-    // N₁₂ ≠ 0 ⇒ S = ( N⃗₂, I⃗₂ )
-
+    // compute diagonal elements of N = A - lambdaI
     var na = subtract(a, l1);
-    var nb = subtract(b, l1);
-    var nc = subtract(c, l1);
     var nd = subtract(d, l1);
-    if (smaller(abs(nb), prec)) {
-      return [[na, one], [nc, zero]];
+
+    // col(N,2) = 0  implies  S = ( col(N,1), e_1 )
+    // col(N,2) != 0 implies  S = ( col(N,2), e_2 )
+
+    if (smaller(abs(b), prec) && smaller(abs(nd), prec)) {
+      return [[na, one], [c, zero]];
     } else {
-      return [[nb, zero], [nd, one]];
+      return [[b, zero], [nd, one]];
     }
   }
 
   /**
-   * Enlarge the matrix from n×n to N×N, setting the new
+   * Enlarge the matrix from nxn to NxN, setting the new
    * elements to 1 on diagonal and 0 elsewhere
    */
   function inflateMatrix(arr, N) {
@@ -602,15 +599,21 @@ export function createComplexEigs(_ref) {
 
     // you better choose a random vector before I count to five
     var i = 0;
-    while (true) {
+    for (; i < 5; ++i) {
       b = randomOrthogonalVector(N, orthog, type);
-      b = usolve(A, b);
+      try {
+        b = usolve(A, b);
+      } catch (_unused) {
+        // That direction didn't work, likely because the original matrix
+        // was defective. But still make the full number of tries...
+        continue;
+      }
       if (larger(norm(b), largeNum)) {
         break;
       }
-      if (++i >= 5) {
-        return null;
-      }
+    }
+    if (i >= 5) {
+      return null; // couldn't find any orthogonal vector in the image
     }
 
     // you better converge before I count to ten
@@ -660,8 +663,10 @@ export function createComplexEigs(_ref) {
    * Project vector v to the orthogonal complement of an array of vectors
    */
   function orthogonalComplement(v, orthog) {
+    var vectorShape = size(v);
     for (var w of orthog) {
-      // v := v − (w, v)/∥w∥² w
+      w = reshape(w, vectorShape); // make sure this is just a vector computation
+      // v := v − (w, v)/|w|^2 w
       v = subtract(v, multiply(divideScalar(dot(w, v), dot(w, w)), w));
     }
     return v;

package/lib/esm/function/matrix/eigs/{realSymetric.js → realSymmetric.js}

@@ -23,25 +23,29 @@ export function createRealSymmetric(_ref) {
   function main(arr, N) {
     var prec = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : config.epsilon;
     var type = arguments.length > 3 ? arguments[3] : undefined;
+    var computeVectors = arguments.length > 4 ? arguments[4] : undefined;
     if (type === 'number') {
-      return diag(arr, prec);
+      return diag(arr, prec, computeVectors);
     }
     if (type === 'BigNumber') {
-      return diagBig(arr, prec);
+      return diagBig(arr, prec, computeVectors);
     }
     throw TypeError('Unsupported data type: ' + type);
   }
 
   // diagonalization implementation for number (efficient)
-  function diag(x, precision) {
+  function diag(x, precision, computeVectors) {
     var N = x.length;
     var e0 = Math.abs(precision / N);
     var psi;
-    var Sij = new Array(N);
-    // Sij is Identity Matrix
-    for (var i = 0; i < N; i++) {
-      Sij[i] = createArray(N, 0);
-      Sij[i][i] = 1.0;
+    var Sij;
+    if (computeVectors) {
+      Sij = new Array(N);
+      // Sij is Identity Matrix
+      for (var i = 0; i < N; i++) {
+        Sij[i] = Array(N).fill(0);
+        Sij[i][i] = 1.0;
+      }
     }
     // initial error
     var Vab = getAij(x);
@@ -50,26 +54,29 @@ export function createRealSymmetric(_ref) {
       var j = Vab[0][1];
       psi = getTheta(x[_i][_i], x[j][j], x[_i][j]);
       x = x1(x, psi, _i, j);
-      Sij = Sij1(Sij, psi, _i, j);
+      if (computeVectors) Sij = Sij1(Sij, psi, _i, j);
       Vab = getAij(x);
     }
-    var Ei = createArray(N, 0); // eigenvalues
+    var Ei = Array(N).fill(0); // eigenvalues
     for (var _i2 = 0; _i2 < N; _i2++) {
       Ei[_i2] = x[_i2][_i2];
     }
-    return sorting(clone(Ei), clone(Sij));
+    return sorting(clone(Ei), Sij, computeVectors);
   }
 
   // diagonalization implementation for bigNumber
-  function diagBig(x, precision) {
+  function diagBig(x, precision, computeVectors) {
     var N = x.length;
     var e0 = abs(precision / N);
     var psi;
-    var Sij = new Array(N);
-    // Sij is Identity Matrix
-    for (var i = 0; i < N; i++) {
-      Sij[i] = createArray(N, 0);
-      Sij[i][i] = 1.0;
+    var Sij;
+    if (computeVectors) {
+      Sij = new Array(N);
+      // Sij is Identity Matrix
+      for (var i = 0; i < N; i++) {
+        Sij[i] = Array(N).fill(0);
+        Sij[i][i] = 1.0;
+      }
     }
     // initial error
     var Vab = getAijBig(x);
@@ -78,15 +85,15 @@ export function createRealSymmetric(_ref) {
       var j = Vab[0][1];
       psi = getThetaBig(x[_i3][_i3], x[j][j], x[_i3][j]);
       x = x1Big(x, psi, _i3, j);
-      Sij = Sij1Big(Sij, psi, _i3, j);
+      if (computeVectors) Sij = Sij1Big(Sij, psi, _i3, j);
       Vab = getAijBig(x);
     }
-    var Ei = createArray(N, 0); // eigenvalues
+    var Ei = Array(N).fill(0); // eigenvalues
     for (var _i4 = 0; _i4 < N; _i4++) {
       Ei[_i4] = x[_i4][_i4];
     }
     // return [clone(Ei), clone(Sij)]
-    return sorting(clone(Ei), clone(Sij));
+    return sorting(clone(Ei), Sij, computeVectors);
   }
 
   // get angle
@@ -114,8 +121,8 @@ export function createRealSymmetric(_ref) {
     var N = Sij.length;
     var c = Math.cos(theta);
     var s = Math.sin(theta);
-    var Ski = createArray(N, 0);
-    var Skj = createArray(N, 0);
+    var Ski = Array(N).fill(0);
+    var Skj = Array(N).fill(0);
     for (var k = 0; k < N; k++) {
       Ski[k] = c * Sij[k][i] - s * Sij[k][j];
       Skj[k] = s * Sij[k][i] + c * Sij[k][j];
@@ -131,8 +138,8 @@ export function createRealSymmetric(_ref) {
     var N = Sij.length;
     var c = cos(theta);
     var s = sin(theta);
-    var Ski = createArray(N, bignumber(0));
-    var Skj = createArray(N, bignumber(0));
+    var Ski = Array(N).fill(bignumber(0));
+    var Skj = Array(N).fill(bignumber(0));
     for (var k = 0; k < N; k++) {
       Ski[k] = subtract(multiplyScalar(c, Sij[k][i]), multiplyScalar(s, Sij[k][j]));
       Skj[k] = addScalar(multiplyScalar(s, Sij[k][i]), multiplyScalar(c, Sij[k][j]));
@@ -151,8 +158,8 @@ export function createRealSymmetric(_ref) {
     var s = bignumber(sin(theta));
     var c2 = multiplyScalar(c, c);
     var s2 = multiplyScalar(s, s);
-    var Aki = createArray(N, bignumber(0));
-    var Akj = createArray(N, bignumber(0));
+    var Aki = Array(N).fill(bignumber(0));
+    var Akj = Array(N).fill(bignumber(0));
     // 2cs Hij
     var csHij = multiply(bignumber(2), c, s, Hij[i][j]);
     //  Aii
@@ -187,8 +194,8 @@ export function createRealSymmetric(_ref) {
     var s = Math.sin(theta);
     var c2 = c * c;
     var s2 = s * s;
-    var Aki = createArray(N, 0);
-    var Akj = createArray(N, 0);
+    var Aki = Array(N).fill(0);
+    var Akj = Array(N).fill(0);
     //  Aii
     var Aii = c2 * Hij[i][i] - 2 * c * s * Hij[i][j] + s2 * Hij[j][j];
     var Ajj = s2 * Hij[i][i] + 2 * c * s * Hij[i][j] + c2 * Hij[j][j];
@@ -247,12 +254,15 @@ export function createRealSymmetric(_ref) {
   }
 
   // sort results
-  function sorting(E, S) {
+  function sorting(E, S, computeVectors) {
     var N = E.length;
     var values = Array(N);
-    var vectors = Array(N);
-    for (var k = 0; k < N; k++) {
-      vectors[k] = Array(N);
+    var vecs;
+    if (computeVectors) {
+      vecs = Array(N);
+      for (var k = 0; k < N; k++) {
+        vecs[k] = Array(N);
+      }
     }
     for (var i = 0; i < N; i++) {
       var minID = 0;
@@ -264,30 +274,24 @@ export function createRealSymmetric(_ref) {
         }
       }
       values[i] = E.splice(minID, 1)[0];
-      for (var _k5 = 0; _k5 < N; _k5++) {
-        vectors[_k5][i] = S[_k5][minID];
-        S[_k5].splice(minID, 1);
+      if (computeVectors) {
+        for (var _k5 = 0; _k5 < N; _k5++) {
+          vecs[i][_k5] = S[_k5][minID];
+          S[_k5].splice(minID, 1);
+        }
       }
     }
+    if (!computeVectors) return {
+      values
+    };
+    var eigenvectors = vecs.map((vector, i) => ({
+      value: values[i],
+      vector
+    }));
     return {
       values,
-      vectors
+      eigenvectors
     };
   }
-
-  /**
-   * Create an array of a certain size and fill all items with an initial value
-   * @param {number} size
-   * @param {number} value
-   * @return {number[]}
-   */
-  function createArray(size, value) {
-    // TODO: as soon as all browsers support Array.fill, use that instead (IE doesn't support it)
-    var array = new Array(size);
-    for (var i = 0; i < size; i++) {
-      array[i] = value;
-    }
-    return array;
-  }
   return main;
 }