Terms "numeric" and "scalar" in mathjs code and documentation

[gwhitney]

There doesn't seem to be any specific definition anywhere in mathjs code/documentation of what entities are considered "numeric" and/or "scalar". There seem to be some inconsistencies within the code or with the usual mathematical meaning of them. The main examples:

• The functions hasNumericValue and isNumeric agree that boolean values are numeric and Complex values are not. Yet in common mathematical terminology, the latter are called the "complex numbers", so certainly a mathematician would think of them as numeric. And boolean values are more ambiguous: in mathjs, they very freely convert to 1 and 0, to the point that they are practically aliases, and numeric returns true for them, but it's less clear that in typical math terminology "true" would be considered numeric. And indeed, in the TypeScript index.d.ts, MathNumericType is defined to include Complex and not include boolean, which seems internally inconsistent with isNumeric and hasNumericValue, especially since in TypeScript those are all visible identifiers. It could be surprising that isNumeric could ever return false on an argument of MathNumericType. Moreover, isNumeric(5) returns true and isNumeric(complex(5, 0)) returns false, even though equal(5, complex(5, 0)) returns true, which seems contradictory: how can two things be equal, yet one is numeric and the other is not?

• Pretty consistently in mathjs code, "scalar" seems to mean "number | BigNumber | Complex | Fraction | bigint | Unit" and often also boolean (which does automatically convert to number). This meaning seems to match mathematical usage pretty well. However, since the TypeScript definition of MathScalarType is MathNumericType | Unit, these things mean that TypeScript currently thinks that math.add(true, false) is a type error, even though it executes perfectly well, returning 1.

Possible action items here:

1. Although I personally don't think of "true" and "false" as numeric, they are pretty consistently treated as numeric in mathjs, so leave the return type of isNumeric on booleans alone, and add boolean to MathNumericType in index.d.ts. This change would definitely improve the correctness of the TypeScript type definitions, and is not a breaking change.

2. To avoid confusion, make isNumeric and MathNumericType consistent. This change would involve deciding once and for all whether Complex values are numeric. Based on the 5 vs. complex(5, 0) example, I would strongly vote that they are numeric. That option would of course necessitate a breaking change. If there is a need for something that is true on number, bigint, bignumber, (boolean?) and fraction, one could consider adding isReal, although that should also return true for Complex values with (essentially) 0 imaginary part. On the other hand, if in the end the decision is made to stick with Complex not being numeric, then Complex should be removed from MathNumericType (and added to MathScalarType, since there does seem to be consensus Complex values are scalars).

3. Add to some appropriate place in the documentation careful definitions of "numeric" and "scalar" within mathjs, and make sure other documentation and code consistently agree with these definitions.

Looking forward to your thoughts on these points and whether any of these actions (or others you might think of) are worth making in the near term.

[josdejong]

Hm yeah interesting.

With numeric so far we mean: number | BigNumber | bigint | Fraction | boolean (see code). The idea behind it is whether the "thing" can be represented as a single numeric value. A complex number consists of two numeric values, not one. A matrix contains m x n numeric values. A string can possibly be a numeric value depending on whether the string contains a numeric value or some text, that's what hasNumericValue can check.

The idea behind "scalar" is that it is a single "item" from an array/matrix that holds multiple items. That can be anything except a Matrix or Array.

I had a look at the type definitions, and it looks like isNumeric corresponds to the actual implementation but hasNumericValue not, that cannot return a boolean[] but always returns boolean. The type of MathNumericType should indeed correspond with the list of types from isNumeric (your point 2). So, good point to ensure the type definitions are on par with the actual implementations!

[gwhitney]

A complex number consists of two numeric values, not one.

That is entirely a matter of perspective. From my point of view, a complex number is a single number, a member of the algebraic closure of the reals. That field just happens to have dimension 2 over the reals, but that's really just a coincidence. The question really becomes, what is the meaning/purpose/use case for isNumeric and hasNumericValue?

[gwhitney]

Oops, I more or less already filed this as issue #3380 a while back; at least I am consistent ;) Should we merge the two? As an issue or a discussion?