operations between jagged arrays and scalars #3607

dvd101x · 2025-12-09T03:36:11Z

Hi, this is the proof of concept discussed at #3537

It's more inline with what Jos and Glen suggested as my initial idea was flawed. This PR only shows two main changes.

refactors matAlgo14xDs to use it's DenseMatrix map method and includes a hack to make the matrix creation faster.
makes a new matAlgo15xAs to map arrays that can be jagged or non homogeneous and there is no need to convert to matrix and then back to array.

My expectation is that all operations between Matrix|Array and scalar should be faster.

The new functionality is that it's possible to do stuff like

math.add([1,[2,3]], 1)

math.config({matrix:"Array"})
math.evaluate("[1,[2,3]] + 1")

josdejong · 2025-12-10T15:23:18Z

Nice! This actually simplifies the code since you can "just" use the map function.

What are the next steps? Add some unit tests for jagged inputs, update docs, and see what the performance impact is?

dvd101x · 2025-12-11T15:26:28Z

Yes exactly, I will proceed with the next steps in the following weeks.

Maybe later I will come back to broadcasting jagged arrays.

src/type/matrix/utils/matAlgo14xDs.js

gwhitney

Excellent, this is shaping up. A few more things to consider.

gwhitney · 2025-12-16T07:13:52Z

src/function/bitwise/leftShift.js

  const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
  const matAlgo14xDs = createMatAlgo14xDs({ typed })
+  const matAlgo15xAs = createMatAlgo15xAs()
  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })


This concat is not actually a dependency of matrixAlgorithmSuite. Since you are here, please remove it. Most likely that will allow concat to be removed as a dependency altogether.

Thanks! just addressed this.

gwhitney · 2025-12-16T07:15:21Z

docs/datatypes/matrices.md

 - `Array`, a regular JavaScript array. A multidimensional array can be created
-  by nesting arrays.
+  by nesting arrays. If the elements of an array are of the same size, it is a
+  rectangular array. If the elements are all arrays but not of the same size, 


You should say that these words "rectangular", "jagged", "heterogeneous" are the terminology mathjs will use -- it's not like these are universally standard terms.

Thanks, included a brief explanation of the terminology that would be used. I'm not familiar weather or not these are known, but took references of wikipedia to define the names.

gwhitney · 2025-12-16T07:15:46Z

docs/datatypes/matrices.md

 (vertically) and `y` as _row_ (horizontally).

+## Not rectangular arrays
+


Should that be "Non-rectangular arrays" ?

Thanks! just addressed this.

gwhitney · 2025-12-16T07:17:04Z

docs/datatypes/matrices.md

