josdejong · dvd101x · Dec 9, 2025 · Dec 9, 2025 · Dec 9, 2025 · Dec 9, 2025
diff --git a/HISTORY.md b/HISTORY.md
@@ -1687,7 +1687,7 @@ Breaking changes:
 - Dropped support for (non-primitive) instances of `Number`, `Boolean`, and
   `String` from functions `clone` and `typeof`.
 - Dropped official support for IE9 (probably still works, but it's not tested).
-- Fixed #851: More consistent behavior of sqrt, nthRoot, and pow.
+- Fixed #851: More consistent behavior of `sqrt`, `nthRoot`, and `pow`.
   Thanks @dakotablair.
 - Fixed #1103: Calling `toTex` on node that contains `derivative` causing
   an exception. Thanks @joelhoover.
@@ -2520,7 +2520,7 @@ Non breaking changes:
 
 ## 2015-07-12, version 1.7.1
 
-- Fixed #397: Inaccuracies in nthRoot for very large values, and wrong results
+- Fixed #397: Inaccuracies in `nthRoot` for very large values, and wrong results
   for very small values. (backported from v2)
 - Fixed #405: Parser throws error when defining a function in a multiline
   expression.
@@ -3061,7 +3061,7 @@ Non breaking changes:
 
 - Extended the import function and some other minor improvements.
 - Fixed a bug in merging one dimensional vectors into a matrix.
-- Fixed a bug in function subtract, when subtracting a complex number from a
+- Fixed a bug in function `subtract`, when subtracting a complex number from a
   real number.
 
 ## 2013-05-10, version 0.8.1

diff --git a/docs/datatypes/matrices.md b/docs/datatypes/matrices.md
@@ -12,10 +12,13 @@ dense and sparse matrices.
 Math.js supports two types of matrices:
 
 - `Array`, a regular JavaScript array. A multidimensional array can be created
-  by nesting arrays.
+  by nesting arrays. The following terminology will be used to define different kinds of nested arrays.
+  - **Recangular array**: All elements of an array are arrays of the same size. Like `[[1, 2], [3, 4]]`
+  - **Jagged arrays**: All elements of an array are arrays but not of the same size. Like `[[1, 2], [3, 4, 5]]`
+  - **Heterogeneous arrays**: If not all the elements inside an array are arrays. Like `[[1, 2], 3]`.
 - `Matrix`, a matrix implementation by math.js. A `Matrix` is an object wrapped
   around a regular JavaScript `Array`, providing utility functions for easy
-  matrix manipulation such as `subset`, `size`, `resize`, `clone`, and more.
+  matrix manipulation such as `subset`, `size`, `resize`, `clone`, and more. Nested arrays must be rectangular to be converted to a `Matrix`.
 
 In most cases, the type of matrix output from functions is determined by the
 function input: An `Array` as input will return an `Array`, a `Matrix` as input
@@ -224,6 +227,27 @@ If you have a matrix where the first dimension means `x` and the second
 means `y`, this will look confusing since `x` is printed as _column_ 
 (vertically) and `y` as _row_ (horizontally).
 
+## Non-rectangular arrays
+
+By nesting arrays it is possible to have arrays that are not rectangular, for example.
+```js
+[[1, 2], [3, 4]]    // rectangular of size [2, 2]
+[[1, 2], [3, 4, 5]] // jagged
+[[1, 2], 3]         // heterogeneous
+```
+
+Jagged and heterogeneous arrays can't be converted to a matrix, but many operations are available for them.
+```js
+const A = [[1, 2], 3]
+math.add(A, 1)
+math.map(A, a => a+1)
+math.forEach(A, a => console.log(a))
+```
+Some matrix functions expect a rectangular array and might provide unexpected results with non rectangular arrays, for example.
+```js
+math.size([[1, 2], [3]]) // [2, 2]
+```
+The process of validation for rectangularity is expensive and is mandatory to create a `Matrix`, thus there might be a performance benefit of not converting an `Array` to a `Matrix`.
 
 ## Resizing
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/src/expression/parse.js b/src/expression/parse.js
@@ -82,20 +82,20 @@ export const createParse = /* #__PURE__ */ factory(name, dependencies, ({
    *
    * History:
    *
-   *     v0.9   Created
-   *     v0.13  Switched to one-based indices
-   *     v0.14  Added `[1,2;3,4]` notation for matrices
-   *     v0.18  Dropped the `function` keyword
-   *     v0.20  Added ternary conditional
-   *     v0.27  Allow multi-line expressions; allow functions that receive
-   *            unevaluated parameters (`rawArgs`)
+   *     v15.1  Add optional chaining operator
+   *     v14.8  Add nullish coalescing operator
+   *     v12.4  Allow trailing commas in matrices
+   *     v9.5   Support for calculations with percentages
+   *     v7.3   Supported binary, octal, and hexadecimal notation
    *     v3     Add object notation; allow assignments internal to other
    *            expressions
-   *     v7.3   Supported binary, octal, and hexadecimal notation
-   *     v9.5   Support for calculations with percentages
-   *     v12.4  Allow trailing commas in matrices
-   *     v14.8  Add nullish coalescing operator
-   *     v15.1  Add optional chaining operator
+   *     v0.27  Allow multi-line expressions; allow functions that receive
+   *            unevaluated parameters (`rawArgs`)
+   *     v0.20  Added ternary conditional
+   *     v0.18  Dropped the `function` keyword
+   *     v0.14  Added `[1,2;3,4]` notation for matrices
+   *     v0.13  Switched to one-based indices
+   *     v0.9   Created
    *
    * @param {string | string[] | Matrix} expr          Expression to be parsed
    * @param {{nodes: Object<string, Node>}} [options]  Available options:

diff --git a/src/function/arithmetic/add.js b/src/function/arithmetic/add.js
@@ -10,19 +10,17 @@ const dependencies = [
   'matrix',
   'addScalar',
   'equalScalar',
-  'DenseMatrix',
-  'SparseMatrix',
-  'concat'
+  'DenseMatrix'
 ]
 
 export const createAdd = /* #__PURE__ */ factory(
   name,
   dependencies,
-  ({ typed, matrix, addScalar, equalScalar, DenseMatrix, SparseMatrix, concat }) => {
+  ({ typed, matrix, addScalar, equalScalar, DenseMatrix }) => {
     const matAlgo01xDSid = createMatAlgo01xDSid({ typed })
     const matAlgo04xSidSid = createMatAlgo04xSidSid({ typed, equalScalar })
     const matAlgo10xSids = createMatAlgo10xSids({ typed, DenseMatrix })
-    const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })
+    const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix })
     /**
      * Add two or more values, `x + y`.
      * For matrices, the function is evaluated element wise.
@@ -55,10 +53,9 @@ export const createAdd = /* #__PURE__ */ factory(
      *
      * History:
      *
-     *     v13     Handle bigint arguments
      *     v11.6   Support matrix broadcasting
+     *     v5.0.3  Support matrices with a `datatype` defined
      *     v3.8    Allow more than two arguments
-     *     v0.0.2  Created
      *
      * @param  {number | BigNumber | bigint | Fraction | Complex | Unit | Array | Matrix} x First value to add
      * @param  {number | BigNumber | bigint | Fraction | Complex | Unit | Array | Matrix} y Second value to add

diff --git a/src/function/arithmetic/dotDivide.js b/src/function/arithmetic/dotDivide.js
@@ -13,17 +13,16 @@ const dependencies = [
   'equalScalar',
   'divideScalar',
   'DenseMatrix',
-  'concat',
   'SparseMatrix'
 ]
 
-export const createDotDivide = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, equalScalar, divideScalar, DenseMatrix, concat, SparseMatrix }) => {
+export const createDotDivide = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, equalScalar, divideScalar, DenseMatrix, SparseMatrix }) => {
   const matAlgo02xDS0 = createMatAlgo02xDS0({ typed, equalScalar })
   const matAlgo03xDSf = createMatAlgo03xDSf({ typed })
   const matAlgo07xSSf = createMatAlgo07xSSf({ typed, SparseMatrix })
   const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
   const matAlgo12xSfs = createMatAlgo12xSfs({ typed, DenseMatrix })
-  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })
+  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix })
 
   /**
    * Divide two matrices element wise. The function accepts both matrices and
@@ -47,6 +46,12 @@ export const createDotDivide = /* #__PURE__ */ factory(name, dependencies, ({ ty
    *
    *    divide, multiply, dotMultiply
    *
+   * History:
+   *
+   *    v14.0.0  Return a sparse matrix for sparse inputs
+   *    v11.6    Support matrix broadcasting
+   *    v0.23    Renamed from `edivide`
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x Numerator
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} y Denominator
    * @return {number | BigNumber | Fraction | Complex | Unit | Array | Matrix}                    Quotient, `x ./ y`

diff --git a/src/function/arithmetic/dotMultiply.js b/src/function/arithmetic/dotMultiply.js
@@ -9,15 +9,14 @@ const dependencies = [
   'typed',
   'matrix',
   'equalScalar',
-  'multiplyScalar',
-  'concat'
+  'multiplyScalar'
 ]
 
-export const createDotMultiply = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, equalScalar, multiplyScalar, concat }) => {
+export const createDotMultiply = /* #__PURE__ */ factory(name, dependencies, ({ typed, matrix, equalScalar, multiplyScalar }) => {
   const matAlgo02xDS0 = createMatAlgo02xDS0({ typed, equalScalar })
   const matAlgo09xS0Sf = createMatAlgo09xS0Sf({ typed, equalScalar })
   const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
-  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })
+  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix })
 
   /**
    * Multiply two matrices element wise. The function accepts both matrices and
@@ -41,6 +40,11 @@ export const createDotMultiply = /* #__PURE__ */ factory(name, dependencies, ({
    *
    *    multiply, divide, dotDivide
    *
+   * History:
+   *
+   *    v11.6   Support matrix broadcasting
+   *    v0.23   Renamed from `emultiply`
+   *
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} x Left hand value
    * @param  {number | BigNumber | Fraction | Complex | Unit | Array | Matrix} y Right hand value
    * @return {number | BigNumber | Fraction | Complex | Unit | Array | Matrix}                    Multiplication of `x` and `y`

diff --git a/src/function/arithmetic/dotPow.js b/src/function/arithmetic/dotPow.js
@@ -12,16 +12,15 @@ const dependencies = [
   'matrix',
   'pow',
   'DenseMatrix',
-  'concat',
   'SparseMatrix'
 ]
 
-export const createDotPow = /* #__PURE__ */ factory(name, dependencies, ({ typed, equalScalar, matrix, pow, DenseMatrix, concat, SparseMatrix }) => {
+export const createDotPow = /* #__PURE__ */ factory(name, dependencies, ({ typed, equalScalar, matrix, pow, DenseMatrix, SparseMatrix }) => {
   const matAlgo03xDSf = createMatAlgo03xDSf({ typed })
   const matAlgo07xSSf = createMatAlgo07xSSf({ typed, SparseMatrix })
   const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
   const matAlgo12xSfs = createMatAlgo12xSfs({ typed, DenseMatrix })
-  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })
+  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix })
 
   const powScalarSignatures = {}
   for (const signature in pow.signatures) {
@@ -52,6 +51,12 @@ export const createDotPow = /* #__PURE__ */ factory(name, dependencies, ({ typed
    *
    *    pow, sqrt, multiply
    *
+   * History:
+   *
+   *    v14.0.0  Return a sparse matrix for sparse inputs
+   *    v11.6    Support matrix broadcasting
+   *    v0.23    Renamed from `epow`
+   *
    * @param  {number | BigNumber | Complex | Unit | Array | Matrix} x  The base
    * @param  {number | BigNumber | Complex | Unit | Array | Matrix} y  The exponent
    * @return {number | BigNumber | Complex | Unit | Array | Matrix}                     The value of `x` to the power `y`

diff --git a/src/function/arithmetic/gcd.js b/src/function/arithmetic/gcd.js
@@ -32,7 +32,7 @@ export const createGcd = /* #__PURE__ */ factory(name, dependencies, ({ typed, m
   const matAlgo01xDSid = createMatAlgo01xDSid({ typed })
   const matAlgo04xSidSid = createMatAlgo04xSidSid({ typed, equalScalar })
   const matAlgo10xSids = createMatAlgo10xSids({ typed, DenseMatrix })
-  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })
+  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix })
 
   /**
    * Calculate the greatest common divisor for two or more values or arrays.
@@ -56,6 +56,13 @@ export const createGcd = /* #__PURE__ */ factory(name, dependencies, ({ typed, m
    *
    *    lcm, xgcd
    *
+   * History:
+   *
+   *    v11.7  Accept arrays as input
+   *    v11.6  Support matrix broadcasting
+   *    v0.26  Implement BigNumber support
+   *    v0.6   Created
+   *
    * @param {... number | BigNumber | Fraction | Array | Matrix} args  Two or more integer numbers
    * @return {number | BigNumber | Fraction | Array | Matrix}                           The greatest common divisor
    */