feat!: update the return value for n=1 in math/base/special/bernoulli

gunjjoshi · kgryte · web-flow · commit 47cfa907d643 · 2024-11-14T01:58:24.000-08:00
BREAKING CHANGE: update return value for `n=1` In order to migrate and preserve prior behavior, users should special case `n=1` and return `0`. The change in this commit aligns return values with SymPy and R; although, other libraries and envs choose to return `-0.5`. PR-URL: #3108 Ref: #3037 (comment) Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Signed-off-by: Gunj Joshi <gunjjoshi8372@gmail.com> Signed-off-by: Athan Reines <kgryte@gmail.com>
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/README.md b/lib/node_modules/@stdlib/math/base/special/bernoulli/README.md
@@ -43,7 +43,7 @@ var v = bernoulli( 0 );
 // returns 1.0
 
 v = bernoulli( 1 );
-// returns 0.0
+// returns 0.5
 
 v = bernoulli( 2 );
 // returns ~0.167
@@ -158,7 +158,7 @@ double out = stdlib_base_bernoulli( 0 );
 // returns 1.0
 
 out = stdlib_base_bernoulli( 1 );
-// returns 0.0
+// returns 0.5
 ```
 
 The function accepts the following arguments:
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/benchmark.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/benchmark.js
@@ -21,8 +21,7 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
-var floor = require( '@stdlib/math/base/special/floor' );
+var randu = require( '@stdlib/random/array/discrete-uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var pkg = require( './../package.json' ).name;
 var bernoulli = require( './../lib' );
@@ -35,10 +34,11 @@ bench( pkg, function benchmark( b ) {
 	var y;
 	var i;
 
+	x = randu( 100, 0, 500 );
+
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		x = floor( randu()*500.0 );
-		y = bernoulli( x );
+		y = bernoulli( x[ i % x.length ] );
 		if ( isnan( y ) ) {
 			b.fail( 'should not return NaN' );
 		}
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/benchmark.native.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/benchmark.native.js
@@ -22,8 +22,7 @@
 
 var resolve = require( 'path' ).resolve;
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
-var floor = require( '@stdlib/math/base/special/floor' );
+var randu = require( '@stdlib/random/array/discrete-uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var tryRequire = require( '@stdlib/utils/try-require' );
 var pkg = require( './../package.json' ).name;
@@ -44,10 +43,11 @@ bench( pkg+'::native', opts, function benchmark( b ) {
 	var y;
 	var i;
 
+	x = randu( 100, 0, 500 );
+
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		x = floor( randu() * 500.0 );
-		y = bernoulli( x );
+		y = bernoulli( x[ i % x.length ] );
 		if ( isnan( y ) ) {
 			b.fail( 'should not return NaN' );
 		}
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/c/native/benchmark.c b/lib/node_modules/@stdlib/math/base/special/bernoulli/benchmark/c/native/benchmark.c
@@ -91,15 +91,18 @@ static double rand_double( void ) {
 */
 static double benchmark( void ) {
 	double elapsed;
-	double x;
+	double x[ 100 ];
 	double y;
 	double t;
 	int i;
 
+	for ( i = 0; i < 100; i++ ) {
+		x[ i ] = ( 500.0 * rand_double() );
+	}
+
 	t = tic();
 	for ( i = 0; i < ITERATIONS; i++ ) {
-		x = ( 500.0 * rand_double() );
-		y = stdlib_base_bernoulli( x );
+		y = stdlib_base_bernoulli( (int)( x[ i % 100 ] ) );
 		if ( y != y ) {
 			printf( "should not return NaN\n" );
 			break;
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/docs/repl.txt b/lib/node_modules/@stdlib/math/base/special/bernoulli/docs/repl.txt
@@ -21,7 +21,7 @@
     > var y = {{alias}}( 0 )
     1.0
     > y = {{alias}}( 1 )
-    0.0
+    0.5
     > y = {{alias}}( 2 )
     ~0.167
     > y = {{alias}}( 3 )
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/docs/types/index.d.ts b/lib/node_modules/@stdlib/math/base/special/bernoulli/docs/types/index.d.ts
@@ -30,7 +30,7 @@
 *
 * @example
 * var y = bernoulli( 1 );
-* // returns 0.0
+* // returns 0.5
 *
 * @example
 * var y = bernoulli( 2 );
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/index.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/index.js
@@ -30,7 +30,7 @@
 * // returns 1.0
 *
 * y = bernoulli( 1 );
-* // returns 0.0
+* // returns 0.5
 *
 * y = bernoulli( 2 );
 * // returns ~0.166
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/main.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/main.js
@@ -47,7 +47,7 @@ var MAX_BERNOULLI = 258|0; // asm type annotation
 *
 * @example
 * var y = bernoulli( 1 );
-* // returns 0.0
+* // returns 0.5
 *
 * @example
 * var y = bernoulli( 2 );
@@ -85,6 +85,9 @@ function bernoulli( n ) {
 	if ( isnan( n ) || !isNonNegativeInteger( n ) ) {
 		return NaN;
 	}
+	if ( n === 1 ) {
+		return 0.5;
+	}
 	if ( isOdd( n ) ) {
 		return 0.0;
 	}
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/native.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/lib/native.js
@@ -37,7 +37,7 @@ var addon = require( './../src/addon.node' );
 *
 * @example
 * var y = bernoulli( 1 );
-* // returns 0.0
+* // returns 0.5
 *
 * @example
 * var y = bernoulli( 2 );
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/manifest.json b/lib/node_modules/@stdlib/math/base/special/bernoulli/manifest.json
@@ -37,8 +37,6 @@
       "libpath": [],
       "dependencies": [
         "@stdlib/math/base/napi/unary",
-        "@stdlib/math/base/assert/is-nonnegative-integer",
-        "@stdlib/math/base/assert/is-nan",
         "@stdlib/math/base/assert/is-odd",
         "@stdlib/constants/float64/ninf",
         "@stdlib/constants/float64/pinf"
@@ -55,8 +53,6 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/math/base/assert/is-nonnegative-integer",
-        "@stdlib/math/base/assert/is-nan",
         "@stdlib/math/base/assert/is-odd",
         "@stdlib/constants/float64/ninf",
         "@stdlib/constants/float64/pinf"
@@ -73,8 +69,6 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/math/base/assert/is-nonnegative-integer",
-        "@stdlib/math/base/assert/is-nan",
         "@stdlib/math/base/assert/is-odd",
         "@stdlib/constants/float64/ninf",
         "@stdlib/constants/float64/pinf"
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/src/main.c b/lib/node_modules/@stdlib/math/base/special/bernoulli/src/main.c
@@ -16,8 +16,6 @@
 * limitations under the License.
 */
 
-#include "stdlib/math/base/assert/is_nonnegative_integer.h"
-#include "stdlib/math/base/assert/is_nan.h"
 #include "stdlib/math/base/assert/is_odd.h"
 #include "stdlib/constants/float64/ninf.h"
 #include "stdlib/constants/float64/pinf.h"
@@ -170,9 +168,12 @@ int32_t MAX_BERNOULLI = 258;
 * // returns 1
 */
 double stdlib_base_bernoulli( const int32_t n ) {
-	if ( stdlib_base_is_nan( n ) || !stdlib_base_is_nonnegative_integer( n ) ) {
+	if ( n < 0 ) {
 		return 0.0 / 0.0; // NaN
 	}
+	if ( n == 1 ) {
+		return 0.5;
+	}
 	if ( stdlib_base_is_odd( n ) ) {
 		return 0.0;
 	}
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/test/test.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/test/test.js
@@ -44,31 +44,37 @@ tape( 'if provided a negative number, the function returns `NaN`', function test
 	var v;
 	var i;
 
-	t.strictEqual( isnan( bernoulli( -3.14 ) ), true, 'returns NaN' );
+	t.strictEqual( isnan( bernoulli( -3.14 ) ), true, 'returns expected value' );
 
 	for ( i = -1; i > -100; i-- ) {
 		v = bernoulli( i );
-		t.strictEqual( isnan( v ), true, 'returns NaN when provided ' + i );
+		t.strictEqual( isnan( v ), true, 'returns expected value when provided ' + i );
 	}
 	t.end();
 });
 
+tape( 'if provided `1`, the function returns `0.5`', function test( t ) {
+	var v = bernoulli( 1 );
+	t.strictEqual( v, 0.5, 'returns expected value' );
+	t.end();
+});
+
 tape( 'if provided `NaN`, the function returns `NaN`', function test( t ) {
 	var v = bernoulli( NaN );
-	t.strictEqual( isnan( v ), true, 'returns NaN when provided a NaN' );
+	t.strictEqual( isnan( v ), true, 'returns expected value' );
 	t.end();
 });
 
 tape( 'if provided a non-integer, the function returns `NaN`', function test( t ) {
 	var v = bernoulli( 3.14 );
-	t.strictEqual( isnan( v ), true, 'returns NaN' );
+	t.strictEqual( isnan( v ), true, 'returns expected value' );
 	t.end();
 });
 
 tape( 'the function returns the nth Bernoulli number for odd numbers', function test( t ) {
 	var v;
 	var i;
-	for ( i = 1; i < 500; i += 2 ) {
+	for ( i = 3; i < 500; i += 2 ) {
 		v = bernoulli( i );
 
 		// Odd Bernoulli numbers are equal to zero:
@@ -93,9 +99,9 @@ tape( 'the function returns +/- infinity for large integers', function test( t )
 	for ( i = 260; i < 1000; i += 2 ) {
 		v = bernoulli( i );
 		if ( i % 4 === 0 ) {
-			t.strictEqual( v, NINF, 'returns negative infinity' );
+			t.strictEqual( v, NINF, 'returns expected value' );
 		} else {
-			t.strictEqual( v, PINF, 'returns positive infinity' );
+			t.strictEqual( v, PINF, 'returns expected value' );
 		}
 	}
 	t.end();
diff --git a/lib/node_modules/@stdlib/math/base/special/bernoulli/test/test.native.js b/lib/node_modules/@stdlib/math/base/special/bernoulli/test/test.native.js
@@ -53,19 +53,25 @@ tape( 'if provided a negative number, the function returns `NaN`', opts, functio
 	var v;
 	var i;
 
-	t.strictEqual( isnan( bernoulli( -3.14 ) ), true, 'returns NaN' );
+	t.strictEqual( isnan( bernoulli( -3.14 ) ), true, 'returns expected value' );
 
 	for ( i = -1; i > -100; i-- ) {
 		v = bernoulli( i );
-		t.strictEqual( isnan( v ), true, 'returns NaN when provided ' + i );
+		t.strictEqual( isnan( v ), true, 'returns expected value when provided ' + i );
 	}
 	t.end();
 });
 
+tape( 'if provided `1`, the function returns `0.5`', opts, function test( t ) {
+	var v = bernoulli( 1 );
+	t.strictEqual( v, 0.5, 'returns expected value' );
+	t.end();
+});
+
 tape( 'the function returns the nth Bernoulli number for odd numbers', opts, function test( t ) {
 	var v;
 	var i;
-	for ( i = 1; i < 500; i += 2 ) {
+	for ( i = 3; i < 500; i += 2 ) {
 		v = bernoulli( i );
 
 		// Odd Bernoulli numbers are equal to zero:
@@ -90,9 +96,9 @@ tape( 'the function returns +/- infinity for large integers', opts, function tes
 	for ( i = 260; i < 1000; i += 2 ) {
 		v = bernoulli( i );
 		if ( i % 4 === 0 ) {
-			t.strictEqual( v, NINF, 'returns negative infinity' );
+			t.strictEqual( v, NINF, 'returns expected value' );
 		} else {
-			t.strictEqual( v, PINF, 'returns positive infinity' );
+			t.strictEqual( v, PINF, 'returns expected value' );
 		}
 	}
 	t.end();

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@`
`30`	`30`	`*`
`31`	`31`	`* @example`
`32`	`32`	`* var y = bernoulli( 1 );`
`33`		`-* // returns 0.0`
	`33`	`+* // returns 0.5`
