From fc042e3c40a97596e9e414e5868ba5f878d68771 Mon Sep 17 00:00:00 2001 From: gururaj1512 Date: Sun, 24 Aug 2025 14:01:50 +0530 Subject: [PATCH] feat: add `ndarray/base/binary-reduce-strided1d-dispatch-factory` --- .../README.md | 331 ++++++++++++ .../benchmark/benchmark.assign.js | 127 +++++ .../benchmark/benchmark.js | 63 +++ .../benchmark/benchmark.length.js | 123 +++++ .../docs/repl.txt | 168 ++++++ .../docs/types/index.d.ts | 298 +++++++++++ .../docs/types/test.ts | 506 ++++++++++++++++++ .../examples/index.js | 81 +++ .../lib/index.js | 102 ++++ .../lib/main.js | 183 +++++++ .../package.json | 65 +++ .../test/test.js | 35 ++ 12 files changed, 2082 insertions(+) create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/README.md create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.assign.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.length.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/repl.txt create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/index.d.ts create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/test.ts create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/examples/index.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/index.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/main.js create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/package.json create mode 100644 lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/test/test.js diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/README.md b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/README.md new file mode 100644 index 000000000000..1489f7c3cc98 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/README.md @@ -0,0 +1,331 @@ + + +# binaryStrided1dDispatchFactory + +> Create a function for performing binary reduction on two input ndarrays. + +
+ +## Usage + + + +```javascript +var binaryStrided1dDispatchFactory = require( '@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory' ); +``` + +#### binaryStrided1dDispatchFactory( table, idtypes, odtypes, policies ) + +Returns a function for performing binary reduction on two input ndarrays. + + + +```javascript +var base = require( '@stdlib/blas/base/ndarray/gdot' ); + +var table = { + 'default': base +}; + +var dtypes = [ 'float64', 'float32', 'generic' ]; +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +var binary = binaryStrided1dDispatchFactory( table, [ dtypes, dtypes ], dtypes, policies ); +``` + +The function has the following parameters: + +- **table**: strided binary reduction function dispatch table. Must have the following properties: + + - **default**: default strided binary reduction function which should be invoked when provided ndarrays have data types which do not have a corresponding specialized implementation. + + A dispatch table may have the following additional properties: + + - **types**: one-dimensional list of ndarray data types describing specialized input ndarray argument signatures. Only the input ndarray argument data types should be specified. Output ndarray and additional input ndarray argument data types should be omitted and are not considered during dispatch. The length of `types` must equal twice the number of strided functions specified by `fcns` (i.e., for every pair of input ndarray data types, there must be a corresponding strided binary reduction function in `fcns`). + - **fcns**: list of strided binary reduction functions which are specific to specialized input ndarray argument signatures. + +- **idtypes**: list containing lists of supported input data types for each input ndarray argument. + +- **odtypes**: list of supported output data types. + +- **policies**: dispatch policies. Must have the following properties: + + - **output**: output data type [policy][@stdlib/ndarray/output-dtype-policies]. + - **casting**: input ndarray casting [policy][@stdlib/ndarray/input-casting-policies]. + +#### binary( x, y\[, ...args]\[, options] ) + +Performs a binary reduction on two provided input ndarrays. + + + +```javascript +var ndarray = require( '@stdlib/ndarray/base/ctor' ); +var base = require( '@stdlib/blas/base/ndarray/gdot' ); + +var table = { + 'default': base +}; + +var dtypes = [ 'float64', 'float32', 'generic' ]; +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +var binary = binaryStrided1dDispatchFactory( table, [ dtypes, dtypes ], dtypes, policies ); + +var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + +var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + +var z = binary( x, y ); +// returns + +var v = z.get(); +// returns -5.0 +``` + +The function has the following parameters: + +- **x**: first input ndarray. +- **y**: second input ndarray. +- **...args**: additional input ndarray arguments (_optional_). +- **options**: function options (_optional_). + +The function accepts the following options: + +- **dims**: list of dimensions over which to perform a binary reduction. +- **dtype**: output ndarray data type. Setting this option, overrides the output data type policy. +- **keepdims**: boolean indicating whether the reduced dimensions should be included in the returned ndarray as singleton dimensions. Default: `false`. + +By default, the function returns an ndarray having a data type determined by the output data type policy. To override the default behavior, set the `dtype` option. + + + +```javascript +var ndarray = require( '@stdlib/ndarray/base/ctor' ); +var base = require( '@stdlib/blas/base/ndarray/gdot' ); +var getDType = require( '@stdlib/ndarray/dtype' ); + +var table = { + 'default': base +}; + +var dtypes = [ 'float64', 'float32', 'generic' ]; +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +var binary = binaryStrided1dDispatchFactory( table, [ dtypes, dtypes ], dtypes, policies ); + +var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + +var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + +var z = binary( x, y, { + 'dtype': 'float64' +}); +// returns + +var dt = getDType( z ); +// returns 'float64' +``` + +#### binary.assign( x, y\[, ...args], out\[, options] ) + +Performs a binary reduction on two provided input ndarrays and assigns results to a provided output ndarray. + + + +```javascript +var base = require( '@stdlib/blas/base/ndarray/gdot' ); +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var ndarray = require( '@stdlib/ndarray/base/ctor' ); + +var idt = dtypes( 'real_and_generic' ); +var odt = idt; +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +var table = { + 'default': base +}; +var binary = binaryStrided1dDispatchFactory( table, [ idt, idt ], odt, policies ); + +var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + +var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + +var zbuf = [ 0.0 ]; +var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' ); + +var out = binary.assign( x, y, z ); +// returns + +var v = out.get(); +// returns -5.0 + +var bool = ( out === z ); +// returns true +``` + +The method has the following parameters: + +- **x**: first input ndarray. +- **y**: second input ndarray. +- **args**: additional input ndarray arguments (_optional_). +- **out**: output ndarray. +- **options**: function options (_optional_). + +The method accepts the following options: + +- **dims**: list of dimensions over which to perform a binary reduction. + +
+ + + +
+ +## Notes + +- A strided binary reduction function should have the following signature: + + ```text + f( arrays ) + ``` + + where + + - **arrays**: array containing two input ndarrays, followed by any additional ndarray arguments. + +- The output data type policy only applies to the function returned by the main function. For the `assign` method, the output ndarray is allowed to have any supported output data type. + +
+ + + +
+ +## Examples + + + + + +```javascript +var ddot = require( '@stdlib/blas/base/ndarray/ddot' ); +var sdot = require( '@stdlib/blas/base/ndarray/sdot' ); +var base = require( '@stdlib/blas/base/ndarray/gdot' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var dtype = require( '@stdlib/ndarray/dtype' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); +var ndarray = require( '@stdlib/ndarray/ctor' ); +var binaryStrided1dDispatchFactory = require( '@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory' ); + +// Define the supported input and output data types: +var idt = dtypes( 'real_and_generic' ); +var odt = dtypes( 'real_and_generic' ); + +// Define dispatch policies: +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +// Define a dispatch table: +var table = { + 'types': [ + 'float64', 'float64', // first and second input + 'float32', 'float32' // first and second input + ], + 'fcns': [ + ddot, + sdot + ], + 'default': base +}; + +// Create an interface for performing a binary reduction: +var dot = binaryStrided1dDispatchFactory( table, [ idt, idt ], odt, policies ); + +// Generate arrays of random numbers: +var xbuf = uniform( 100, -1.0, 1.0, { + 'dtype': 'generic' +}); +var ybuf = uniform( 100, -1.0, 1.0, { + 'dtype': 'generic' +}); + +// Wrap in ndarrays: +var x = new ndarray( 'generic', xbuf, [ 10, 10 ], [ 10, 1 ], 0, 'row-major' ); +var y = new ndarray( 'generic', ybuf, [ 10, 10 ], [ 10, 1 ], 0, 'row-major' ); + +// Perform a binary reduction: +var z = dot( x, y, { + 'dims': [ 0 ] +}); + +// Resolve the output array data type: +var dt = dtype( z ); +console.log( dt ); + +// Print the results: +console.log( ndarray2array( z ) ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/output-dtype-policies + +[@stdlib/ndarray/input-casting-policies]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/input-casting-policies + +
+ + diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.assign.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.assign.js new file mode 100644 index 000000000000..0ea354ecbd81 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.assign.js @@ -0,0 +1,127 @@ +/** +* @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 bench = require( '@stdlib/bench' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var dtypes = require( '@stdlib/array/dtypes' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var zeros = require( '@stdlib/array/zeros' ); +var ndarray = require( '@stdlib/ndarray/base/ctor' ); +var gdot = require( '@stdlib/blas/base/ndarray/gdot' ); +var pkg = require( './../package.json' ).name; +var factory = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var policies; + var binary; + var table; + var out; + var dt; + var x; + var y; + + table = { + 'default': gdot + }; + dt = dtypes( 'real_floating_point' ); + policies = { + 'output': 'same', + 'casting': 'none' + }; + binary = factory( table, [ dt, dt ], dt, policies ); + + x = uniform( len, -50.0, 50.0, { + 'dtype': 'float64' + }); + y = uniform( len, -50.0, 50.0, { + 'dtype': 'float64' + }); + x = new ndarray( 'float64', x, [ len ], [ 1 ], 0, 'row-major' ); + y = new ndarray( 'float64', y, [ len ], [ 1 ], 0, 'row-major' ); + + out = new ndarray( 'float64', zeros( 1, 'float64' ), [], [ 0 ], 0, 'row-major' ); + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var o; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + o = binary.assign( x, y, out ); + if ( typeof o !== 'object' ) { + b.fail( 'should return an ndarray' ); + } + } + b.toc(); + if ( isnan( o.get() ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':assign:len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.js new file mode 100644 index 000000000000..f7023bba4789 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.js @@ -0,0 +1,63 @@ +/** +* @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 bench = require( '@stdlib/bench' ); +var gdot = require( '@stdlib/blas/base/ndarray/gdot' ); +var pkg = require( './../package.json' ).name; +var factory = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::factory', function benchmark( b ) { + var policies; + var dtypes; + var table; + var v; + var i; + + table = { + 'default': gdot + }; + dtypes = [ + 'float64', + 'float32' + ]; + policies = { + 'output': 'same', + 'casting': 'none' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = factory( table, [ dtypes, dtypes ], dtypes, policies ); + if ( typeof v !== 'function' ) { + b.fail( 'should return a function' ); + } + } + b.toc(); + if ( typeof v !== 'function' ) { + b.fail( 'should return a function' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.length.js new file mode 100644 index 000000000000..70ff9a99b1f2 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/benchmark/benchmark.length.js @@ -0,0 +1,123 @@ +/** +* @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 bench = require( '@stdlib/bench' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var ndarray = require( '@stdlib/ndarray/base/ctor' ); +var gdot = require( '@stdlib/blas/base/ndarray/gdot' ); +var pkg = require( './../package.json' ).name; +var factory = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var policies; + var binary; + var table; + var dt; + var x; + var y; + + table = { + 'default': gdot + }; + dt = dtypes( 'real_floating_point' ); + policies = { + 'output': 'same', + 'casting': 'none' + }; + binary = factory( table, [ dt, dt ], dt, policies ); + + x = uniform( len, -50.0, 50.0, { + 'dtype': 'float64' + }); + y = uniform( len, -50.0, 50.0, { + 'dtype': 'float64' + }); + x = new ndarray( 'float64', x, [ len ], [ 1 ], 0, 'row-major' ); + y = new ndarray( 'float64', y, [ len ], [ 1 ], 0, 'row-major' ); + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var o; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + o = binary( x, y ); + if ( typeof o !== 'object' ) { + b.fail( 'should return an ndarray' ); + } + } + b.toc(); + if ( isnan( o.get() ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+'::apply:len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/repl.txt new file mode 100644 index 000000000000..574c0cd0ff3a --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/repl.txt @@ -0,0 +1,168 @@ + +{{alias}}( table, idtypes, odtypes, policies ) + Returns function for performing binary reduction on two input ndarrays. + + Parameters + ---------- + table: Object + Dispatch table containing strided binary reduction functions. The table + object must have the following property: + + - default: default strided binary reduction function to invoke when + provided ndarrays have data types which do not have a corresponding + specialized implementation. + + The table may having the following additional properties: + + - types: one-dimensional list of ndarray data types describing + specialized input ndarray argument signatures. + - fcns: list of strided binary reduction functions which are specific + to specialized input ndarray argument signatures. + + A strided binary reduction function should have the following signature: + + f( arrays ) + + where + + - arrays: array containing two input ndarrays, followed by any + additional ndarray arguments. + + idtypes: Array> + List containing lists of supported input array data types for each + input ndarray argument. + + odtypes: Array + List of supported output array data types. + + policies: Object + Dispatch policies. Must have the following properties: + + - output: output data type policy. + - casting: input ndarray casting policy. + + Returns + ------- + fcn: Function + Function for performing binary reduction on ndarrays. + + Examples + -------- + > var dt = [ 'float64', 'float32', 'generic' ]; + > var p = { 'output': 'same', 'casting': 'none' }; + > var t = { 'default': {{alias:@stdlib/blas/base/ndarray/gdot}} }; + > var f = {{alias}}( t, [ dt, dt ], dt, p ); + + +fcn( x, y[, ...args][, options] ) + Performs a binary reduction on two provided input ndarrays. + + Parameters + ---------- + x: ndarray + First input array. + + y: ndarray + Second input array. + + args: ...ndarray (optional) + Additional ndarray arguments. + + options: Object (optional) + Function options. + + options.dtype: string (optional) + Output array data type. Setting this option overrides the output data + type policy. + + options.dims: Array (optional) + List of dimensions over which to perform a binary reduction. If not + provided, the function performs a binary reduction over all elements in + the two provided input ndarrays. + + options.keepdims: boolean (optional) + Boolean indicating whether the reduced dimensions should be included in + the returned ndarray as singleton dimensions. Default: false. + + Returns + ------- + out: ndarray + Output array. + + Examples + -------- + > var dts = [ 'float64', 'float32', 'generic' ]; + > var p = { 'output': 'same', 'casting': 'none' }; + > var t = { 'default': {{alias:@stdlib/blas/base/ndarray/gdot}} }; + > var f = {{alias}}( t, [ dts, dts ], dts, p ); + > var xbuf = [ -1.0, 2.0, -3.0, -4.0 ]; + > var ybuf = [ -1.0, 2.0, -3.0, -4.0 ]; + > var dt = 'generic'; + > var sh = [ buf.length ]; + > var sx = [ 1 ]; + > var oo = 0; + > var ord = 'row-major'; + > var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, oo, ord ); + > var y = new {{alias:@stdlib/ndarray/ctor}}( dt, ybuf, sh, sx, oo, ord ); + > var z = f( x, y ); + > var v = z.get() + 30.0 + + +fcn.assign( x, y[, ...args], out[, options] ) + Performs a binary reduction on two provided input ndarrays and assigns + results to a provided output ndarray. + + Parameters + ---------- + x: ndarray + First input array. + + y: ndarray + Second input array. + + args: ...ndarray (optional) + Additional ndarray arguments. + + out: ndarray + Output array. + + options: Object (optional) + Function options. + + options.dims: Array (optional) + List of dimensions over which to perform a binary reduction. If not + provided, the function performs a binary reduction over all elements + in the two provided input ndarrays. + + Returns + ------- + out: ndarray + Output array. + + Examples + -------- + > var dts = [ 'float64', 'float32', 'generic' ]; + > var p = { 'output': 'same', 'casting': 'none' }; + > var t = { 'default': {{alias:@stdlib/blas/base/ndarray/gdot}} }; + > var f = {{alias}}( t, [ dts, dts ], dts, p ); + > var xbuf = [ -1.0, 2.0, -3.0, -4.0 ]; + > var ybuf = [ -1.0, 2.0, -3.0, -4.0 ]; + > var dt = 'generic'; + > var sh = [ buf.length ]; + > var sx = [ 1 ]; + > var oo = 0; + > var ord = 'row-major'; + > var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, oo, ord ); + > var y = new {{alias:@stdlib/ndarray/ctor}}( dt, ybuf, sh, sx, oo, ord ); + > var out = {{alias:@stdlib/ndarray/zeros}}( [], { 'dtype': dt } ); + > var z = f.assign( x, y, out ) + + > var bool = ( out === z ) + true + > var v = out.get() + 30.0 + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/index.d.ts new file mode 100644 index 000000000000..25d6616e4450 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/index.d.ts @@ -0,0 +1,298 @@ +/* +* @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. +*/ + +// TypeScript Version: 4.1 + +/// + +import { ArrayLike } from '@stdlib/types/array'; +import { OutputPolicy, InputCastingPolicy, DataType, typedndarray } from '@stdlib/types/ndarray'; + +/** +* Input array. +*/ +type InputArray = typedndarray; + +/** +* Output array. +*/ +type OutputArray = typedndarray; + +/** +* Interface defining "base" options. +*/ +interface BaseOptions { + /** + * List of dimensions over which to perform a binary reduction. + */ + dims?: ArrayLike; +} + +/** +* Interface defining options. +*/ +interface Options extends BaseOptions { + /** + * Output array data type. + */ + dtype?: DataType; + + /** + * Boolean indicating whether the reduced dimensions should be included in the returned array as singleton dimensions. Default: `false`. + */ + keepdims?: boolean; +} + +/** +* Strided binary reduction function. +* +* @param arrays - input ndarrays +* @param options - function options +* @returns result +*/ +type Binary = ( arrays: [ typedndarray, typedndarray ], options?: unknown ) => U; + +/** +* Strided binary reduction function. +* +* @param arrays - input ndarrays +* @param options - function options +* @returns result +*/ +type BinaryWithAdditionalArrays = ( arrays: [ typedndarray, typedndarray, ...Array> ], options?: unknown ) => U; + +/** +* Base dispatch table. +*/ +interface BaseDispatchTable { + /** + * Default strided reduction function. + */ + default: Binary | BinaryWithAdditionalArrays; +} + +/** +* Dispatch table. +*/ +interface DispatchTable extends BaseDispatchTable { + /** + * One-dimensional list of ndarray data types describing specialized input ndarray argument signatures. + */ + types: ArrayLike; + + /** + * List of strided binary reduction functions which are specific to specialized input ndarray argument signatures. + */ + fcns: ArrayLike | BinaryWithAdditionalArrays>; +} + +/** +* Dispatch policies. +*/ +interface Policies { + /** + * Output data type policy. + */ + output: OutputPolicy; + + /** + * Input ndarray casting policy. + */ + casting: InputCastingPolicy; +} + +/** +* Interface for performing a binary reduction on two input ndarrays. +*/ +interface BinaryFunction { + /** + * Performs a binary reduction on two provided input ndarrays. + * + * @param x - input ndarray + * @param y - second input ndarray + * @param args - function options and additional array arguments + * @returns output ndarray + * + * @example + * var base = require( '@stdlib/blas/base/ndarray/gdot' ); + * var dtypes = require( '@stdlib/ndarray/dtypes' ); + * var ndarray = require( '@stdlib/ndarray/base/ctor' ); + * + * var idt = dtypes( 'real_and_generic' ); + * var odt = idt; + * var policies = { + * 'output': 'same', + * 'casting': 'none' + * }; + * + * var table = { + * 'default': base + * }; + * var dot = factory( table, [ idt, idt ], odt, policies ); + * + * var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; + * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + * + * var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; + * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + * + * var z = dot( x, y ); + * // returns + * + * var v = z.get(); + * // returns -5.0 + */ + ( x: InputArray, y: InputArray, ...args: Array | Options> ): OutputArray; // NOTE: we lose type specificity here, but retaining specificity would likely be difficult and/or tedious to completely enumerate, as the output ndarray data type is dependent on how `x` interacts with output data type policy and whether that policy has been overridden by `options.dtype`. In principle, as well, based on the policy, it is possible to know more exactly which `InputArray` types are actually allowed. + + /** + * Performs a binary reduction on two provided input ndarrays and assigns results to a provided output ndarray. + * + * @param x - first input ndarray + * @param y - second input ndarray + * @param out - output ndarray + * @param options - function options + * @returns output ndarray + * + * @example + * var base = require( '@stdlib/blas/base/ndarray/gdot' ); + * var dtypes = require( '@stdlib/ndarray/dtypes' ); + * var ndarray = require( '@stdlib/ndarray/base/ctor' ); + * + * var idt = dtypes( 'real_and_generic' ); + * var odt = idt; + * var policies = { + * 'output': 'same', + * 'casting': 'none' + * }; + * + * var table = { + * 'default': base + * }; + * var dot = factory( table, [ idt, idt ], odt, policies ); + * + * var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; + * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + * + * var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; + * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + * + * var zbuf = [ 0.0 ]; + * var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' ); + * + * var out = dot.assign( x, y, z ); + * // returns + * + * var v = out.get(); + * // returns -5.0 + * + * var bool = ( out === z ); + * // returns true + */ + assign = OutputArray>( x: InputArray, y: InputArray, out: V, options?: BaseOptions ): V; + + /** + * Performs a binary reduction on two provided input ndarrays and assigns results to a provided output ndarray. + * + * @param x - first input ndarray + * @param y - second input ndarray + * @param z - additional ndarray argument + * @param args - output ndarray, additional array arguments, and function options + * @returns output ndarray + * + * @example + * var base = require( '@stdlib/blas/base/ndarray/gdot' ); + * var dtypes = require( '@stdlib/ndarray/dtypes' ); + * var ndarray = require( '@stdlib/ndarray/base/ctor' ); + * + * var idt = dtypes( 'real_and_generic' ); + * var odt = idt; + * var policies = { + * 'output': 'same', + * 'casting': 'none' + * }; + * + * var table = { + * 'default': base + * }; + * var dot = factory( table, [ idt, idt ], odt, policies ); + * + * var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; + * var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); + * + * var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; + * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); + * + * var zbuf = [ 0.0 ]; + * var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' ); + * + * var out = dot.assign( x, y, z ); + * // returns + * + * var v = out.get(); + * // returns -5.0 + * + * var bool = ( out === z ); + * // returns true + */ + assign = OutputArray>( x: InputArray, y: InputArray, z: InputArray | V, ...args: Array | V | BaseOptions> ): V; +} + +/** +* Creates a function for performing a binary reduction on two input ndarrays. +* +* @param table - dispatch table +* @param idtypes - list containing lists of supported input data types for each ndarray argument +* @param odtypes - list of supported output data types +* @param policies - dispatch policies +* @returns function for applying a binary function +* +* @example +* var base = require( '@stdlib/blas/base/ndarray/gdot' ); +* var dtypes = require( '@stdlib/ndarray/dtypes' ); +* var ndarray = require( '@stdlib/ndarray/base/ctor' ); +* +* var idt = dtypes( 'real_and_generic' ); +* var odt = idt; +* var policies = { +* 'output': 'same', +* 'casting': 'none' +* }; +* +* var table = { +* 'default': base +* }; +* var dot = factory( table, [ idt, idt ], odt, policies ); +* +* var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +* var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); +* +* var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +* var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); +* +* var z = dot( x, y ); +* // returns +* +* var v = z.get(); +* // returns -5.0 +*/ +declare function factory( table: DispatchTable | BaseDispatchTable, idtypes: ArrayLike>, odtypes: ArrayLike, policies: Policies ): BinaryFunction; + + +// EXPORTS // + +export = factory; diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/test.ts new file mode 100644 index 000000000000..3ce4a9e96775 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/docs/types/test.ts @@ -0,0 +1,506 @@ +/* +* @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. +*/ + +/* eslint-disable @typescript-eslint/no-unused-expressions, space-in-parens */ + +/// + +import { DataType, OutputPolicy, InputCastingPolicy } from '@stdlib/types/ndarray'; +import gdot = require( '@stdlib/blas/base/ndarray/gdot' ); +import zeros = require( '@stdlib/ndarray/zeros' ); +import factory = require( './index' ); + + +// TESTS // + +// The function returns a function... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + factory( table, [ dtypes, dtypes ], dtypes, policies ); // $ExpectType BinaryFunction +} + +// The compiler throws an error if the function is provided a first argument which is not a dispatch table... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + factory( '5', [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( 5, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( true, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( false, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( null, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( void 0, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( 'abc', [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( {}, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError + factory( ( x: number, y: number ): number => x + y, [ dtypes, dtypes ], dtypes, policies ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a list of data type lists... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + factory( table, '5', dtypes, policies ); // $ExpectError + factory( table, 5, dtypes, policies ); // $ExpectError + factory( table, true, dtypes, policies ); // $ExpectError + factory( table, false, dtypes, policies ); // $ExpectError + factory( table, null, dtypes, policies ); // $ExpectError + factory( table, void 0, dtypes, policies ); // $ExpectError + factory( table, 'abc', dtypes, policies ); // $ExpectError + factory( table, {}, dtypes, policies ); // $ExpectError + factory( table, ( x: number ): number => x, dtypes, policies ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a list of data types... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + factory( table, [ dtypes, dtypes ], '5', policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], 5, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], true, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], false, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], null, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], void 0, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], 'abc', policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], {}, policies ); // $ExpectError + factory( table, [ dtypes, dtypes ], ( x: number ): number => x, policies ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a valid policies object... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + + factory( table, [ dtypes, dtypes ], dtypes, '5' ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, 5 ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, true ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, false ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, null ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, void 0 ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, 'abc' ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, {} ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + factory(); // $ExpectError + factory( abs ); // $ExpectError + factory( table, [ dtypes, dtypes ] ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes ); // $ExpectError + factory( table, [ dtypes, dtypes ], dtypes, policies, {} ); // $ExpectError +} + +// The function returns a function which returns an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, x ); // $ExpectType OutputArray + f( x, x, {} ); // $ExpectType OutputArray +} + +// The compiler throws an error if the returned function is provided a first argument which is not an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( '5', x ); // $ExpectError + f( 5, x ); // $ExpectError + f( true, x ); // $ExpectError + f( false, x ); // $ExpectError + f( null, x ); // $ExpectError + f( void 0, x ); // $ExpectError + f( {}, x ); // $ExpectError + f( ( x: number ): number => x, x ); // $ExpectError + + f( '5', x, {} ); // $ExpectError + f( 5, x, {} ); // $ExpectError + f( true, x, {} ); // $ExpectError + f( false, x, {} ); // $ExpectError + f( null, x, {} ); // $ExpectError + f( void 0, x, {} ); // $ExpectError + f( {}, x, {} ); // $ExpectError + f( ( x: number ): number => x, x, {} ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided a second argument which is not an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, '5' ); // $ExpectError + f( x, 5 ); // $ExpectError + f( x, true ); // $ExpectError + f( x, false ); // $ExpectError + f( x, null ); // $ExpectError + f( x, void 0 ); // $ExpectError + f( x, {} ); // $ExpectError + f( x, ( x: number ): number => x ); // $ExpectError + + f( x, '5', {} ); // $ExpectError + f( x, 5, {} ); // $ExpectError + f( x, true, {} ); // $ExpectError + f( x, false, {} ); // $ExpectError + f( x, null, {} ); // $ExpectError + f( x, void 0, {} ); // $ExpectError + f( x, {}, {} ); // $ExpectError + f( x, ( x: number ): number => x, {} ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided an invalid third argument... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, x, '5' ); // $ExpectError + f( x, x, true ); // $ExpectError + f( x, x, false ); // $ExpectError + f( x, x, null ); // $ExpectError + f( x, x, [] ); // $ExpectError + f( x, x, ( x: number ): number => x ); // $ExpectError + + f( x, x, '5', {} ); // $ExpectError + f( x, x, true, {} ); // $ExpectError + f( x, x, false, {} ); // $ExpectError + f( x, x, null, {} ); // $ExpectError + f( x, x, [], {} ); // $ExpectError + f( x, x, ( x: number ): number => x, {} ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided an invalid `dtype` option... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, x, { 'dtype': '5' } ); // $ExpectError + f( x, x, { 'dtype': 5 } ); // $ExpectError + f( x, x, { 'dtype': true } ); // $ExpectError + f( x, x, { 'dtype': false } ); // $ExpectError + f( x, x, { 'dtype': null } ); // $ExpectError + f( x, x, { 'dtype': [] } ); // $ExpectError + f( x, x, { 'dtype': {} } ); // $ExpectError + f( x, x, { 'dtype': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided an invalid `keepdims` option... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, x, { 'keepdims': '5' } ); // $ExpectError + f( x, x, { 'keepdims': 5 } ); // $ExpectError + f( x, x, { 'keepdims': null } ); // $ExpectError + f( x, x, { 'keepdims': [] } ); // $ExpectError + f( x, x, { 'keepdims': {} } ); // $ExpectError + f( x, x, { 'keepdims': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided an invalid `dims` option... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f( x, x, { 'dims': '5' } ); // $ExpectError + f( x, x, { 'dims': 5 } ); // $ExpectError + f( x, x, { 'dims': true } ); // $ExpectError + f( x, x, { 'dims': false } ); // $ExpectError + f( x, x, { 'dims': null } ); // $ExpectError + f( x, x, { 'dims': {} } ); // $ExpectError + f( x, x, { 'dims': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the returned function is provided an unsupported number of arguments... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f(); // $ExpectError +} + +// The function returns a function having an `assign` method which returns an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign( x, x, x ); // $ExpectType float64ndarray +} + +// The compiler throws an error if the `assign` method is provided a first argument which is not an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign( '5', x, x ); // $ExpectError + f.assign( 5, x, x ); // $ExpectError + f.assign( true, x, x ); // $ExpectError + f.assign( false, x, x ); // $ExpectError + f.assign( null, x, x ); // $ExpectError + f.assign( void 0, x, x ); // $ExpectError + f.assign( {}, x, x ); // $ExpectError + f.assign( ( x: number ): number => x, x, x ); // $ExpectError + + f.assign( '5', x, x, {} ); // $ExpectError + f.assign( 5, x, x, {} ); // $ExpectError + f.assign( true, x, x, {} ); // $ExpectError + f.assign( false, x, x, {} ); // $ExpectError + f.assign( null, x, x, {} ); // $ExpectError + f.assign( void 0, x, x, {} ); // $ExpectError + f.assign( {}, x, x, {} ); // $ExpectError + f.assign( ( x: number ): number => x, x, x, {} ); // $ExpectError +} + +// The compiler throws an error if the `assign` method is provided a second argument which is not an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign( x, '5', x ); // $ExpectError + f.assign( x, 5, x ); // $ExpectError + f.assign( x, true, x ); // $ExpectError + f.assign( x, false, x ); // $ExpectError + f.assign( x, null, x ); // $ExpectError + f.assign( x, void 0, x ); // $ExpectError + f.assign( x, ( x: number ): number => x, x ); // $ExpectError + + f.assign( x, '5', x, {} ); // $ExpectError + f.assign( x, 5, x, {} ); // $ExpectError + f.assign( x, true, x, {} ); // $ExpectError + f.assign( x, false, x, {} ); // $ExpectError + f.assign( x, null, x, {} ); // $ExpectError + f.assign( x, void 0, x, {} ); // $ExpectError + f.assign( x, ( x: number ): number => x, x, {} ); // $ExpectError +} + +// The compiler throws an error if the `assign` method is provided a third argument which is not an ndarray... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign( x, x, '5' ); // $ExpectError + f.assign( x, x, 5 ); // $ExpectError + f.assign( x, x, true ); // $ExpectError + f.assign( x, x, false ); // $ExpectError + f.assign( x, x, null ); // $ExpectError + f.assign( x, x, void 0 ); // $ExpectError + f.assign( x, x, ( x: number ): number => x ); // $ExpectError + + f.assign( x, x, '5', {} ); // $ExpectError + f.assign( x, x, 5, {} ); // $ExpectError + f.assign( x, x, true, {} ); // $ExpectError + f.assign( x, x, false, {} ); // $ExpectError + f.assign( x, x, null, {} ); // $ExpectError + f.assign( x, x, void 0, {} ); // $ExpectError + f.assign( x, x, ( x: number ): number => x, {} ); // $ExpectError +} + +// The compiler throws an error if the `assign` method is provided an invalid `dims` option... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign( x, x, x, { 'dims': '5' } ); // $ExpectError + f.assign( x, x, x, { 'dims': 5 } ); // $ExpectError + f.assign( x, x, x, { 'dims': true } ); // $ExpectError + f.assign( x, x, x, { 'dims': false } ); // $ExpectError + f.assign( x, x, x, { 'dims': null } ); // $ExpectError + f.assign( x, x, x, { 'dims': {} } ); // $ExpectError + f.assign( x, x, x, { 'dims': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the `assign` method is provided an unsupported number of arguments... +{ + const dtypes: Array = [ 'float64', 'float32' ]; + const table = { + 'default': gdot + }; + const policies = { + 'output': 'same' as OutputPolicy, + 'casting': 'none' as InputCastingPolicy + }; + const x = zeros( [ 2, 2 ], { + 'dtype': 'float64' + }); + + const f = factory( table, [ dtypes, dtypes ], dtypes, policies ); + f.assign(); // $ExpectError + f.assign( x ); // $ExpectError + f.assign( x, x ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/examples/index.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/examples/index.js new file mode 100644 index 000000000000..031ea47527a8 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/examples/index.js @@ -0,0 +1,81 @@ +/** +* @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. +*/ + +/* eslint-disable array-element-newline, id-length */ + +'use strict'; + +var ddot = require( '@stdlib/blas/base/ndarray/ddot' ); +var sdot = require( '@stdlib/blas/base/ndarray/sdot' ); +var base = require( '@stdlib/blas/base/ndarray/gdot' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var dtype = require( '@stdlib/ndarray/dtype' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); +var ndarray = require( '@stdlib/ndarray/ctor' ); +var binaryStrided1dDispatchFactory = require( './../lib' ); + +// Define the supported input and output data types: +var idt = dtypes( 'real_and_generic' ); +var odt = dtypes( 'real_and_generic' ); + +// Define dispatch policies: +var policies = { + 'output': 'same', + 'casting': 'none' +}; + +// Define a dispatch table: +var table = { + 'types': [ + 'float64', 'float64', // first and second input + 'float32', 'float32' // first and second input + ], + 'fcns': [ + ddot, + sdot + ], + 'default': base +}; + +// Create an interface for performing a binary reduction: +var dot = binaryStrided1dDispatchFactory( table, [ idt, idt ], odt, policies ); + +// Generate arrays of random numbers: +var xbuf = uniform( 100, -1.0, 1.0, { + 'dtype': 'generic' +}); +var ybuf = uniform( 100, -1.0, 1.0, { + 'dtype': 'generic' +}); + +// Wrap in ndarrays: +var x = new ndarray( 'generic', xbuf, [ 10, 10 ], [ 10, 1 ], 0, 'row-major' ); +var y = new ndarray( 'generic', ybuf, [ 10, 10 ], [ 10, 1 ], 0, 'row-major' ); + +// Perform a binary reduction: +var z = dot( x, y, { + 'dims': [ 0 ] +}); + +// Resolve the output array data type: +var dt = dtype( z ); +console.log( dt ); + +// Print the results: +console.log( ndarray2array( z ) ); diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/index.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/index.js new file mode 100644 index 000000000000..02c4f583883c --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/index.js @@ -0,0 +1,102 @@ +/** +* @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'; + +/** +* Create a function for performing binary reduction on two input ndarrays. +* +* @module @stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory +* +* @example +* var base = require( '@stdlib/blas/base/ndarray/gdot' ); +* var dtypes = require( '@stdlib/ndarray/dtypes' ); +* var ndarray = require( '@stdlib/ndarray/base/ctor' ); +* var factory = require( '@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory' ); +* +* var idt = dtypes( 'real_and_generic' ); +* var odt = idt; +* var policies = { +* 'output': 'same', +* 'casting': 'none' +* }; +* +* var table = { +* 'default': base +* }; +* var dot = factory( table, [ idt, idt ], odt, policies ); +* +* var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +* var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); +* +* var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +* var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); +* +* var z = dot( x, y ); +* // returns +* +* var v = z.get(); +* // returns -5.0 +* +* @example +* var base = require( '@stdlib/blas/base/ndarray/gdot' ); +* var dtypes = require( '@stdlib/ndarray/dtypes' ); +* var ndarray = require( '@stdlib/ndarray/base/ctor' ); +* var factory = require( '@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory' ); +* +* var idt = dtypes( 'real_and_generic' ); +* var odt = idt; +* var policies = { +* 'output': 'same', +* 'casting': 'none' +* }; +* +* var table = { +* 'default': base +* }; +* var dot = factory( table, [ idt, idt ], odt, policies ); +* +* var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +* var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); +* +* var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +* var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); +* +* var zbuf = [ 0.0 ]; +* var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' ); +* +* var out = dot.assign( x, y, z ); +* // returns +* +* var v = out.get(); +* // returns -5.0 +* +* var bool = ( out === z ); +* // returns true +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; + +// exports: { "assign": "main.assign" } diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/main.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/main.js new file mode 100644 index 000000000000..a6a5d9ef60c4 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/lib/main.js @@ -0,0 +1,183 @@ +/** +* @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 setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var BinaryStrided1dDispatch = require( '@stdlib/ndarray/base/binary-reduce-strided1d-dispatch' ); + + +// MAIN // + +/** +* Returns a function for performing binary reduction on two input ndarrays. +* +* @param {Object} table - dispatch table +* @param {Function} table.default - default strided binary reduction function +* @param {StringArray} [table.types] - one-dimensional list of ndarray data types describing specialized input ndarray argument signatures +* @param {ArrayLikeObject} [table.fcns] - list of strided binary reduction functions which are specific to specialized input ndarray argument signatures +* @param {ArrayLikeObject} idtypes - list containing lists of supported input data types for each ndarray argument +* @param {StringArray} odtypes - list of supported output data types +* @param {Object} policies - policies +* @param {string} policies.output - output data type policy +* @param {string} policies.casting - input ndarray casting policy +* @throws {TypeError} first argument must be an object having valid properties +* @throws {TypeError} second argument must be an array containing arrays of supported data types +* @throws {TypeError} third argument must be an array of supported data types +* @throws {TypeError} fourth argument must be an object having supported policies +* @throws {Error} first argument must be an object having valid properties +* @returns {Function} function for performing binary reduction on ndarrays +* +* @example +* var base = require( '@stdlib/blas/base/ndarray/gdot' ); +* var dtypes = require( '@stdlib/ndarray/dtypes' ); +* var ndarray = require( '@stdlib/ndarray/base/ctor' ); +* +* var idt = dtypes( 'real_and_generic' ); +* var odt = idt; +* var policies = { +* 'output': 'same', +* 'casting': 'none' +* }; +* +* var table = { +* 'default': base +* }; +* var dot = factory( table, [ idt, idt ], odt, policies ); +* +* var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +* var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); +* +* var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +* var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); +* +* var z = dot( x, y ); +* // returns +* +* var v = z.get(); +* // returns -5.0 +* +* @example +* var base = require( '@stdlib/blas/base/ndarray/gdot' ); +* var dtypes = require( '@stdlib/ndarray/dtypes' ); +* var ndarray = require( '@stdlib/ndarray/base/ctor' ); +* +* var idt = dtypes( 'real_and_generic' ); +* var odt = idt; +* var policies = { +* 'output': 'same', +* 'casting': 'none' +* }; +* +* var table = { +* 'default': base +* }; +* var dot = factory( table, [ idt, idt ], odt, policies ); +* +* var xbuf = [ 4.0, 2.0, -3.0, 5.0, -1.0 ]; +* var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' ); +* +* var ybuf = [ 2.0, 6.0, -1.0, -4.0, 8.0 ]; +* var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' ); +* +* var zbuf = [ 0.0 ]; +* var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' ); +* +* var out = dot.assign( x, y, z ); +* // returns +* +* var v = out.get(); +* // returns -5.0 +* +* var bool = ( out === z ); +* // returns true +*/ +function factory( table, idtypes, odtypes, policies ) { + var f = new BinaryStrided1dDispatch( table, idtypes, odtypes, policies ); + setReadOnly( main, 'assign', assign ); + return main; + + /** + * Performs a binary reduction on two provided input ndarrays. + * + * @private + * @param {ndarrayLike} x - first input ndarray + * @param {ndarrayLike} y - second input ndarray + * @param {...ndarrayLike} [args] - additional ndarray arguments + * @param {Options} [options] - function options + * @param {IntegerArray} [options.dims] - list of dimensions over which to perform a binary reduction + * @param {boolean} [options.keepdims=false] - boolean indicating whether the reduced dimensions should be included in the returned ndarray as singleton dimensions + * @param {string} [options.dtype] - output ndarray data type + * @throws {TypeError} first argument must be an ndarray-like object + * @throws {TypeError} second argument must be an ndarray-like object + * @throws {TypeError} options argument must be an object + * @throws {RangeError} dimension indices must not exceed input ndarray bounds + * @throws {RangeError} number of dimension indices must not exceed the number of input ndarray dimensions + * @throws {Error} must provide valid options + * @returns {ndarray} output ndarray + */ + function main() { + var args; + var i; + + args = []; + for ( i = 0; i < arguments.length; i++ ) { + args.push( arguments[ i ] ); + } + return f.apply.apply( f, args ); + } + + /** + * Performs a binary reduction on two provided input ndarrays and assigns results to a provided output ndarray. + * + * @private + * @param {ndarrayLike} x - first input ndarray + * @param {ndarrayLike} y - second input ndarray + * @param {...ndarrayLike} [args] - additional ndarray arguments + * @param {ndarrayLike} out - output ndarray + * @param {Options} [options] - function options + * @param {IntegerArray} [options.dims] - list of dimensions over which to perform a binary reduction. + * @throws {TypeError} first argument must be an ndarray + * @throws {TypeError} first argument must have a supported data type + * @throws {TypeError} second argument must be an ndarray + * @throws {TypeError} second argument must have a supported data type + * @throws {TypeError} output argument must be an ndarray + * @throws {TypeError} options argument must be an object + * @throws {RangeError} dimension indices must not exceed input ndarray bounds + * @throws {RangeError} number of dimension indices must not exceed the number of input ndarray dimensions + * @throws {Error} must provide valid options + * @returns {ndarrayLike} output ndarray + */ + function assign() { + var args; + var i; + + args = []; + for ( i = 0; i < arguments.length; i++ ) { + args.push( arguments[ i ] ); + } + return f.assign.apply( f, args ); + } +} + + +// EXPORTS // + +module.exports = factory; diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/package.json b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/package.json new file mode 100644 index 000000000000..cd75c568e7e6 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/package.json @@ -0,0 +1,65 @@ +{ + "name": "@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory", + "version": "0.0.0", + "description": "Create a function for performing binary reduction on two input ndarrays.", + "license": "Apache-2.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" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "factory", + "function", + "func", + "fcn", + "ndarray", + "strided", + "vector", + "array", + "apply", + "reduction", + "reduce" + ] +} diff --git a/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/test/test.js b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/test/test.js new file mode 100644 index 000000000000..6a51e9ffda63 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch-factory/test/test.js @@ -0,0 +1,35 @@ +/** +* @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 tape = require( 'tape' ); +var factory = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof factory, 'function', 'main export is a function' ); + t.end(); +}); + +// FIXME: add tests