diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/README.md b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/README.md new file mode 100644 index 000000000000..91d0c46201b3 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/README.md @@ -0,0 +1,126 @@ + + +# ternaryBlockSize + +> Resolve a loop block size for multi-dimensional array tiled loops. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var ternaryBlockSize = require( '@stdlib/ndarray/base/ternary-tiling-block-size' ); +``` + +#### ternaryBlockSize( dtypeW, dtypeX, dtypeY, dtypeZ ) + +Resolves a loop block size according to provided ndarray [dtypes][@stdlib/ndarray/dtypes] for multi-dimensional array tiled loops applying a ternary function. + +```javascript +var bsize = ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ); +// returns +``` + +
+ + + + + +
+ +## Notes + +- The returned loop tiling block size is in units of elements. + +
+ + + + + +
+ +## Examples + + + +```javascript +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var cartesianPower = require( '@stdlib/array/base/cartesian-power' ); +var promotionRules = require( '@stdlib/ndarray/promotion-rules' ); +var ternaryBlockSize = require( '@stdlib/ndarray/base/ternary-tiling-block-size' ); + +// Generate a list of input ndarray dtype triplets: +var dt = cartesianPower( dtypes(), 3 ); + +// Resolve the block size for each dtype triplet and its promoted dtype... +var t; +var b; +var i; +console.log( 'block_size, wdtype, xdtype, ydtype, zdtype' ); +for ( i = 0; i < dt.length; i++ ) { + t = promotionRules.apply( null, dt[ i ] ); + dt[ i ].push( ( t === -1 ) ? 'generic' : t ); + b = ternaryBlockSize.apply( null, dt[ i ] ); + console.log( '%d, %s, %s, %s, %s', b, dt[i][0], dt[i][1], dt[i][2], dt[i][3] ); +} +``` + +
+ + + + + +
+ +
+ + + + + +
+ +
+ + + + + +
+ +[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes + +
+ + diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/benchmark/benchmark.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/benchmark/benchmark.js new file mode 100644 index 000000000000..6c8dad9d9cb1 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/benchmark/benchmark.js @@ -0,0 +1,102 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimitive; +var pkg = require( './../package.json' ).name; +var blockSize = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var dw; + var dx; + var dy; + var dz; + var s; + var i; + + dw = [ + 'float64', + 'float32', + 'int8', + 'uint8', + 'uint8c', + 'int16', + 'uint16', + 'int32', + 'uint32', + 'binary', + 'generic', + 'foobar' + ]; + dx = [ + 'float64', + 'float32', + 'int8', + 'uint8', + 'uint8c', + 'int16', + 'uint16', + 'int32', + 'uint32', + 'binary', + 'generic', + 'foobar' + ]; + dy = [ + 'float64', + 'float32', + 'int8', + 'uint8', + 'uint8c', + 'int16', + 'uint16', + 'int32', + 'uint32', + 'binary', + 'generic', + 'foobar' + ]; + dz = [ + 'float64', + 'generic', + 'int32', + 'int16', + 'int8' + ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + s = blockSize( dw[ i%dw.length ], dx[ i%dx.length ], dy[ i%dy.length ], dz[ i%dz.length ] ); // eslint-disable-line max-len + if ( typeof s !== 'number' ) { + b.fail( 'should return a number' ); + } + } + b.toc(); + if ( !isPositiveInteger( s ) ) { + b.fail( 'should return a positive integer' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/repl.txt new file mode 100644 index 000000000000..3916de61c021 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/repl.txt @@ -0,0 +1,33 @@ + +{{alias}}( dtypeW, dtypeX, dtypeY, dtypeZ ) + Returns a loop block size for multi-dimensional array tiled loops. + + Parameters + ---------- + dtypeW: string|DataType + First input array data type. + + dtypeX: string|DataType + Second input array data type. + + dtypeY: string|DataType + Third input array data type. + + dtypeZ: string|DataType + Output array data type. + + Returns + ------- + out: integer + Block size. + + Examples + -------- + > var out = {{alias}}( 'float64', 'float64', 'float64', 'float64' ) + + > out = {{alias}}( 'float64', 'int32', 'float64', 'float64' ) + + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/index.d.ts new file mode 100644 index 000000000000..3476b54537d6 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/index.d.ts @@ -0,0 +1,43 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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 { DataType } from '@stdlib/types/ndarray'; + +/** +* Returns a loop block size for multi-dimensional array tiled loops. +* +* @param dtypeW - first input array data type +* @param dtypeX - second input array data type +* @param dtypeY - third input array data type +* @param dtypeZ - output array data type +* @returns block size (in units of elements) +* +* @example +* var bsize = ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ); +* // returns +*/ +declare function ternaryBlockSize( dtypeW: DataType, dtypeX: DataType, dtypeY: DataType, dtypeZ: DataType ): number; + + +// EXPORTS // + +export = ternaryBlockSize; diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/test.ts new file mode 100644 index 000000000000..70015f436521 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/docs/types/test.ts @@ -0,0 +1,42 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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. +*/ + +import ternaryBlockSize = require( './index' ); + + +// TESTS // + +// The function returns a number... +{ + ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ); // $ExpectType number + ternaryBlockSize( 'float32', 'int8', 'uint16', 'complex128' ); // $ExpectType number + ternaryBlockSize( 'generic', 'generic', 'generic', 'generic' ); // $ExpectType number +} + +// The compiler throws an error if the function is provided insufficient arguments... +{ + ternaryBlockSize(); // $ExpectError + ternaryBlockSize( 'float64' ); // $ExpectError + ternaryBlockSize( 'float64', 'float64' ); // $ExpectError + ternaryBlockSize( 'float64', 'float64', 'float64' ); // $ExpectError +} + +// The compiler throws an error if the function is provided too many arguments... +{ + ternaryBlockSize( 'float64', 'float64', 'float64', 'float64', {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/examples/index.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/examples/index.js new file mode 100644 index 000000000000..c1d96d83714b --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/examples/index.js @@ -0,0 +1,39 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var cartesianPower = require( '@stdlib/array/base/cartesian-power' ); +var promotionRules = require( '@stdlib/ndarray/promotion-rules' ); +var ternaryBlockSize = require( './../lib' ); + +// Generate a list of input ndarray dtype triplets: +var dt = cartesianPower( dtypes(), 3 ); + +// Resolve the block size for each dtype triplet and its promoted dtype... +var t; +var b; +var i; +console.log( 'block_size, wdtype, xdtype, ydtype, zdtype' ); +for ( i = 0; i < dt.length; i++ ) { + t = promotionRules.apply( null, dt[ i ] ); + dt[ i ].push( ( t === -1 ) ? 'generic' : t ); + b = ternaryBlockSize.apply( null, dt[ i ] ); + console.log( '%d, %s, %s, %s, %s', b, dt[i][0], dt[i][1], dt[i][2], dt[i][3] ); +} diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/defaults.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/defaults.js new file mode 100644 index 000000000000..c7ef3101b2d2 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/defaults.js @@ -0,0 +1,34 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 // + +var defaults = { + // Define a default block size (in bytes): + 'BLOCK_SIZE_IN_BYTES': 64|0, // 64b is a common cache line size. How applicable the common cache line size is here is debatable, given that, depending on the associated stride(s), the innermost loop may not iterate over adjacent elements. The primary goal is to have a block size in which all data within a block can always fit in (L1) cache, regardless of cache size (i.e., cache-oblivious). For reference, a common L1 cache size is 32kB per core. For best performance, block sizes should be tuned based on system hardware; however, such tuning is not readily available to us here. Without obvious better alternatives, 64b has some theoretical (and practical) underpinning, and it should be good enough for most inputs, especially for ndarrays with near contiguity. + + // Define a default block size (in elements): + 'BLOCK_SIZE_IN_ELEMENTS': 8|0 // 64 bytes / 8 bytes per element (i.e., default element size is same as a double) +}; + + +// EXPORTS // + +module.exports = defaults; diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/index.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/index.js new file mode 100644 index 000000000000..5e6f3be4c82e --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/index.js @@ -0,0 +1,40 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +/** +* Resolve a loop block size for multi-dimensional array tiled loops. +* +* @module @stdlib/ndarray/base/ternary-tiling-block-size +* +* @example +* var ternaryBlockSize = require( '@stdlib/ndarray/base/ternary-tiling-block-size' ); +* +* var bsize = ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ); +* // returns +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/main.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/main.js new file mode 100644 index 000000000000..c03b5a99b867 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/lib/main.js @@ -0,0 +1,73 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 bytesPerElement = require( '@stdlib/ndarray/base/bytes-per-element' ); +var defaults = require( './defaults.js' ); + + +// MAIN // + +/** +* Returns a loop block size for multi-dimensional array tiled loops. +* +* @param {*} dtypeW - first input array data type +* @param {*} dtypeX - second input array data type +* @param {*} dtypeY - third input array data type +* @param {*} dtypeZ - output array data type +* @returns {integer} block size (in units of elements) +* +* @example +* var bsize = ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ); +* // returns +*/ +function ternaryBlockSize( dtypeW, dtypeX, dtypeY, dtypeZ ) { + var nbx; + var nby; + var nbz; + var nbw; + var max; + + nbx = bytesPerElement( dtypeW ); + nby = bytesPerElement( dtypeX ); + nbz = bytesPerElement( dtypeY ); + nbw = bytesPerElement( dtypeZ ); + if ( nbx === null || nby === null || nbz === null || nbw === null ) { // e.g., "generic" arrays + return defaults.BLOCK_SIZE_IN_ELEMENTS; + } + // Find the largest element size among all four arrays: + max = nbx; + if ( nby > max ) { + max = nby; + } + if ( nbz > max ) { + max = nbz; + } + if ( nbw > max ) { + max = nbw; + } + return ( defaults.BLOCK_SIZE_IN_BYTES/max )|0; // asm type annotation +} + + +// EXPORTS // + +module.exports = ternaryBlockSize; diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/package.json b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/package.json new file mode 100644 index 000000000000..ca383a7aaf78 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/package.json @@ -0,0 +1,69 @@ +{ + "name": "@stdlib/ndarray/base/ternary-tiling-block-size", + "version": "0.0.0", + "description": "Resolve a loop block size for multi-dimensional array tiled loops.", + "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", + "stdtypes", + "types", + "base", + "ndarray", + "loop", + "tiling", + "blocking", + "cache-oblivious", + "multidimensional", + "array", + "utilities", + "utility", + "utils", + "util" + ], + "__stdlib__": {} +} diff --git a/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/test/test.js b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/test/test.js new file mode 100644 index 000000000000..46e26539ddd1 --- /dev/null +++ b/lib/node_modules/@stdlib/ndarray/base/ternary-tiling-block-size/test/test.js @@ -0,0 +1,61 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimitive; +var dtypes = require( '@stdlib/ndarray/dtypes' ); +var cartesianPower = require( '@stdlib/array/base/cartesian-power' ); +var promotionRules = require( '@stdlib/ndarray/promotion-rules' ); +var ternaryBlockSize = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof ternaryBlockSize, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns a block size', function test( t ) { + var dt; + var pt; + var v; + var i; + + // NOTE: we don't test for exact block size values, as we shouldn't need to make guarantees regarding the block size for any particular set of dtypes. This function is meant to be opaque, and we want to reserve the right to silently update/change return values in the future. + + // Generate dtype triplets: + dt = cartesianPower( dtypes(), 3 ); + + for ( i = 0; i < dt.length; i++ ) { + pt = promotionRules.apply( null, dt[ i ] ); + dt[ i ].push( ( pt === -1 ) ? 'generic' : pt ); + v = ternaryBlockSize( dt[ i ][ 0 ], dt[ i ][ 1 ], dt[ i ][ 2 ], dt[ i ][ 3 ] ); // eslint-disable-line max-len + t.strictEqual( isPositiveInteger( v ), true, 'returns a positive integer when provided ('+dt[ i ].join( ', ' )+')' ); + } + + // Sanity check that the block size for dtypes with wider bit widths is smaller than for dtypes with shorter bit widths... + t.strictEqual( ternaryBlockSize( 'complex128', 'complex128', 'complex128', 'complex128' ) < ternaryBlockSize( 'int8', 'int8', 'int8', 'int8' ), true, 'returns expected value' ); + t.strictEqual( ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' ) < ternaryBlockSize( 'uint8', 'uint8', 'uint8', 'uint8' ), true, 'returns expected value' ); + t.end(); +});