feat: nearly equal with relative and absolute tolerance (#3152)

* nearlyEqual with absolute and relative tolerances

* Format

* nearlyEqual for bigNumber

* Added skip for NaN

* Reduce diff a bit

* Issue with examples in jsdcos

* Updated all calls for nearlyEqual

* Fixed failing tests

* Changed epsilon to relTol, absTol

* Changed references to epsilon in docs and tests

* Added warning for config.epsilon

* Fix warning in zeta.test

* Added config test

* Added sinon to test console.warn

---------

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

docs/core/configuration.md

@@ -8,7 +8,8 @@ import { create, all } from 'mathjs'
 
 // create a mathjs instance with configuration
 const config = {
-  epsilon: 1e-12,
+  relTol: 1e-12,
+  absTol: 1e-15,
   matrix: 'Matrix',
   number: 'number',
   precision: 64,
@@ -28,10 +29,14 @@ math.config({
 
 The following configuration options are available:
 
-- `epsilon`. The minimum relative difference used to test equality between two
+- `relTol`. The minimum relative difference used to test equality between two
   compared values. This value is used by all relational functions.
   Default value is `1e-12`.
 
+- `absTol`. The minimum absolute difference used to test equality between two
+  compared values. This value is used by all relational functions.
+  Default value is `1e-15`.
+
 - `matrix`. The default type of matrix output for functions.
   Available values are: `'Matrix'` (default) or `'Array'`.
   Where possible, the type of matrix output from functions is determined from

docs/datatypes/bignumbers.md

@@ -24,7 +24,8 @@ math.config({
   number: 'BigNumber',      // Default type of number:
                             // 'number' (default), 'BigNumber', or 'Fraction'
   precision: 64,            // Number of significant digits for BigNumbers
-  epsilon: 1e-60
+  relTol: 1e-60,
+  absTol: 1e-63
 })
 
 // use math
@@ -34,12 +35,12 @@ math.evaluate('0.1 + 0.2')  // BigNumber, 0.3
 The default precision for BigNumber is 64 digits, and can be configured with
 the option `precision`. 
 
-Note that we also change the configuration of `epsilon` 
-to be close to the precision limit of our BigNumbers. `epsilon` is used for 
+Note that we also change the configuration of `relTol` and `absTol` 
+to be close to the precision limit of our BigNumbers. `relTol` and `absTol` are used for 
 example in relational and rounding functions (`equal`, `larger`, `smaller`, 
 `round`, `floor`, etc) to determine when a value is nearly equal, 
-see [Equality](numbers.md#equality). If we would leave `epsilon` unchanged, 
-having the default value of `1e-12`, we could get inaccurate and misleading 
+see [Equality](numbers.md#equality). If we would leave `relTol` and `absTol`  unchanged, 
+having the default value of `1e-12` and `1e-15` respectively, we could get inaccurate and misleading 
 results since we're now working with a higher precision.
 
 

docs/datatypes/numbers.md

@@ -73,16 +73,14 @@ false, as the addition `0.1 + 0.2` introduces a round-off error and does not
 return exactly `0.3`.
 
 To solve this problem, the relational functions of math.js check whether the
-relative difference between the compared values is smaller than the configured
-option `epsilon`. In pseudo code (without exceptions for 0, Infinity and NaN):
+relative and absolute differences between the compared values is smaller than the configured
+option `relTol` and `absTol`. In pseudo code (without exceptions for 0, Infinity and NaN):
 
-    diff = abs(x - y)
-    nearlyEqual = (diff <= max(abs(x), abs(y)) * EPSILON) OR (diff < DBL_EPSILON)
+    abs(a-b) <= max(relTol * max(abs(a), abs(b)), absTol)
 
 where:
 
- - `EPSILON` is the relative difference between x and y. Epsilon is configurable
-   and is `1e-12` by default. See [Configuration](../core/configuration.md).
+ - `relTol` is the relative tolerance between x and y and `absTol` the absolute tolerance. Relative tolerance and absolute tolerance are configurable and are `1e-12` and `1e-15` respectively by default. See [Configuration](../core/configuration.md).
  - `DBL_EPSILON` is the minimum positive floating point number such that
    `1.0 + DBL_EPSILON !== 1.0`. This is a constant with a value of approximately
    `2.2204460492503130808472633361816e-16`.