Matrix creation and conversion methods (josdejong#2155)

* made dense and sparse matrices iterable, fixed josdejong#1184

* added matrixFromFunction, fixes josdejong#2153

* added tests for matrixFromFunction

* added matrixFromRows

* added matrixFromColumns

* added rows() and columns() for dense matrix

* improved sparse documentation a tiny bit

* fix linting issues

* added matrixFromRow/Column to seealso of row and column

* removed unnecessary duplication from matrixFromRows/Columns

* added babel runtime

Co-authored-by: Jos de Jong <[email protected]>

.babelrc

@@ -3,7 +3,8 @@
     ["@babel/preset-env"]
   ],
   "plugins": [
-    "@babel/plugin-transform-object-assign"
+    "@babel/plugin-transform-object-assign",
+    "@babel/transform-runtime"
   ],
   "ignore": [
     "lib/**/*.js"

package.json

@@ -25,6 +25,7 @@
     "unit"
   ],
   "dependencies": {
+    "@babel/runtime": "^7.13.17",
     "complex.js": "^2.0.11",
     "decimal.js": "^10.2.1",
     "escape-latex": "^1.2.0",
@@ -37,6 +38,7 @@
   "devDependencies": {
     "@babel/core": "7.13.14",
     "@babel/plugin-transform-object-assign": "7.12.13",
+    "@babel/plugin-transform-runtime": "^7.13.15",
     "@babel/preset-env": "7.13.12",
     "@babel/register": "7.13.14",
     "babel-loader": "8.2.2",

src/expression/embeddedDocs/embeddedDocs.js

@@ -202,6 +202,9 @@ import { splitUnitDocs } from './construction/splitUnit.js'
 import { sparseDocs } from './construction/sparse.js'
 import { numberDocs } from './construction/number.js'
 import { matrixDocs } from './construction/matrix.js'
+import { matrixFromFunctionDocs } from './function/matrix/matrixFromFunction.js'
+import { matrixFromRowsDocs } from './function/matrix/matrixFromRows.js'
+import { matrixFromColumnsDocs } from './function/matrix/matrixFromColumns.js'
 import { indexDocs } from './construction/index.js'
 import { fractionDocs } from './construction/fraction.js'
 import { createUnitDocs } from './construction/createUnit.js'
@@ -424,6 +427,9 @@ export const embeddedDocs = {
   inv: invDocs,
   eigs: eigsDocs,
   kron: kronDocs,
+  matrixFromFunction: matrixFromFunctionDocs,
+  matrixFromRows: matrixFromRowsDocs,
+  matrixFromColumns: matrixFromColumnsDocs,
   map: mapDocs,
   ones: onesDocs,
   partitionSelect: partitionSelectDocs,

src/expression/embeddedDocs/function/matrix/column.js

@@ -10,5 +10,5 @@ export const columnDocs = {
     'column(A, 1)',
     'column(A, 2)'
   ],
-  seealso: ['row']
+  seealso: ['row', 'matrixFromColumns']
 }

src/expression/embeddedDocs/function/matrix/matrixFromColumns.js

@@ -0,0 +1,16 @@
+export const matrixFromColumnsDocs = {
+  name: 'matrixFromColumns',
+  category: 'Matrix',
+  syntax: [
+    'math.matrixFromColumns(...arr)',
+    'math.matrixFromColumns(row1, row2)',
+    'math.matrixFromColumns(row1, row2, row3)'
+  ],
+  description: 'Create a dense matrix from vectors as individual columns.',
+  examples: [
+    'matrixFromColumns([1, 2, 3], [[4],[5],[6]])'
+  ],
+  seealso: [
+    'matrix', 'matrixFromRows', 'matrixFromFunction', 'zeros'
+  ]
+}

src/expression/embeddedDocs/function/matrix/matrixFromFunction.js

@@ -0,0 +1,22 @@
+export const matrixFromFunctionDocs = {
+  name: 'matrixFromFunction',
+  category: 'Matrix',
+  syntax: [
+    'math.matrixFromFunction(size, fn)',
+    'math.matrixFromFunction(size, fn, format)',
+    'math.matrixFromFunction(size, fn, format, datatype)',
+    'math.matrixFromFunction(size, format, fn)',
+    'math.matrixFromFunction(size, format, datatype, fn)'
+  ],
+  description: 'Create a matrix by evaluating a generating function at each index.',
+  examples: [
+    'f(I) = I[1] - I[2]',
+    'matrixFromFunction([3,3], f)',
+    'g(I) = I[1] - I[2] == 1 ? 4 : 0',
+    'matrixFromFunction([100, 100], "sparse", g)',
+    'matrixFromFunction([5], random)'
+  ],
+  seealso: [
+    'matrix', 'matrixFromRows', 'matrixFromColumns', 'zeros'
+  ]
+}

src/expression/embeddedDocs/function/matrix/matrixFromRows.js

@@ -0,0 +1,16 @@
+export const matrixFromRowsDocs = {
+  name: 'matrixFromRows',
+  category: 'Matrix',
+  syntax: [
+    'math.matrixFromRows(...arr)',
+    'math.matrixFromRows(row1, row2)',
+    'math.matrixFromRows(row1, row2, row3)'
+  ],
+  description: 'Create a dense matrix from vectors as individual rows.',
+  examples: [
+    'matrixFromRows([1, 2, 3], [[4],[5],[6]])'
+  ],
+  seealso: [
+    'matrix', 'matrixFromColumns', 'matrixFromFunction', 'zeros'
+  ]
+}

src/expression/embeddedDocs/function/matrix/row.js

@@ -10,5 +10,5 @@ export const rowDocs = {
     'row(A, 1)',
     'row(A, 2)'
   ],
-  seealso: ['column']
+  seealso: ['column', 'matrixFromRows']
 }

src/factoriesAny.js

@@ -24,6 +24,9 @@ export { createBignumber } from './type/bignumber/function/bignumber.js'
 export { createComplex } from './type/complex/function/complex.js'
 export { createFraction } from './type/fraction/function/fraction.js'
 export { createMatrix } from './type/matrix/function/matrix.js'
+export { createMatrixFromFunction } from './function/matrix/matrixFromFunction.js'
+export { createMatrixFromRows } from './function/matrix/matrixFromRows.js'
+export { createMatrixFromColumns } from './function/matrix/matrixFromColumns.js'
 export { createSplitUnit } from './type/unit/function/splitUnit.js'
 export { createUnaryMinus } from './function/arithmetic/unaryMinus.js'
 export { createUnaryPlus } from './function/arithmetic/unaryPlus.js'

src/function/matrix/flatten.js

@@ -8,6 +8,7 @@ const dependencies = ['typed', 'matrix']
 export const createFlatten = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix }) => {
   /**
    * Flatten a multi dimensional matrix into a single dimensional matrix.
+   * It is guaranteed to always return a clone of the argument.
    *
    * Syntax:
    *

src/function/matrix/matrixFromColumns.js

@@ -0,0 +1,86 @@
+import { factory } from '../../utils/factory.js'
+
+const name = 'matrixFromColumns'
+const dependencies = ['typed', 'matrix', 'flatten', 'size']
+
+export const createMatrixFromColumns = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, flatten, size }) => {
+  /**
+   * Create a dense matrix from vectors as individual columns.
+   * If you pass row vectors, they will be transposed (but not conjugated!)
+   *
+   * Syntax:
+   *
+   *    math.matrixFromColumns(...arr)
+   *    math.matrixFromColumns(col1, col2)
+   *    math.matrixFromColumns(col1, col2, col3)
+   *
+   * Examples:
+   *
+   *    math.matrixFromColumns([1, 2, 3], [[4],[5],[6]])
+   *    math.matrixFromColumns(...vectors)
+   *
+   * See also:
+   *
+   *    matrix, matrixFromRows, matrixFromFunction, zeros
+   *
+   * @param {...Array | ...Matrix} cols
+   * @return { number[][] | Matrix } if at least one of the arguments is an array, an array will be returned
+   */
+  return typed(name, {
+    '...Array': function (arr) {
+      return _createArray(arr)
+    },
+    '...Matrix': function (arr) {
+      return matrix(_createArray(arr.map(m => m.toArray())))
+    }
+
+    // TODO implement this properly for SparseMatrix
+  })
+
+  function _createArray (arr) {
+    if (arr.length === 0) throw new TypeError('At least one column is needed to construct a matrix.')
+    const N = checkVectorTypeAndReturnLength(arr[0])
+
+    // create an array with empty rows
+    const result = []
+    for (let i = 0; i < N; i++) {
+      result[i] = []
+    }
+
+    // loop columns
+    for (const col of arr) {
+      const colLength = checkVectorTypeAndReturnLength(col)
+
+      if (colLength !== N) {
+        throw new TypeError('The vectors had different length: ' + (N | 0) + ' ≠ ' + (colLength | 0))
+      }
+
+      const f = flatten(col)
+
+      // push a value to each row
+      for (let i = 0; i < N; i++) {
+        result[i].push(f[i])
+      }
+    }
+
+    return result
+  }
+
+  function checkVectorTypeAndReturnLength (vec) {
+    const s = size(vec)
+
+    if (s.length === 1) { // 1D vector
+      return s[0]
+    } else if (s.length === 2) { // 2D vector
+      if (s[0] === 1) { // row vector
+        return s[1]
+      } else if (s[1] === 1) { // col vector
+        return s[0]
+      } else {
+        throw new TypeError('At least one of the arguments is not a vector.')
+      }
+    } else {
+      throw new TypeError('Only one- or two-dimensional vectors are supported.')
+    }
+  }
+})

