Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -10,6 +10,8 @@
 
 ### Features
 
+-   [`9b0d852`](https://github.com/stdlib-js/stdlib/commit/9b0d8520418c2788d20d446b6a39471b6393a787) - add `loopOrder` to namespace
+-   [`bdc9110`](https://github.com/stdlib-js/stdlib/commit/bdc91105259200e3ebb60aea16e918718301ce4b) - add `ndarray/base/loop-interchange-order`
 -   [`e5ddc80`](https://github.com/stdlib-js/stdlib/commit/e5ddc80ad0e60653c61dfc8847ecc65dff6c69f2) - add `outputDataType` to namespace
 -   [`5e7af03`](https://github.com/stdlib-js/stdlib/commit/5e7af03b8d27240b12f4fbf7bbad86ff57b64917) - add `ndarray/base/output-dtype`
 -   [`1f3ebc8`](https://github.com/stdlib-js/stdlib/commit/1f3ebc857c1c4b98d4681867b0d738b572631bcd) - add `promoteDataTypes` to namespace
@@ -386,6 +388,11 @@ A total of 15 issues were closed in this release:
 
 <details>
 
+-   [`603ba97`](https://github.com/stdlib-js/stdlib/commit/603ba974c88f33cb73ba53c69435183ca535ded9) - **docs:** fix parameter names _(by Athan Reines)_
+-   [`dcfb648`](https://github.com/stdlib-js/stdlib/commit/dcfb6488ac9624b23ec546f7c54a2da0156c6695) - **refactor:** use generalized utility for resolving loop data _(by Athan Reines)_
+-   [`d8fe0d8`](https://github.com/stdlib-js/stdlib/commit/d8fe0d87591079990591bd5727abdabaa81cd265) - **bench:** update value generation and update examples _(by Athan Reines)_
+-   [`9b0d852`](https://github.com/stdlib-js/stdlib/commit/9b0d8520418c2788d20d446b6a39471b6393a787) - **feat:** add `loopOrder` to namespace _(by Athan Reines)_
+-   [`bdc9110`](https://github.com/stdlib-js/stdlib/commit/bdc91105259200e3ebb60aea16e918718301ce4b) - **feat:** add `ndarray/base/loop-interchange-order` _(by Athan Reines)_
 -   [`09c158e`](https://github.com/stdlib-js/stdlib/commit/09c158e65824e081b5abef0454122e6c63a05586) - **docs:** update namespace table of contents [(#6987)](https://github.com/stdlib-js/stdlib/pull/6987) _(by stdlib-bot)_
 -   [`c1805ef`](https://github.com/stdlib-js/stdlib/commit/c1805eface6e530b09bfc77c800b249e6b321b2c) - **test:** fix broken tests _(by Athan Reines)_
 -   [`7ac3d7d`](https://github.com/stdlib-js/stdlib/commit/7ac3d7d0dbf2202eb1b1494ea91825fb46725df4) - **test:** remove console statements _(by Athan Reines)_

base/binary-loop-interchange-order/README.md

@@ -97,19 +97,23 @@ For all returned arrays, the first element corresponds to the innermost loop, an
 
 ## Examples
 
+<!-- eslint-disable max-len -->
+
 <!-- eslint no-undef: "error" -->
 
 ```javascript
 var array = require( '@stdlib/ndarray/array' );
-var loopOrder = require( '@stdlib/ndarray/base/binary-loop-interchange-order' );
+var getShape = require( '@stdlib/ndarray/shape' );
+var getStrides = require( '@stdlib/ndarray/strides' );
+var binaryLoopOrder = require( '@stdlib/ndarray/base/binary-loop-interchange-order' );
 
 // Create ndarrays:
 var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 var y = array( [ [ 5, 6 ], [ 7, 8 ] ] );
 var z = array( [ [ 0, 0 ], [ 0, 0 ] ] );
 
 // Resolve loop interchange data:
-var o = loopOrder( x.shape, x.strides, y.strides, z.strides );
+var o = binaryLoopOrder( getShape( x ), getStrides( x ), getStrides( y ), getStrides( z ) );
 // returns {...}
 
 console.log( o );

base/binary-loop-interchange-order/benchmark/benchmark.js

@@ -21,28 +21,32 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
 var isArray = require( '@stdlib/assert/is-array' );
 var shape2strides = require( './../../../base/shape2strides' );
 var pkg = require( './../package.json' ).name;
-var loopOrder = require( './../lib' );
+var binaryLoopOrder = require( './../lib' );
 
 
 // MAIN //
 
 bench( pkg+'::row-major', function benchmark( b ) {
 	var strides;
+	var factors;
 	var shape;
 	var out;
 	var i;
 
 	shape = [ 10, 10, 10 ];
 	strides = shape2strides( shape, 'row-major' );
+	factors = [
+		-1,
+		1
+	];
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		strides[ i%shape.length ] *= ( randu() < 0.5 ) ? -1 : 1;
-		out = loopOrder( shape, strides, strides, strides );
+		strides[ i%shape.length ] *= factors[ i%factors.length ];
+		out = binaryLoopOrder( shape, strides, strides, strides );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}
@@ -57,17 +61,22 @@ bench( pkg+'::row-major', function benchmark( b ) {
 
 bench( pkg+'::column-major', function benchmark( b ) {
 	var strides;
+	var factors;
 	var shape;
 	var out;
 	var i;
 
 	shape = [ 10, 10, 10 ];
 	strides = shape2strides( shape, 'column-major' );
+	factors = [
+		-1,
+		1
+	];
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		strides[ i%shape.length ] *= ( randu() < 0.5 ) ? -1 : 1;
-		out = loopOrder( shape, strides, strides, strides );
+		strides[ i%shape.length ] *= factors[ i%factors.length ];
+		out = binaryLoopOrder( shape, strides, strides, strides );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}

base/binary-loop-interchange-order/docs/types/index.d.ts

@@ -67,10 +67,10 @@ interface LoopOrderObject {
 *
 * -   The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
 *
-* @param sh - array dimensions
-* @param sx - first input array stride lengths
-* @param sy - second input array stride lengths
-* @param sz - output array stride lengths
+* @param shape - array dimensions
+* @param stridesX - first input array stride lengths
+* @param stridesY - second input array stride lengths
+* @param stridesZ - output array stride lengths
 * @returns loop interchange data
 *
 * @example
@@ -80,7 +80,7 @@ interface LoopOrderObject {
 * var sy = [ 24, 8, 1 ]; // row-major
 * var sz = [ 1, -2, 6 ]; // column-major
 *
-* var o = loopOrder( sh, sx, sy, sz );
+* var o = binaryLoopOrder( sh, sx, sy, sz );
 * // returns {...}
 *
 * var ssh = o.sh;

base/binary-loop-interchange-order/examples/index.js

@@ -19,6 +19,8 @@
 'use strict';
 
 var array = require( './../../../array' );
+var getShape = require( './../../../shape' );
+var getStrides = require( './../../../strides' );
 var loopOrder = require( './../lib' );
 
 // Create ndarrays:
@@ -27,7 +29,7 @@ var y = array( [ [ 5, 6 ], [ 7, 8 ] ] );
 var z = array( [ [ 0, 0 ], [ 0, 0 ] ] );
 
 // Resolve loop interchange data:
-var o = loopOrder( x.shape, x.strides, y.strides, z.strides );
+var o = loopOrder( getShape( x ), getStrides( x ), getStrides( y ), getStrides( z ) ); // eslint-disable-line max-len
 // returns {...}
 
 console.log( o );

base/binary-loop-interchange-order/lib/index.js

@@ -32,7 +32,7 @@
 * var sy = [ 24, 8, 1 ]; // row-major
 * var sz = [ 1, -2, 6 ]; // column-major
 *
-* var o = loopOrder( sh, sx, sy, sz );
+* var o = binaryLoopOrder( sh, sx, sy, sz );
 * // returns {...}
 *
 * var ssh = o.sh;

base/binary-loop-interchange-order/lib/main.js

@@ -20,17 +20,7 @@
 
 // MODULES //
 
-var zeroTo = require( '@stdlib/array/base/zero-to' );
-var copy = require( '@stdlib/array/base/copy-indexed' );
-var take = require( '@stdlib/array/base/take-indexed' );
-var strides2order = require( './../../../base/strides2order' );
-var sort2ins = require( './sort2ins.js' );
-
-
-// VARIABLES //
-
-// Number of arrays:
-var N = 3;
+var loopOrder = require( './../../../base/loop-interchange-order' );
 
 
 // MAIN //
@@ -60,7 +50,7 @@ var N = 3;
 * var sy = [ 24, 8, 1 ]; // row-major
 * var sz = [ 1, -2, 6 ]; // column-major
 *
-* var o = loopOrder( sh, sx, sy, sz );
+* var o = binaryLoopOrder( sh, sx, sy, sz );
 * // returns {...}
 *
 * var ssh = o.sh;
@@ -75,75 +65,17 @@ var N = 3;
 * var ssz = o.sz;
 * // returns [ 6, -2, 1 ]
 */
-function loopOrder( sh, sx, sy, sz ) {
-	var idx;
-	var tmp;
-	var max;
-	var len;
-	var arr;
-	var ox;
-	var oy;
-	var oz;
-	var i;
-	var j;
-
-	// Initialize a loop interchange index array for generating a loop order permutation:
-	idx = zeroTo( sh.length );
-
-	// Determine the order (layout) of each array:
-	ox = strides2order( sx );
-	oy = strides2order( sy );
-	oz = strides2order( sz );
-
-	// Determine which array should be used to generate the loop order:
-	tmp = [ [], [], [], [] ];
-	tmp[ ox ].push( sx );
-	tmp[ oy ].push( sy );
-	tmp[ oz ].push( sz );
-	max = tmp[ 0 ].length;
-	if ( max === N ) {
-		// If all arrays are "disorganized", then just use the first array, as, generally, each array is likely to be as un-ideal as every other:
-		arr = sx;
-	} else if ( max === N-1 ) {
-		// If all but one array is "disorganized", find the "organized" array...
-		for ( i = 1; i < 4; i++ ) {
-			if ( tmp[ i ].length ) {
-				arr = tmp[ i ][ 0 ];
-				break;
-			}
-		}
-	} else {
-		// Find the layout which is most common...
-		j = 0;
-		for ( i = 1; i < 4; i++ ) {
-			len = tmp[ i ].length;
-			if ( len >= max ) {
-				max = len;
-				j = i;
-			}
-		}
-		// Use the strides of the first array having the most common layout:
-		arr = tmp[ j ][ 0 ];
-	}
-	// Sort array strides in increasing order (of magnitude):
-	arr = copy( arr );
-	sort2ins( arr, idx );
-
-	// Permute the shape and array strides based on the sorted strides:
-	sh = take( sh, idx );
-	sx = take( sx, idx );
-	sy = take( sy, idx );
-	sz = take( sz, idx );
-
+function binaryLoopOrder( sh, sx, sy, sz ) {
+	var tmp = loopOrder( sh, [ sx, sy, sz ] );
 	return {
-		'sh': sh,
-		'sx': sx,
-		'sy': sy,
-		'sz': sz
+		'sh': tmp[ 0 ],
+		'sx': tmp[ 1 ],
+		'sy': tmp[ 2 ],
+		'sz': tmp[ 3 ]
 	};
 }
 
 
 // EXPORTS //
 
-module.exports = loopOrder;
+module.exports = binaryLoopOrder;

base/binary-loop-interchange-order/test/test.js

@@ -22,14 +22,14 @@
 
 var tape = require( 'tape' );
 var isArray = require( '@stdlib/assert/is-array' );
-var loopOrder = require( './../lib' );
+var binaryLoopOrder = require( './../lib' );
 
 
 // TESTS //
 
 tape( 'main export is a function', function test( t ) {
 	t.ok( true, __filename );
-	t.strictEqual( typeof loopOrder, 'function', 'main export is a function' );
+	t.strictEqual( typeof binaryLoopOrder, 'function', 'main export is a function' );
 	t.end();
 });
 
@@ -45,7 +45,7 @@ tape( 'the function returns loop interchange data (row-major)', function test( t
 	sy = [ -4, 2, 1 ];
 	sz = [ -8, 4, -2 ];
 
-	o = loopOrder( sh, sx, sy, sz );
+	o = binaryLoopOrder( sh, sx, sy, sz );
 
 	t.notEqual( o.sh, sh, 'returns new array' );
 	t.strictEqual( isArray( o.sh ), true, 'returns expected value' );
@@ -78,7 +78,7 @@ tape( 'the function returns loop interchange data (column-major)', function test
 	sy = [ -1, 4, 8 ];
 	sz = [ -2, 4, -8 ];
 
-	o = loopOrder( sh, sx, sy, sz );
+	o = binaryLoopOrder( sh, sx, sy, sz );
 
 	t.notEqual( o.sh, sh, 'returns new array' );
 	t.strictEqual( isArray( o.sh ), true, 'returns expected value' );
@@ -111,7 +111,7 @@ tape( 'the function returns loop interchange data (mixed order)', function test(
 	sy = [ 1, -4, -8 ];
 	sz = [ -8, 4, -2 ];
 
-	o = loopOrder( sh, sx, sy, sz );
+	o = binaryLoopOrder( sh, sx, sy, sz );
 
 	t.notEqual( o.sh, sh, 'returns new array' );
 	t.strictEqual( isArray( o.sh ), true, 'returns expected value' );
@@ -144,7 +144,7 @@ tape( 'the function returns loop interchange data (mostly disorganized)', functi
 	sy = [ -4, 2, 1 ]; // row-major
 	sz = [ -8, -2, 4 ]; // disorganized
 
-	o = loopOrder( sh, sx, sy, sz );
+	o = binaryLoopOrder( sh, sx, sy, sz );
 
 	t.notEqual( o.sh, sh, 'returns new array' );
 	t.strictEqual( isArray( o.sh ), true, 'returns expected value' );
@@ -177,7 +177,7 @@ tape( 'the function returns loop interchange data (all disorganized)', function
 	sy = [ 1, -4, 2 ]; // disorganized
 	sz = [ -8, -2, 4 ]; // disorganized
 
-	o = loopOrder( sh, sx, sy, sz );
+	o = binaryLoopOrder( sh, sx, sy, sz );
 
 	t.notEqual( o.sh, sh, 'returns new array' );
 	t.strictEqual( isArray( o.sh ), true, 'returns expected value' );
@@ -199,7 +199,7 @@ tape( 'the function returns loop interchange data (all disorganized)', function
 });
 
 tape( 'if provided empty arrays, the function returns empty arrays', function test( t ) {
-	var o = loopOrder( [], [], [], [] );
+	var o = binaryLoopOrder( [], [], [], [] );
 	t.deepEqual( o.sh, [], 'returns expected value' );
 	t.deepEqual( o.sx, [], 'returns expected value' );
 	t.deepEqual( o.sy, [], 'returns expected value' );

base/lib/index.js

@@ -463,6 +463,15 @@ setReadOnly( ns, 'ind2sub', require( './../../base/ind2sub' ) );
 */
 setReadOnly( ns, 'iterationOrder', require( './../../base/iteration-order' ) );
 
+/**
+* @name loopOrder
+* @memberof ns
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/ndarray/base/loop-interchange-order}
+*/
+setReadOnly( ns, 'loopOrder', require( './../../base/loop-interchange-order' ) );
+
 /**
 * @name map
 * @memberof ns