# math-float64-epsilon-difference

Computes the relative difference of two real numbers in units of double-precision floating-point epsilon.

## Usage no npm install needed!

``````<script type="module">
import mathFloat64EpsilonDifference from 'https://cdn.skypack.dev/math-float64-epsilon-difference';
</script>``````

# Relative Difference

Computes the relative difference of two real numbers in units of double-precision floating-point epsilon.

## Installation

``````\$ npm install math-float64-epsilon-difference
``````

## Usage

``````var diff = require( 'math-float64-epsilon-difference' );
``````

#### diff( x, y[, scale] )

Computes the relative difference of two real numbers in units of double-precision floating-point epsilon.

``````var d = diff( 12.15, 12.149999999999999 );
// returns ~0.658ε
``````

The following `scale` functions are supported:

• max-abs: maximum absolute value of `x` and `y` (default).
• max: maximum value of `x` and `y`.
• min-abs: minimum absolute value of `x` and `y`.
• min: minimum value of `x` and `y`.
• mean-abs: arithmetic mean of the absolute values of `x` and `y`.
• mean: arithmetic mean of `x` and `y`.
• x: `x` (noncommutative).
• y: `y` (noncommutative).

By default, the `function` scales the absolute difference by dividing the absolute difference by the maximum absolute value of `x` and `y`. To scale by a different `function`, specify a scale function name.

``````var d = diff( 2.4341309458983933, 2.4341309458633909, 'mean-abs' );
// returns ~64761.5ε => ~1.438e-11
``````

To use a custom scale `function`, provide a `function` which accepts two numeric arguments `x` and `y`.

``````function scale( x, y ) {
// Return the minimum value:
return ( x > y ) ? y : x;
}

var d = diff( 1.0000000000000002, 1.0000000000000100, scale );
// returns ~44ε
``````

## Notes

• If computing the relative difference in units of epsilon will result in overflow, the function returns the maximum double-precision floating-point number.

``````var d = diff( 1e304, 1, 'min' );
// returns ~1.798e308ε => 1e304/ε overflows
``````
• If the absolute difference of `x` and `y` is `0`, the relative difference is always `0`.

``````var d = diff( 0, 0 );
// returns 0ε

d = diff( 3.14, 3.14 );
// returns 0ε
``````
• If `|x| = |y| = infinity`, the function returns `NaN`.

``````var PINF = Number.POSITIVE_INFINITY;
var NINF = Number.NEGATIVE_INFINITY;

var d = diff( PINF, PINF );
// returns NaN

d = diff( NINF, NINF );
// returns NaN
``````
• If `|x| = |-y| = infinity`, the relative difference is `+infinity`.

``````var PINF = Number.POSITIVE_INFINITY;
var NINF = Number.NEGATIVE_INFINITY;

var d = diff( PINF, NINF );
// returns +infinity

d = diff( NINF, PINF );
// returns +infinity
``````
• If a `scale` function returns `0`, the function returns `NaN`.

``````var d = diff( -1, 1, 'mean' );
// returns NaN => |2/0|
``````

## Examples

``````var EPS = require( 'const-eps-float64' );
var diff = require( 'math-float64-epsilon-difference' );

var sign;
var x;
var y;
var d;
var i;

for ( i = 0; i < 100; i++ ) {
x = Math.random();
sign = ( Math.random() > 0.5 ) ? 1 : -1;
y = x + sign*EPS*i;
d = diff( x, y );
console.log( 'x = %d. y = %d. d = %dε.', x, y, d );
}
``````

To run the example code from the top-level application directory,

``````\$ node ./examples/index.js
``````

## Tests

### Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

``````\$ make test
``````

All new feature development should have corresponding unit tests to validate correct functionality.

### Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

``````\$ make test-cov
``````

Istanbul creates a `./reports/coverage` directory. To access an HTML version of the report,

``````\$ make view-cov
``````

### Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

``````\$ make test-browsers
``````

To view the tests in a local web browser,

``````\$ make view-browser-tests
``````