fix: avoid cancellation near |x| = 1 in math/base/special/acoth

lib/node_modules/@stdlib/math/base/special/acoth/lib/main.js

@@ -21,6 +21,7 @@
 // MODULES //
 
 var atanh = require( '@stdlib/math/base/special/atanh' );
+var log1p = require( '@stdlib/math/base/special/log1p' );
 
 
 // MAIN //
@@ -52,6 +53,13 @@ var atanh = require( '@stdlib/math/base/special/atanh' );
 * // returns NaN
 */
 function acoth( x ) {
+	// Near `|x| = 1`, `atanh( 1/x )` loses the low bits of `1-|1/x|` to the rounding of `1/x`. Use `acoth(x) = log( (x+1)/(x-1) )/2 = log1p( 2/(x-1) )/2` instead, where `x-1` is exact for `1 <= x <= 2`:
+	if ( x >= 1.0 && x <= 2.0 ) {
+		return 0.5 * log1p( 2.0 / ( x - 1.0 ) );
+	}
+	if ( x <= -1.0 && x >= -2.0 ) {
+		return -0.5 * log1p( 2.0 / ( -x - 1.0 ) );
+	}
 	return atanh( 1.0/x );
 }
 

lib/node_modules/@stdlib/math/base/special/acoth/manifest.json

@@ -37,7 +37,8 @@
       "libpath": [],
       "dependencies": [
         "@stdlib/math/base/napi/unary",
-        "@stdlib/math/base/special/atanh"
+        "@stdlib/math/base/special/atanh",
+        "@stdlib/math/base/special/log1p"
       ]
     },
     {
@@ -51,7 +52,8 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/math/base/special/atanh"
+        "@stdlib/math/base/special/atanh",
+        "@stdlib/math/base/special/log1p"
       ]
     },
     {
@@ -65,7 +67,8 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/math/base/special/atanh"
+        "@stdlib/math/base/special/atanh",
+        "@stdlib/math/base/special/log1p"
       ]
     }
   ]

lib/node_modules/@stdlib/math/base/special/acoth/src/main.c

@@ -18,6 +18,7 @@
 
 #include "stdlib/math/base/special/acoth.h"
 #include "stdlib/math/base/special/atanh.h"
+#include "stdlib/math/base/special/log1p.h"
 
 /**
 * Computes the inverse hyperbolic cotangent of a double-precision floating-point number.
@@ -30,5 +31,12 @@
 * // returns ~0.5493
 */
 double stdlib_base_acoth( const double x ) {
+	// Near `|x| = 1`, `atanh( 1/x )` loses the low bits of `1-|1/x|` to the rounding of `1/x`. Use `acoth(x) = log( (x+1)/(x-1) )/2 = log1p( 2/(x-1) )/2` instead, where `x-1` is exact for `1 <= x <= 2`:
+	if ( x >= 1.0 && x <= 2.0 ) {
+		return 0.5 * stdlib_base_log1p( 2.0 / ( x - 1.0 ) );
+	}
+	if ( x <= -1.0 && x >= -2.0 ) {
+		return -0.5 * stdlib_base_log1p( 2.0 / ( -x - 1.0 ) );
+	}
 	return stdlib_base_atanh( 1.0 / x );
 }

lib/node_modules/@stdlib/math/base/special/acoth/test/fixtures/julia/runner.jl

@@ -19,7 +19,7 @@
 import JSON
 
 """
     gen( domain, name )
 
 Generate fixture data and write to file.
 
@@ -37,7 +37,9 @@
 """
 function gen( domain, name )
 	x = collect( domain );