src/function/matrix/matrixFromFunction.js

@@ -0,0 +1,63 @@
+import { factory } from '../../utils/factory.js'
+
+const name = 'matrixFromFunction'
+const dependencies = ['typed', 'matrix', 'isZero']
+
+export const createMatrixFromFunction = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, isZero }) => {
+  /**
+   * Create a matrix by evaluating a generating function at each index.
+   *
+   * Syntax:
+   *
+   *    math.matrixFromFunction(size, fn)
+   *    math.matrixFromFunction(size, fn, format)
+   *    math.matrixFromFunction(size, fn, format, datatype)
+   *    math.matrixFromFunction(size, format, fn)
+   *    math.matrixFromFunction(size, format, datatype, fn)
+   *
+   * Examples:
+   *
+   *    math.matrixFromFunction([3,3], i => i[0] - i[1]) // an antisymmetric matrix
+   *    math.matrixFromFunction([100, 100], 'sparse', i => i[0] - i[1] === 1 ? 4 : 0) // a sparse subdiagonal matrix
+   *    math.matrixFromFunction([5], i => math.random()) // a random vector
+   *
+   * See also:
+   *
+   *    matrix, zeros
+   */
+  return typed(name, {
+    'Array | Matrix, function, string, string': function (size, fn, format, datatype) {
+      return _create(size, fn, format, datatype)
+    },
+    'Array | Matrix, function, string': function (size, fn, format) {
+      return _create(size, fn, format)
+    },
+    'Array | Matrix, function': function (size, fn) {
+      return _create(size, fn, 'dense')
+    },
+    'Array | Matrix, string, function': function (size, format, fn) {
+      return _create(size, fn, format)
+    },
+    'Array | Matrix, string, string, function': function (size, format, datatype, fn) {
+      return _create(size, fn, format, datatype)
+    }
+  })
+
+  function _create (size, fn, format, datatype) {
+    let m
+    if (datatype !== undefined) {
+      m = matrix(format, datatype)
+    } else {
+      m = matrix(format)
+    }
+
+    m.resize(size)
+    m.forEach(function (_, index) {
+      const val = fn(index)
+      if (isZero(val)) return
+      m.set(index, val)
+    })
+
+    return m
+  }
+})

