time-to-botec/squiggle/node_modules/@stdlib/math/base/utils/float64-epsilon-difference/README.md
NunoSempere b6addc7f05 feat: add the node modules
Necessary in order to clearly see the squiggle hotwiring.
2022-12-03 12:44:49 +00:00

5.4 KiB

Epsilon Difference

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

Usage

var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' );

epsdiff( x, y[, scale] )

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

var d = epsdiff( 12.15, 12.149999999999999 ); // => ~0.658ε
// 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 = epsdiff( 2.4341309458983933, 2.4341309458633909, 'mean-abs' ); // => ~64761.5ε => ~1.438e-11
// returns ~64761.5

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 = epsdiff( 1.0000000000000002, 1.0000000000000100, scale ); // => ~44ε
// 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 = epsdiff( 1.0e304, 1.0, 'min' ); // => ~1.798e308ε => 1.0e304/ε overflows
    // returns ~1.798e308
    
  • If the absolute difference of x and y is 0, the relative difference is always 0.

    var d = epsdiff( 0.0, 0.0 );
    // returns 0.0
    
    d = epsdiff( 3.14, 3.14 );
    // returns 0.0
    
  • If x = y = +infinity or x = y = -infinity, the function returns NaN.

    var PINF = require( '@stdlib/constants/float64/pinf' );
    var NINF = require( '@stdlib/constants/float64/ninf' );
    
    var d = epsdiff( PINF, PINF );
    // returns NaN
    
    d = epsdiff( NINF, NINF );
    // returns NaN
    
  • If x = -y = +infinity or -x = y = +infinity, the relative difference is +infinity.

    var PINF = require( '@stdlib/constants/float64/pinf' );
    var NINF = require( '@stdlib/constants/float64/ninf' );
    
    var d = epsdiff( PINF, NINF );
    // returns Infinity
    
    d = epsdiff( NINF, PINF );
    // returns Infinity
    
  • If a scale function returns 0, the function returns NaN.

    var d = epsdiff( -1.0, 1.0, 'mean' ); // => |2/0|
    // returns NaN
    

Examples

var randu = require( '@stdlib/random/base/randu' );
var EPS = require( '@stdlib/constants/float64/eps' );
var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' );

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

for ( i = 0; i < 100; i++ ) {
    x = randu();
    sign = ( randu() > 0.5 ) ? 1.0 : -1.0;
    y = x + ( sign*EPS*i );
    d = epsdiff( x, y );
    console.log( 'x = %d. y = %d. d = %dε.', x, y, d );
}