-	y = acoth.( x );
+	y = setprecision( BigFloat, 256 ) do
+		Float64.( acoth.( BigFloat.( x ) ) );
+	end
 
 	# Store data to be written to file as a collection:
 	data = Dict([
@@ -92,3 +94,11 @@
 # Huge negative values:
 x = range( -1.0e300, stop = -1.0e308, length = 1003 );
 gen( x, "huge_negative.json" );
+
+# Values close to one (in `Float64`, `acoth` is `atanh(1/x)` and loses the low bits of `1-1/x`):
+x = 1.0 .+ exp10.( range( -15.0, stop = -1.0, length = 1000 ) );
+gen( x, "near_positive_one.json" );
+
+x = -1.0 .- exp10.( range( -15.0, stop = -1.0, length = 1000 ) );
+gen( x, "near_negative_one.json" );
+

lib/node_modules/@stdlib/math/base/special/acoth/test/test.js

@@ -37,6 +37,8 @@ var largerNegative = require( './fixtures/julia/larger_negative.json' );
 var largeNegative = require( './fixtures/julia/large_negative.json' );
 var mediumNegative = require( './fixtures/julia/medium_negative.json' );
 var hugeNegative = require( './fixtures/julia/huge_negative.json' );
+var nearPositiveOne = require( './fixtures/julia/near_positive_one.json' );
+var nearNegativeOne = require( './fixtures/julia/near_negative_one.json' );
 
 
 // TESTS //
@@ -57,7 +59,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for medium positiv
 	expected = mediumPositive.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -72,7 +74,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for medium negativ
 	expected = mediumNegative.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -87,7 +89,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for large positive
 	expected = largePositive.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -102,7 +104,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for large negative
 	expected = largeNegative.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -167,6 +169,36 @@ tape( 'the function computes the inverse hyperbolic cotangent for huge negative
 	t.end();
 });
 
+tape( 'the function computes the inverse hyperbolic cotangent for values close to `1`', function test( t ) {
+	var expected;
+	var x;
+	var y;
+	var i;
+
+	x = nearPositiveOne.x;
+	expected = nearPositiveOne.expected;
+	for ( i = 0; i < x.length; i++ ) {
+		y = acoth( x[ i ] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+	}
+	t.end();
+});
+
+tape( 'the function computes the inverse hyperbolic cotangent for values close to `-1`', function test( t ) {
+	var expected;
+	var x;
+	var y;
+	var i;
+
+	x = nearNegativeOne.x;
+	expected = nearNegativeOne.expected;
+	for ( i = 0; i < x.length; i++ ) {
+		y = acoth( x[ i ] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+	}
+	t.end();
+});
+
 tape( 'the function returns `NaN` if provided `NaN`', function test( t ) {
 	var v = acoth( NaN );
 	t.strictEqual( isnan( v ), true, 'returns expected value' );

lib/node_modules/@stdlib/math/base/special/acoth/test/test.native.js

@@ -38,6 +38,8 @@ var largerNegative = require( './fixtures/julia/larger_negative.json' );
 var largeNegative = require( './fixtures/julia/large_negative.json' );
 var mediumNegative = require( './fixtures/julia/medium_negative.json' );
 var hugeNegative = require( './fixtures/julia/huge_negative.json' );
+var nearPositiveOne = require( './fixtures/julia/near_positive_one.json' );
+var nearNegativeOne = require( './fixtures/julia/near_negative_one.json' );
 
 
 // VARIABLES //
@@ -66,7 +68,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for medium positiv
 	expected = mediumPositive.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -81,7 +83,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for medium negativ
 	expected = mediumNegative.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -96,7 +98,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for large positive
 	expected = largePositive.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -111,7 +113,7 @@ tape( 'the function computes the inverse hyperbolic cotangent for large negative
 	expected = largeNegative.expected;
 	for ( i = 0; i < x.length; i++ ) {
 		y = acoth( x[ i ] );
-		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 2 ), true, 'returns expected value' );
 	}
 	t.end();
 });
@@ -176,6 +178,36 @@ tape( 'the function computes the inverse hyperbolic cotangent for huge negative
 	t.end();
 });
 
+tape( 'the function computes the inverse hyperbolic cotangent for values close to `1`', opts, function test( t ) {
+	var expected;
+	var x;
+	var y;
+	var i;
+
+	x = nearPositiveOne.x;
+	expected = nearPositiveOne.expected;
+	for ( i = 0; i < x.length; i++ ) {
+		y = acoth( x[ i ] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+	}
+	t.end();
+});
+
+tape( 'the function computes the inverse hyperbolic cotangent for values close to `-1`', opts, function test( t ) {
+	var expected;
+	var x;
+	var y;
+	var i;
+
+	x = nearNegativeOne.x;
+	expected = nearNegativeOne.expected;
+	for ( i = 0; i < x.length; i++ ) {
+		y = acoth( x[ i ] );
+		t.strictEqual( isAlmostSameValue( y, expected[ i ], 1 ), true, 'returns expected value' );
+	}
+	t.end();
+});
+
 tape( 'the function returns `NaN` if provided `NaN`', opts, function test( t ) {
 	var v = acoth( NaN );
 	t.strictEqual( isnan( v ), true, 'returns expected value' );