src/function/matrix/matrixFromRows.js

@@ -0,0 +1,75 @@
+import { factory } from '../../utils/factory.js'
+
+const name = 'matrixFromRows'
+const dependencies = ['typed', 'matrix', 'flatten', 'size']
+
+export const createMatrixFromRows = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, flatten, size }) => {
+  /**
+   * Create a dense matrix from vectors as individual rows.
+   * If you pass column vectors, they will be transposed (but not conjugated!)
+   *
+   * Syntax:
+   *
+   *    math.matrixFromRows(...arr)
+   *    math.matrixFromRows(row1, row2)
+   *    math.matrixFromRows(row1, row2, row3)
+   *
+   * Examples:
+   *
+   *    math.matrixFromRows([1, 2, 3], [[4],[5],[6]])
+   *    math.matrixFromRows(...vectors)
+   *
+   * See also:
+   *
+   *    matrix, matrixFromColumns, matrixFromFunction, zeros
+   *
+   * @param {...Array | ...Matrix} rows
+   * @return { number[][] | Matrix } if at least one of the arguments is an array, an array will be returned
+   */
+  return typed(name, {
+    '...Array': function (arr) {
+      return _createArray(arr)
+    },
+    '...Matrix': function (arr) {
+      return matrix(_createArray(arr.map(m => m.toArray())))
+    }
+
+    // TODO implement this properly for SparseMatrix
+  })
+
+  function _createArray (arr) {
+    if (arr.length === 0) throw new TypeError('At least one row is needed to construct a matrix.')
+    const N = checkVectorTypeAndReturnLength(arr[0])
+
+    const result = []
+    for (const row of arr) {
+      const rowLength = checkVectorTypeAndReturnLength(row)
+
+      if (rowLength !== N) {
+        throw new TypeError('The vectors had different length: ' + (N | 0) + ' ≠ ' + (rowLength | 0))
+      }
+
+      result.push(flatten(row))
+    }
+
+    return result
+  }
+
+  function checkVectorTypeAndReturnLength (vec) {
+    const s = size(vec)
+
+    if (s.length === 1) { // 1D vector
+      return s[0]
+    } else if (s.length === 2) { // 2D vector
+      if (s[0] === 1) { // row vector
+        return s[1]
+      } else if (s[1] === 1) { // col vector
+        return s[0]
+      } else {
+        throw new TypeError('At least one of the arguments is not a vector.')
+      }
+    } else {
+      throw new TypeError('Only one- or two-dimensional vectors are supported.')
+    }
+  }
+})