@stdlib/ndarray-base-binary-reduce-strided1d 0.1.0

package/lib/nd.js

@@ -0,0 +1,189 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var numel = require( '@stdlib/ndarray-base-numel' );
+var vind2bind = require( '@stdlib/ndarray-base-vind2bind' );
+var copyIndexed = require( '@stdlib/array-base-copy-indexed' );
+var zeros = require( '@stdlib/array-base-zeros' );
+var setViewOffsets = require( './set_view_offsets.js' );
+var offsets = require( './offsets.js' );
+
+
+// VARIABLES //
+
+var MODE = 'throw';
+
+
+// MAIN //
+
+/**
+* Performs a reduction over two input ndarrays and assigns results to a provided output ndarray.
+*
+* @private
+* @param {Function} fcn - wrapper for a one-dimensional strided array reduction function
+* @param {Array<Object>} arrays - ndarrays
+* @param {Array<Object>} views - initialized ndarray-like objects representing sub-array views
+* @param {Function} strategyX - first input ndarray reshape strategy
+* @param {Function} strategyY - second input ndarray reshape strategy
+* @param {Options} opts - function options
+* @returns {void}
+*
+* @example
+* var Float64Array = require( '@stdlib/array-float64' );
+* var ndarray2array = require( '@stdlib/ndarray-base-to-array' );
+* var gdot = require( '@stdlib/blas-base-ndarray-gdot' );
+*
+* // Create data buffers:
+* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+* var ybuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+* var zbuf = new Float64Array( [ 0.0, 0.0, 0.0 ] );
+*
+* // Define the array shapes:
+* var xsh = [ 3, 2, 2 ];
+* var ysh = [ 3, 2, 2 ];
+* var zsh = [ 3 ];
+*
+* // Define the array strides:
+* var sx = [ 4, 2, 1 ];
+* var sy = [ 4, 2, 1 ];
+* var sz = [ 1 ];
+*
+* // Define the index offsets:
+* var ox = 0;
+* var oy = 0;
+* var oz = 0;
+*
+* // Create input ndarray-like objects:
+* var x = {
+*     'dtype': 'float64',
+*     'data': xbuf,
+*     'shape': xsh,
+*     'strides': sx,
+*     'offset': ox,
+*     'order': 'row-major'
+* };
+* var y = {
+*     'dtype': 'float64',
+*     'data': ybuf,
+*     'shape': ysh,
+*     'strides': sy,
+*     'offset': oy,
+*     'order': 'row-major'
+* };
+*
+* // Create an output ndarray-like object:
+* var z = {
+*     'dtype': 'float64',
+*     'data': zbuf,
+*     'shape': zsh,
+*     'strides': sz,
+*     'offset': oz,
+*     'order': 'row-major'
+* };
+*
+* // Initialize ndarray-like objects representing sub-array views:
+* var views = [
+*     {
+*         'dtype': x.dtype,
+*         'data': x.data,
+*         'shape': [ 2, 2 ],
+*         'strides': [ 2, 1 ],
+*         'offset': x.offset,
+*         'order': x.order
+*     },
+*     {
+*         'dtype': y.dtype,
+*         'data': y.data,
+*         'shape': [ 2, 2 ],
+*         'strides': [ 2, 1 ],
+*         'offset': y.offset,
+*         'order': y.order
+*     }
+* ];
+*
+* // Define a reshape strategy:
+* function strategy( x ) {
+*     return {
+*         'dtype': x.dtype,
+*         'data': x.data,
+*         'shape': [ 4 ],
+*         'strides': [ 1 ],
+*         'offset': x.offset,
+*         'order': x.order
+*     };
+* }
+*
+* // Perform a reduction:
+* binarynd( gdot, [ x, y, z ], views, strategy, strategy, {} );
+*
+* var arr = ndarray2array( z.data, z.shape, z.strides, z.offset, z.order );
+* // returns [ 30.0, 174.0, 446.0 ]
+*/
+function binarynd( fcn, arrays, views, strategyX, strategyY, opts ) {
+	var zbuf;
+	var len;
+	var arr;
+	var sh;
+	var iv;
+	var io;
+	var N;
+	var z;
+	var v;
+	var i;
+	var j;
+
+	N = arrays.length;
+
+	// Resolve the output ndarray and associated shape:
+	z = arrays[ 2 ];
+	sh = z.shape;
+
+	// Compute the total number of elements over which to iterate:
+	len = numel( sh );
+
+	// Resolve a list of pointers to the first indexed elements in the respective ndarrays:
+	iv = offsets( arrays );
+
+	// Shallow copy the list of views to an internal array so that we can update with reshaped views without impacting the original list of views:
+	v = copyIndexed( views );
+
+	// Cache a reference to the output ndarray buffer:
+	zbuf = z.data;
+
+	// Iterate based on the linear **view** index, regardless as to how the data is stored in memory...
+	io = zeros( N );
+	for ( i = 0; i < len; i++ ) {
+		for ( j = 0; j < N; j++ ) {
+			arr = arrays[ j ];
+			io[ j ] = vind2bind( sh, arr.strides, iv[ j ], arr.order, i, MODE );
+		}
+		setViewOffsets( views, io );
+		v[ 0 ] = strategyX( views[ 0 ] );
+		v[ 1 ] = strategyY( views[ 1 ] );
+		zbuf[ io[2] ] = fcn( v, opts );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = binarynd;

package/lib/nd_accessors.js

@@ -0,0 +1,198 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var numel = require( '@stdlib/ndarray-base-numel' );
+var vind2bind = require( '@stdlib/ndarray-base-vind2bind' );
+var copyIndexed = require( '@stdlib/array-base-copy-indexed' );
+var zeros = require( '@stdlib/array-base-zeros' );
+var setViewOffsets = require( './set_view_offsets.js' );
+var offsets = require( './offsets.js' );
+
+
+// VARIABLES //
+
+var MODE = 'throw';
+
+
+// MAIN //
+
+/**
+* Performs a reduction over two input ndarrays and assigns results to a provided output ndarray.
+*
+* @private
+* @param {Function} fcn - wrapper for a one-dimensional strided array reduction function
+* @param {Array<Object>} arrays - ndarrays
+* @param {Array<Object>} views - initialized ndarray-like objects representing sub-array views
+* @param {Function} strategyX - first input ndarray reshape strategy
+* @param {Function} strategyY - second input ndarray reshape strategy
+* @param {Options} opts - function options
+* @returns {void}
+*
+* @example
+* var toAccessorArray = require( '@stdlib/array-base-to-accessor-array' );
+* var accessors = require( '@stdlib/array-base-accessors' );
+* var Float64Array = require( '@stdlib/array-float64' );
+* var ndarray2array = require( '@stdlib/ndarray-base-to-array' );
+* var gdot = require( '@stdlib/blas-base-ndarray-gdot' );
+*
+* // Create data buffers:
+* var xbuf = toAccessorArray( new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ) );
+* var ybuf = toAccessorArray( new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ) );
+* var zbuf = toAccessorArray( new Float64Array( [ 0.0, 0.0, 0.0 ] ) );
+*
+* // Define the array shapes:
+* var xsh = [ 3, 2, 2 ];
+* var ysh = [ 3, 2, 2 ];
+* var zsh = [ 3 ];
+*
+* // Define the array strides:
+* var sx = [ 4, 2, 1 ];
+* var sy = [ 4, 2, 1 ];
+* var sz = [ 1 ];
+*
+* // Define the index offsets:
+* var ox = 0;
+* var oy = 0;
+* var oz = 0;
+*
+* // Create input ndarray-like objects:
+* var x = {
+*     'dtype': 'float64',
+*     'data': xbuf,
+*     'shape': xsh,
+*     'strides': sx,
+*     'offset': ox,
+*     'order': 'row-major',
+*     'accessors': accessors( xbuf ).accessors
+* };
+* var y = {
+*     'dtype': 'float64',
+*     'data': ybuf,
+*     'shape': ysh,
+*     'strides': sy,
+*     'offset': oy,
+*     'order': 'row-major',
+*     'accessors': accessors( ybuf ).accessors
+* };
+*
+* // Create an output ndarray-like object:
+* var z = {
+*     'dtype': 'float64',
+*     'data': zbuf,
+*     'shape': zsh,
+*     'strides': sz,
+*     'offset': oz,
+*     'order': 'row-major',
+*     'accessors': accessors( zbuf ).accessors
+* };
+*
+* // Initialize ndarray-like objects representing sub-array views:
+* var views = [
+*     {
+*         'dtype': x.dtype,
+*         'data': x.data,
+*         'shape': [ 2, 2 ],
+*         'strides': [ 2, 1 ],
+*         'offset': x.offset,
+*         'order': x.order
+*     },
+*     {
+*         'dtype': y.dtype,
+*         'data': y.data,
+*         'shape': [ 2, 2 ],
+*         'strides': [ 2, 1 ],
+*         'offset': y.offset,
+*         'order': y.order
+*     }
+* ];
+*
+* // Define a reshape strategy:
+* function strategy( x ) {
+*     return {
+*         'dtype': x.dtype,
+*         'data': x.data,
+*         'shape': [ 4 ],
+*         'strides': [ 1 ],
+*         'offset': x.offset,
+*         'order': x.order
+*     };
+* }
+*
+* // Perform a reduction:
+* binarynd( gdot, [ x, y, z ], views, strategy, strategy, {} );
+*
+* var arr = ndarray2array( z.data, z.shape, z.strides, z.offset, z.order );
+* // returns [ 30.0, 174.0, 446.0 ]
+*/
+function binarynd( fcn, arrays, views, strategyX, strategyY, opts ) {
+	var zbuf;
+	var len;
+	var arr;
+	var set;
+	var sh;
+	var iv;
+	var io;
+	var N;
+	var z;
+	var v;
+	var i;
+	var j;
+
+	N = arrays.length;
+
+	// Resolve the output ndarray and associated shape:
+	z = arrays[ 2 ];
+	sh = z.shape;
+
+	// Compute the total number of elements over which to iterate:
+	len = numel( sh );
+
+	// Resolve a list of pointers to the first indexed elements in the respective ndarrays:
+	iv = offsets( arrays );
+
+	// Shallow copy the list of views to an internal array so that we can update with reshaped views without impacting the original list of views:
+	v = copyIndexed( views );
+
+	// Cache a reference to the output ndarray buffer:
+	zbuf = z.data;
+
+	// Cache accessors:
+	set = z.accessors[ 1 ];
+
+	// Iterate based on the linear **view** index, regardless as to how the data is stored in memory...
+	io = zeros( N );
+	for ( i = 0; i < len; i++ ) {
+		for ( j = 0; j < N; j++ ) {
+			arr = arrays[ j ];
+			io[ j ] = vind2bind( sh, arr.strides, iv[ j ], arr.order, i, MODE );
+		}
+		setViewOffsets( views, io );
+		v[ 0 ] = strategyX( views[ 0 ] );
+		v[ 1 ] = strategyY( views[ 1 ] );
+		set( zbuf, io[2], fcn( v, opts ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = binarynd;

package/lib/offsets.js

@@ -0,0 +1,42 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MAIN //
+
+/**
+* Resolves index offsets from a list of ndarray-like objects.
+*
+* @private
+* @param {ArrayLikeObject<Object>} arrays - list of ndarray-like objects
+* @returns {NonNegativeIntegerArray} list of offsets
+*/
+function offsets( arrays ) {
+	var out = [];
+	var i;
+	for ( i = 0; i < arrays.length; i++ ) {
+		out.push( arrays[ i ].offset );
+	}
+	return out;
+}
+
+
+// EXPORTS //
+
+module.exports = offsets;

package/lib/reshape_strategy.js

@@ -0,0 +1,260 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var iterationOrder = require( '@stdlib/ndarray-base-iteration-order' );
+var minmaxViewBufferIndex = require( '@stdlib/ndarray-base-minmax-view-buffer-index' ).assign;
+var ndarraylike2object = require( '@stdlib/ndarray-base-ndarraylike2object' );
+var assign = require( '@stdlib/ndarray-base-assign' );
+var ndarraylike2ndarray = require( '@stdlib/ndarray-base-ndarraylike2ndarray' );
+var emptyLike = require( '@stdlib/ndarray-base-empty-like' );
+
+
+// FUNCTIONS //
+
+/**
+* Returns an input ndarray.
+*
+* @private
+* @param {ndarrayLike} x - input ndarray
+* @returns {ndarrayLike} input ndarray
+*/
+function identity( x ) {
+	return x;
+}
+
+/**
+* Broadcasts a zero-dimensional ndarray to a one-dimensional ndarray view containing a single element.
+*
+* @private
+* @param {ndarrayLike} x - input ndarray
+* @returns {ndarrayLike} broadcasted ndarray view
+*/
+function broadcast( x ) {
+	// NOTE: the following properties must be set in the exact same order as in `x` in order to ensure that the returned object has the same hidden shape as the input ndarray-like object...
+	return {
+		'dtype': x.dtype,
+		'data': x.data,
+		'shape': [ 1 ],
+		'strides': [ 0 ],
+		'offset': x.offset,
+		'order': x.order
+	};
+}
+
+/**
+* Returns a function which returns an ndarray view in which the singleton dimensions are removed from an input ndarray having only a single non-singleton dimension.
+*
+* @private
+* @param {ndarrayLike} arr - original ndarray
+* @param {NonNegativeInteger} index - index of the non-singleton dimension
+* @returns {Function} function for returning an ndarray view
+*/
+function squeeze( arr, index ) {
+	var sh = [ arr.shape[ index ] ];
+	var sx = [ arr.strides[ index ] ];
+	return reshape;
+
+	/**
+	* Returns an ndarray view in which the singleton dimensions are removed from an input ndarray having only a single non-singleton dimension.
+	*
+	* @private
+	* @param {ndarrayLike} x - input ndarray
+	* @returns {ndarrayLike} a squeezed ndarray view
+	*/
+	function reshape( x ) {
+		// NOTE: the following properties must be set in the exact same order as in `arr` in order to ensure that the returned object has the same hidden shape as the input ndarray-like object...
+		return {
+			'dtype': x.dtype,
+			'data': x.data,
+			'shape': sh,
+			'strides': sx,
+			'offset': x.offset,
+			'order': x.order
+		};
+	}
+}
+
+/**
+* Returns a function which returns a one-dimensional ndarray view of a contiguous input ndarray having more than one dimension.
+*
+* @private
+* @param {NonNegativeInteger} len - number of elements in an ndarray
+* @param {integer} iox - iteration order
+* @returns {Function} function for returning a one-dimensional ndarray view
+*/
+function contiguous( len, iox ) {
+	var xmmv;
+	var ind;
+	var sh;
+	var sx;
+
+	// Resolve the index of the min/max view buffer element which is the first indexed element...
+	if ( iox === 1 ) {
+		ind = 0;
+	} else {
+		ind = 1;
+	}
+	// Initialize an array for storing the min/max view buffer elements:
+	xmmv = [ 0, 0 ]; // [ min, max ]
+
+	// Initialize the output one-dimensional view's shape and strides:
+	sh = [ len ];
+	sx = [ iox ];
+
+	return reshape;
+
+	/**
+	* Returns a one-dimensional ndarray view of a contiguous input ndarray having more than one dimension.
+	*
+	* @private
+	* @param {ndarrayLike} x - input ndarray
+	* @returns {ndarrayLike} a one-dimensional ndarray view
+	*/
+	function reshape( x ) {
+		// Resolve the minimum and maximum linear indices in the underlying data buffer which are accessible to the input ndarray view:
+		minmaxViewBufferIndex( x.shape, x.strides, x.offset, xmmv );
+
+		// NOTE: the following properties must be set in the exact same order as in `x` in order to ensure that the returned object has the same hidden shape as the input ndarray-like object...
+		return {
+			'dtype': x.dtype,
+			'data': x.data,
+			'shape': sh,
+			'strides': sx,
+			'offset': xmmv[ ind ], // the index of the first indexed element
+			'order': x.order
+		};
+	}
+}
+
+/**
+* Returns a function which copies an input ndarray to a contiguous ndarray workspace.
+*
+* @private
+* @param {NonNegativeInteger} len - number of elements in an ndarray
+* @param {ndarrayLike} workspace - ndarray workspace
+* @returns {Function} function which copies an input ndarray to a contiguous ndarray workspace
+*/
+function copy( len, workspace ) {
+	// NOTE: the following properties must be set in the exact same order as in the input ndarray-like object in order to ensure that the returned object has the same hidden shape...
+	var view = {
+		'dtype': workspace.dtype,
+		'data': workspace.data,
+		'shape': [ len ],
+		'strides': [ 1 ],
+		'offset': workspace.offset,
+		'order': workspace.order
+	};
+	return reshape;
+
+	/**
+	* Copies an input ndarray to a contiguous ndarray workspace and returns a one-dimensional workspace view.
+	*
+	* @private
+	* @param {ndarrayLike} x - input ndarray
+	* @returns {ndarrayLike} one-dimensional workspace view
+	*/
+	function reshape( x ) {
+		assign( [ x, workspace ] );
+		return view;
+	}
+}
+
+
+// MAIN //
+
+/**
+* Returns a function for reshaping input ndarrays which have the same data type, shape, and strides as a provided ndarray.
+*
+* @private
+* @param {ndarrayLike} x - input ndarray
+* @param {*} x.dtype - input ndarray data type
+* @param {Collection} x.data - input ndarray data buffer
+* @param {NonNegativeIntegerArray} x.shape - input ndarray shape
+* @param {IntegerArray} x.strides - input ndarray strides
+* @param {NonNegativeInteger} x.offset - input ndarray index offset
+* @param {string} x.order - input ndarray memory layout
+* @returns {Function} function implementing a reshape strategy
+*/
+function strategy( x ) {
+	var ndims;
+	var xmmv;
+	var len;
+	var iox;
+	var sh;
+	var ns;
+	var i;
+
+	// Resolve the number of array dimensions:
+	sh = x.shape;
+	ndims = sh.length;
+
+	// Check whether the ndarray is zero-dimensional...
+	if ( ndims === 0 ) {
+		return broadcast;
+	}
+	// Check whether the ndarray is already one-dimensional...
+	if ( ndims === 1 ) {
+		return identity;
+	}
+	// Determine the number of singleton dimensions...
+	len = 1; // number of elements
+	ns = 0;  // number of singleton dimensions
+	for ( i = 0; i < ndims; i++ ) {
+		// Check whether the current dimension is a singleton dimension...
+		if ( sh[ i ] === 1 ) {
+			ns += 1;
+		}
+		len *= sh[ i ];
+	}
+	// Determine whether the ndarray has only **one** non-singleton dimension (e.g., ndims=4, shape=[10,1,1,1]) so that we can simply create an ndarray view without the singleton dimensions...
+	if ( ns === ndims-1 ) {
+		// Get the index of the non-singleton dimension...
+		for ( i = 0; i < ndims; i++ ) {
+			if ( sh[ i ] !== 1 ) {
+				break;
+			}
+		}
+		return squeeze( x, i );
+	}
+	iox = iterationOrder( x.strides ); // +/-1
+
+	// Determine whether we can avoid copying data...
+	if ( iox !== 0 ) {
+		// Determine the minimum and maximum linear indices which are accessible by the ndarray view:
+		xmmv = minmaxViewBufferIndex( sh, x.strides, x.offset, [ 0, 0 ] );
+
+		// Determine whether we can ignore shape (and strides) and create a new one-dimensional ndarray view...
+		if ( len === ( xmmv[1]-xmmv[0]+1 ) ) {
+			return contiguous( len, iox );
+		}
+		// The ndarray is non-contiguous, so we cannot directly interpret as a one-dimensional ndarray...
+
+		// Fall-through to copying to a workspace ndarray...
+	}
+	// At this point, we're dealing with a non-contiguous multi-dimensional ndarray, so we need to copy to a contiguous workspace:
+	return copy( len, ndarraylike2object( emptyLike( ndarraylike2ndarray( x ) ) ) ); // eslint-disable-line max-len
+}
+
+
+// EXPORTS //
+
+module.exports = strategy;