+[[1, 2], 3]      // heterogeneous
+```
+
+These types of arrays can't be converted to a matrix, but many operations are available for them.


Say "Jagged and heterogeneous arrays" instead of "These types of arrays" because one of the examples you just showed was rectangular and can be converted to a matrix.

Thanks for the thorough read. Just addressed this issue.

gwhitney · 2025-12-16T07:18:07Z

docs/datatypes/matrices.md

+```js
+math.size([[1, 2], [3]]) // [2, 2]
+```
+The process of validation for rectangularity is expensive and this provides a fast way of working with nested arrays of many kinds.


The antecedent of "this" in "this provides" is unclear. Please clarify exactly what provides a fast way of working with nested arrays.

Thanks! just addressed this issue.

gwhitney · 2025-12-16T07:20:58Z

src/function/bitwise/rightArithShift.js

  const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
  const matAlgo14xDs = createMatAlgo14xDs({ typed })
+  const matAlgo15xAs = createMatAlgo15xAs()
  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })


Same concat removal here.

Thanks! just addressed this issue.

gwhitney · 2025-12-16T07:21:28Z

src/function/bitwise/rightLogShift.js

  const matAlgo11xS0s = createMatAlgo11xS0s({ typed, equalScalar })
  const matAlgo14xDs = createMatAlgo14xDs({ typed })
+  const matAlgo15xAs = createMatAlgo15xAs()
  const matrixAlgorithmSuite = createMatrixAlgorithmSuite({ typed, matrix, concat })


And remove concat here too.

Thanks! just addressed this issue. Please review

gwhitney · 2025-12-16T07:31:31Z

src/type/matrix/utils/matAlgo14xDs.js

      // callback
-      cf = typed.find(callback, [dt, dt])
+      cf = typed.find(callback, [adt, adt])
    }


I realize that you didn't create this algorithm for dealing with the case when the matrix is of a known datatype, but it doesn't seem correct. For example, consider the case of a number matrix and adding a bignumber. Normally a number plus a bignumber is a bignumber. Since addition distributes over the entries of a matrix, I would expect a matrix of numbers, plus a bignumber, to produce a matrix of bignumbers. But by the above logic, instead the bignumber will be converted to a number (possibly losing precision, and since this is an explicit call to convert, there will be no warning), and you will end up with a matrix of numbers. That seems buggy, especially the potential un-warned loss of precision. If you agree, I would personally be fine folding in a fix to this concern (as long as it is not breaking) into this PR. However @josdejong may disagree, and want addressing this potential issue to be in a separate PR. If so, or if it is breaking, please file an issue for the type-handling of matrix-scalar operations, noting whether it is breaking. Thanks!

For this I tried to maintain behavior as is. Maybe this could be addressed in a different PR.

Currently add a Matrix of numbers to a big number throws an error but tries to convert the bigNumber to number.

math.add(math.matrix([1], "dense", "number"), math.bignumber(1)) // Uncaught Error: Cannot convert 1 to number

I agree it's not right and the same goes for map where it assumes that if the input is of a certain type the output will be as well.

math.matrix([1], "dense", "number").map(x => math.add(x, math.bignumber(1))) // returns a matrix of datatype "number" that contains bignumbers.

I don't see an easy fix about the types for when a map accepts a callback, other than checking the output.

But for operators maybe there is a way specific to each operator and datatype or a database of two type inputs equals a type output.

I might be wrong, I will validate again if I'm changing the behavior.

OK, well in the meantime I have filed #3612; you can address it or not in this PR as you and Jos see fit, but we should definitely fix it at some point in the not-too-distant future since it is definitely a bug.

Thanks for bringing this issue up Glen, we should indeed fix this behavior. But best to do that in a separate PR I think.

Hi, I did validate and I think the original behavior is maintained, please let me know if I'm mistaken.

gwhitney · 2025-12-16T07:33:12Z

src/type/matrix/utils/matAlgo15xAs.js

+export const createMatAlgo15xAs = /* #__PURE__ */ factory(name, dependencies, () => {
+  /**
+   * Iterates over Array items and invokes the callback function f(Aij..z, b).
+   * Callback function invoked MxN times.


Since in this case the Array may quite explicitly not be rectangular, saying "MxN" is a bit misleading. Consider changing to something like "Callback function invoked once for each entry of A."

Thanks! just addressed this issue. Please review

src/type/matrix/utils/matAlgo15xAs.js

dvd101x · 2025-12-17T03:33:43Z

After including benchmarks, there is a big benefit of not converting arrays to matrices and small benefit of using the DenseMatrix.map method.

dvd101x · 2025-12-20T02:54:55Z

Hi, all comments are addressed either in code or as a reply. This is ready for review again.

dvd101x added 4 commits December 8, 2025 20:54

Refactor matAlgo14xDs

0f834fb

Included an algorithm for Array and scalars

c9d57a1

fixed name of the exporter function

d273182

Merge branch 'develop' into jagged-arrays

fb35b55

gwhitney reviewed Dec 11, 2025

View reviewed changes

src/type/matrix/utils/matAlgo14xDs.js Outdated Show resolved Hide resolved

dvd101x added 4 commits December 11, 2025 23:09

Fixed missing variable

af646a8

Added tests and removed useMatrixForArrayScalar.js

57c4cb2

added more tests

8e58d2b

Added documentation

cdceb79

gwhitney requested changes Dec 16, 2025

View reviewed changes

Added benchmarks

d67b73d

dvd101x added 5 commits December 16, 2025 21:35

Fixed comment to allow for non-rectangular arrays

a720b66

Define terminology used for nested arrays.

4a215ed

Documentation fixes for non-rectangular arrays

4bdb5ca

Removed concat and other dependancies from factory functions

8c6c47d

Merge branch 'develop' into jagged-arrays

47fc7aa

		(vertically) and `y` as _row_ (horizontally).

		## Not rectangular arrays

Uh oh!

operations between jagged arrays and scalars #3607

Are you sure you want to change the base?

operations between jagged arrays and scalars #3607

Conversation

dvd101x commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josdejong commented Dec 10, 2025

Uh oh!

dvd101x commented Dec 11, 2025

Uh oh!

Uh oh!

gwhitney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josdejong Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dvd101x commented Dec 17, 2025

Uh oh!

dvd101x commented Dec 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dvd101x commented Dec 9, 2025 •

edited

Loading

josdejong Dec 17, 2025 •

edited

Loading