`34`	`34`	`*`
`35`	`35`	`* @example`
`36`	`36`	`* var y = bernoulli( 2 );`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ var MAX_BERNOULLI = 258\|0; // asm type annotation`
`47`	`47`	`*`
`48`	`48`	`* @example`
`49`	`49`	`* var y = bernoulli( 1 );`
`50`		`-* // returns 0.0`
	`50`	`+* // returns 0.5`
`51`	`51`	`*`
`52`	`52`	`* @example`
`53`	`53`	`* var y = bernoulli( 2 );`
`@@ -85,6 +85,9 @@ function bernoulli( n ) {`
`85`	`85`	`if ( isnan( n ) \|\| !isNonNegativeInteger( n ) ) {`
`86`	`86`	`return NaN;`
`87`	`87`	`}`
	`88`	`+ if ( n === 1 ) {`
	`89`	`+ return 0.5;`
	`90`	`+ }`
`88`	`91`	`if ( isOdd( n ) ) {`
`89`	`92`	`return 0.0;`
`90`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,7 +37,7 @@ var addon = require( './../src/addon.node' );`
`37`	`37`	`*`
`38`	`38`	`* @example`
`39`	`39`	`* var y = bernoulli( 1 );`
`40`		`-* // returns 0.0`
	`40`	`+* // returns 0.5`
`41`	`41`	`*`
`42`	`42`	`* @example`
`43`	`43`	`* var y = bernoulli( 2 );`