179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
|
<!--
|
||
|
|
||
|
@license Apache-2.0
|
||
|
|
||
|
Copyright (c) 2018 The Stdlib Authors.
|
||
|
|
||
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
you may not use this file except in compliance with the License.
|
||
|
You may obtain a copy of the License at
|
||
|
|
||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
||
|
Unless required by applicable law or agreed to in writing, software
|
||
|
distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
See the License for the specific language governing permissions and
|
||
|
limitations under the License.
|
||
|
|
||
|
-->
|
||
|
|
||
|
# Epsilon Difference
|
||
|
|
||
|
> Compute the [relative difference][@stdlib/math/base/utils/relative-difference] of two real numbers in units of [double-precision floating-point epsilon][@stdlib/constants/float64/eps].
|
||
|
|
||
|
<section class="usage">
|
||
|
|
||
|
## Usage
|
||
|
|
||
|
```javascript
|
||
|
var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' );
|
||
|
```
|
||
|
|
||
|
#### epsdiff( x, y\[, scale] )
|
||
|
|
||
|
Computes the [relative difference][@stdlib/math/base/utils/relative-difference] of two real numbers in units of [double-precision floating-point epsilon][@stdlib/constants/float64/eps].
|
||
|
|
||
|
```javascript
|
||
|
var d = epsdiff( 12.15, 12.149999999999999 ); // => ~0.658ε
|
||
|
// returns ~0.658
|
||
|
```
|
||
|
|
||
|
The following [`scale`][@stdlib/math/base/utils/relative-difference] functions are supported:
|
||
|
|
||
|
- **max-abs**: maximum [absolute value][@stdlib/math/base/special/abs] of `x` and `y` (_default_).
|
||
|
- **max**: maximum value of `x` and `y`.
|
||
|
- **min-abs**: minimum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`.
|
||
|
- **min**: minimum value of `x` and `y`.
|
||
|
- **mean-abs**: arithmetic mean of the [absolute values][@stdlib/math/base/special/abs] 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][@stdlib/math/base/utils/absolute-difference] by dividing the [absolute difference][@stdlib/math/base/utils/absolute-difference] by the maximum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`. To scale by a different function, specify a scale function name.
|
||
|
|
||
|
```javascript
|
||
|
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`.
|
||
|
|
||
|
```javascript
|
||
|
function scale( x, y ) {
|
||
|
// Return the minimum value:
|
||
|
return ( x > y ) ? y : x;
|
||
|
}
|
||
|
|
||
|
var d = epsdiff( 1.0000000000000002, 1.0000000000000100, scale ); // => ~44ε
|
||
|
// returns ~44
|
||
|
```
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<!-- /.usage -->
|
||
|
|
||
|
<section class="notes">
|
||
|
|
||
|
## Notes
|
||
|
|
||
|
- If computing the [relative difference][@stdlib/math/base/utils/relative-difference] in units of [epsilon][@stdlib/constants/float64/eps] will result in overflow, the function returns the [maximum double-precision floating-point number][@stdlib/constants/float64/max].
|
||
|
|
||
|
```javascript
|
||
|
var d = epsdiff( 1.0e304, 1.0, 'min' ); // => ~1.798e308ε => 1.0e304/ε overflows
|
||
|
// returns ~1.798e308
|
||
|
```
|
||
|
|
||
|
- If the [absolute difference][@stdlib/math/base/utils/absolute-difference] of `x` and `y` is `0`, the [relative difference][@stdlib/math/base/utils/relative-difference] is **always** `0`.
|
||
|
|
||
|
```javascript
|
||
|
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`.
|
||
|
|
||
|
```javascript
|
||
|
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][@stdlib/math/base/utils/relative-difference] is `+infinity`.
|
||
|
|
||
|
```javascript
|
||
|
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`.
|
||
|
|
||
|
```javascript
|
||
|
var d = epsdiff( -1.0, 1.0, 'mean' ); // => |2/0|
|
||
|
// returns NaN
|
||
|
```
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<!-- /.notes -->
|
||
|
|
||
|
<section class="examples">
|
||
|
|
||
|
## Examples
|
||
|
|
||
|
<!-- eslint no-undef: "error" -->
|
||
|
|
||
|
```javascript
|
||
|
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 );
|
||
|
}
|
||
|
```
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<!-- /.examples -->
|
||
|
|
||
|
<section class="links">
|
||
|
|
||
|
[@stdlib/constants/float64/eps]: https://www.npmjs.com/package/@stdlib/constants-float64-eps
|
||
|
|
||
|
[@stdlib/constants/float64/max]: https://www.npmjs.com/package/@stdlib/constants-float64-max
|
||
|
|
||
|
[@stdlib/math/base/special/abs]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/special/abs
|
||
|
|
||
|
[@stdlib/math/base/utils/absolute-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/absolute-difference
|
||
|
|
||
|
[@stdlib/math/base/utils/relative-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/relative-difference
|
||
|
|
||
|
</section>
|
||
|
|
||
|
<!-- /.links -->
|