math-float64-epsilon-difference v1.0.0

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][relative-difference] is `+infinity`.
  
  	``` javascript
  	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

License

MIT license.

Copyright

Copyright © 2016. The Compute.io Authors.