Add xlogy function

Author: Planeshifter

lib/node_modules/@stdlib/math/base/special/xlogy/README.md

@@ -0,0 +1,75 @@
+# xlogy
+
+> Compute `x * ln(y)` so that the result is `0` if `x = 0`.
+
+
+<section class="usage">
+
+## Usage
+
+``` javascript
+var xlogy = require( '@stdlib/math/base/special/xlogy' );
+```
+
+#### xlogy( x, y )
+
+Computes `x * ln(y)` so that the result is `0` if `x = 0`.
+
+``` javascript
+var out = xlogy( 3.0, 2.0 );
+// returns ~2.079
+
+out = xlogy( 1.5, 5.9 );
+// returns ~2.662
+
+out = xlogy( 0.9, 1.0 );
+// returns 0.0
+
+out = xlogy( 0.0, -2.0 );
+// returns 0.0
+
+out = xlogy( 1.5, NaN );
+// returns NaN
+
+out = xlogy( 0.0, NaN );
+// returns NaN
+
+out = xlogy( NaN, 2.3 );
+// returns NaN
+```
+
+</section>
+
+<!-- /.usage -->
+
+
+<section class="examples">
+
+## Examples
+
+``` javascript
+var randu = require( '@stdlib/math/base/random/randu' );
+var xlogy = require( '@stdlib/math/base/special/xlogy' );
+
+var x;
+var y;
+var i;
+
+for ( i = 0; i < 100; i++ ) {
+    x = randu();
+    x = x < 0.5 ? 0.0 : x;
+    y = ( randu() * 20.0 ) - 5.0;
+    console.log( 'xlogy(%d,%d) = %d', x, y, xlogy( x, y ) );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/math/base/special/xlogy/benchmark/benchmark.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var randu = require( '@stdlib/math/base/random/randu' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var pkg = require( './../package.json' ).name;
+var xlogy = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var out;
+	var x;
+	var y;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		x = randu() * 10.0;
+		y = randu() * 10.0;
+		out = xlogy( x, y );
+		if ( isnan( out ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( out ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/math/base/special/xlogy/docs/repl.txt

@@ -0,0 +1,37 @@
+
+{{alias}}( x, y )
+    Computes `x * ln(y)` so that the result is `0` if `x = 0`.
+
+    Parameters
+    ----------
+    x: number
+        Input value.
+
+    y: number
+        Input value.
+
+    Returns
+    -------
+    out: number
+        Function value.
+
+    Examples
+    --------
+    > var out = {{alias}}( 3.0, 2.0 )
+    ~2.079
+    > out = {{alias}}( 1.5, 5.9 )
+    ~2.662
+    > out = {{alias}}( 0.9, 1.0 )
+    0.0
+    > out = {{alias}}( 0.0, -2.0 )
+    0.0
+    > out = {{alias}}( 1.5, NaN )
+    NaN
+    > out = {{alias}}( 0.0, NaN )
+    NaN
+    > out = {{alias}}( NaN, 2.3 )
+    NaN
+
+    See Also
+    --------
+

lib/node_modules/@stdlib/math/base/special/xlogy/examples/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+var randu = require( '@stdlib/math/base/random/randu' );
+var xlogy = require( './../lib' );
+
+var x;
+var y;
+var i;
+
+for ( i = 0; i < 100; i++ ) {
+	x = randu();
+	x = x < 0.5 ? 0.0 : x;
+	y = ( randu() * 20.0 ) - 5.0;
+	console.log( 'xlogy(%d,%d) = %d', x, y, xlogy( x, y ) );
+}

lib/node_modules/@stdlib/math/base/special/xlogy/lib/index.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+* Compute `x * ln(y)` so that the result is `0` if `x = 0`.
+*
+* @module @stdlib/math/base/special/xlogy
+*
+* @example
+* var xlogy = require( '@stdlib/math/base/special/xlogy' );
+*
+* var out = xlogy( 3.0, 2.0 );
+* // returns ~2.079
+*
+* out = xlogy( 1.5, 5.9 );
+* // returns ~2.662
+*
+* out = xlogy( 0.9, 1.0 );
+* // returns 0.0
+*
+* out = xlogy( 0.0, -2.0 );
+* // returns 0.0
+*
+* out = xlogy( 1.5, NaN );
+* // returns NaN
+*
+* out = xlogy( 0.0, NaN );
+* // returns NaN
+*
+* out = xlogy( NaN, 2.3 );
+* // returns NaN
+*/
+
+// MODULES //
+
+var xlogy = require( './xlogy.js' );
+
+
+// EXPORTS //
+
+module.exports = xlogy;

lib/node_modules/@stdlib/math/base/special/xlogy/lib/xlogy.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// MODULES //
+
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var ln = require( '@stdlib/math/base/special/ln' );
+
+
+// MAIN //
+
+/**
+* Computes `x * ln(y)` so that the result is `0` if `x = 0`.
+*
+* @param {number} x - input value
+* @param {number} y - input value
+* @returns {number} function value
+*
+* @example
+* var out = xlogy( 3.0, 2.0 );
+* // returns ~2.079
+*
+* @example
+* var out = xlogy( 1.5, 5.9 );
+* // returns ~2.662
+*
+* @example
+* var out = xlogy( 0.9, 1.0 );
+* // returns 0.0
+*
+* @example
+* var out = xlogy( 0.0, -2.0 );
+* // returns 0.0
+*
+* @example
+* var out = xlogy( 1.5, NaN );
+* // returns NaN
+*
+* @example
+* var out = xlogy( 0.0, NaN );
+* // returns NaN
+*
+* @example
+* var out = xlogy( NaN, 2.3 );
+* // returns NaN
+*/
+function xlogy( x, y ) {
+	if ( x === 0.0 && !isnan( y ) ) {
+		return 0.0;
+	}
+	return x * ln( y );
+} // end FUNCTION xlogy()
+
+
+// EXPORTS //
+
+module.exports = xlogy;

lib/node_modules/@stdlib/math/base/special/xlogy/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@stdlib/math/base/special/xlogy",
+  "version": "0.0.0",
+  "description": "Compute `x * ln(y)` so that the result is `0` if `x = 0`.",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "scripts": {},
+  "main": "./lib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "keywords": [
+    "stdlib",
+    "stdmath",
+    "mathematics",
+    "math",
+    "natural",
+    "logarithm",
+    "log",
+    "ln",
+    "special"
+  ],
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "license": "Apache-2.0"
+}

lib/node_modules/@stdlib/math/base/special/xlogy/test/fixtures/python/large_large.json

@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+"""Generate fixtures."""
+
+import os
+import json
+import numpy as np
+from scipy.special import xlogy
+
+# Get the file path:
+FILE = os.path.realpath(__file__)
+
+# Extract the directory in which this file resides:
+DIR = os.path.dirname(FILE)
+
+
+def gen(x, y, name):
+    """Generate fixture data and writes them to file.
+
+    # Arguments
+
+    * `x`: first parameter
+    * `y`: second parameter
+    * `name::str`: output filename
+
+    # Examples
+
+    ``` python
+    python> x = random(500) * 5.0
+    python> y = random(500) * 5.0
+    python> gen(x, y, './data.json')
+    ```
+    """
+    out = xlogy(x,y)
+
+    # Store data to be written to file as a dictionary:
+    data = {
+        "x": x.tolist(),
+        "y": y.tolist(),
+        "expected": out.tolist()
+    }
+
+    # Based on the script directory, create an output filepath:
+    filepath = os.path.join(DIR, name)
+
+    # Write the data to the output filepath as JSON:
+    with open(filepath, "w") as outfile:
+        json.dump(data, outfile)
+
+
+def main():
+    """Generate fixture data."""
+    x = np.random.random(500) * 5.0
+    y = np.random.random(500) * 5.0
+    gen(x, y, "small_small.json")
+
+    x = np.random.random(500) * 5.0
+    y = np.random.random(500) * 100.0
+    gen(x, y, "small_large.json")
+
+    x = np.random.random(500) * 100.0
+    y = np.random.random(500) * 5.0
+    gen(x, y, "large_small.json")
+
+    x = np.random.random(500) * 100.0
+    y = np.random.random(500) * 100.0
+    gen(x, y, "large_large.json")
+
+if __name__ == "__main__":
+    main()