README.md (5528B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Epsilon Difference 22 23 > 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]. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' ); 31 ``` 32 33 #### epsdiff( x, y\[, scale] ) 34 35 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]. 36 37 ```javascript 38 var d = epsdiff( 12.15, 12.149999999999999 ); // => ~0.658ε 39 // returns ~0.658 40 ``` 41 42 The following [`scale`][@stdlib/math/base/utils/relative-difference] functions are supported: 43 44 - **max-abs**: maximum [absolute value][@stdlib/math/base/special/abs] of `x` and `y` (_default_). 45 - **max**: maximum value of `x` and `y`. 46 - **min-abs**: minimum [absolute value][@stdlib/math/base/special/abs] of `x` and `y`. 47 - **min**: minimum value of `x` and `y`. 48 - **mean-abs**: arithmetic mean of the [absolute values][@stdlib/math/base/special/abs] of `x` and `y`. 49 - **mean**: arithmetic mean of `x` and `y`. 50 - **x**: `x` (_noncommutative_). 51 - **y**: `y` (_noncommutative_). 52 53 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. 54 55 ```javascript 56 var d = epsdiff( 2.4341309458983933, 2.4341309458633909, 'mean-abs' ); // => ~64761.5ε => ~1.438e-11 57 // returns ~64761.5 58 ``` 59 60 To use a custom scale function, provide a `function` which accepts two numeric arguments `x` and `y`. 61 62 ```javascript 63 function scale( x, y ) { 64 // Return the minimum value: 65 return ( x > y ) ? y : x; 66 } 67 68 var d = epsdiff( 1.0000000000000002, 1.0000000000000100, scale ); // => ~44ε 69 // returns ~44 70 ``` 71 72 </section> 73 74 <!-- /.usage --> 75 76 <section class="notes"> 77 78 ## Notes 79 80 - 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]. 81 82 ```javascript 83 var d = epsdiff( 1.0e304, 1.0, 'min' ); // => ~1.798e308ε => 1.0e304/ε overflows 84 // returns ~1.798e308 85 ``` 86 87 - 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`. 88 89 ```javascript 90 var d = epsdiff( 0.0, 0.0 ); 91 // returns 0.0 92 93 d = epsdiff( 3.14, 3.14 ); 94 // returns 0.0 95 ``` 96 97 - If `x = y = +infinity` or `x = y = -infinity`, the function returns `NaN`. 98 99 ```javascript 100 var PINF = require( '@stdlib/constants/float64/pinf' ); 101 var NINF = require( '@stdlib/constants/float64/ninf' ); 102 103 var d = epsdiff( PINF, PINF ); 104 // returns NaN 105 106 d = epsdiff( NINF, NINF ); 107 // returns NaN 108 ``` 109 110 - If `x = -y = +infinity` or `-x = y = +infinity`, the [relative difference][@stdlib/math/base/utils/relative-difference] is `+infinity`. 111 112 ```javascript 113 var PINF = require( '@stdlib/constants/float64/pinf' ); 114 var NINF = require( '@stdlib/constants/float64/ninf' ); 115 116 var d = epsdiff( PINF, NINF ); 117 // returns Infinity 118 119 d = epsdiff( NINF, PINF ); 120 // returns Infinity 121 ``` 122 123 - If a `scale` function returns `0`, the function returns `NaN`. 124 125 ```javascript 126 var d = epsdiff( -1.0, 1.0, 'mean' ); // => |2/0| 127 // returns NaN 128 ``` 129 130 </section> 131 132 <!-- /.notes --> 133 134 <section class="examples"> 135 136 ## Examples 137 138 <!-- eslint no-undef: "error" --> 139 140 ```javascript 141 var randu = require( '@stdlib/random/base/randu' ); 142 var EPS = require( '@stdlib/constants/float64/eps' ); 143 var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' ); 144 145 var sign; 146 var x; 147 var y; 148 var d; 149 var i; 150 151 for ( i = 0; i < 100; i++ ) { 152 x = randu(); 153 sign = ( randu() > 0.5 ) ? 1.0 : -1.0; 154 y = x + ( sign*EPS*i ); 155 d = epsdiff( x, y ); 156 console.log( 'x = %d. y = %d. d = %dε.', x, y, d ); 157 } 158 ``` 159 160 </section> 161 162 <!-- /.examples --> 163 164 <section class="links"> 165 166 [@stdlib/constants/float64/eps]: https://www.npmjs.com/package/@stdlib/constants-float64-eps 167 168 [@stdlib/constants/float64/max]: https://www.npmjs.com/package/@stdlib/constants-float64-max 169 170 [@stdlib/math/base/special/abs]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/special/abs 171 172 [@stdlib/math/base/utils/absolute-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/absolute-difference 173 174 [@stdlib/math/base/utils/relative-difference]: https://www.npmjs.com/package/@stdlib/math/tree/main/base/utils/relative-difference 175 176 </section> 177 178 <!-- /.links -->