From 4f002e12aaf9c09af36650b6aee777b197016dec Mon Sep 17 00:00:00 2001 From: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> Date: Tue, 27 Jan 2026 02:54:04 +0000 Subject: [PATCH] feat: update `ndarray/base` TypeScript declarations Signed-off-by: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> --- .../ndarray/base/docs/types/index.d.ts | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) diff --git a/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts index e596e6d38388..34e588e72ab2 100644 --- a/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts @@ -36,6 +36,7 @@ import broadcastArray = require( '@stdlib/ndarray/base/broadcast-array' ); import broadcastArrayExceptDimensions = require( '@stdlib/ndarray/base/broadcast-array-except-dimensions' ); import broadcastArrays = require( '@stdlib/ndarray/base/broadcast-arrays' ); import broadcastScalar = require( '@stdlib/ndarray/base/broadcast-scalar' ); +import broadcastScalarLike = require( '@stdlib/ndarray/base/broadcast-scalar-like' ); import broadcastShapes = require( '@stdlib/ndarray/base/broadcast-shapes' ); import buffer = require( '@stdlib/ndarray/base/buffer' ); import bufferCtors = require( '@stdlib/ndarray/base/buffer-ctors' ); @@ -124,6 +125,8 @@ import outputPolicyStr2Enum = require( '@stdlib/ndarray/base/output-policy-str2e import pop = require( '@stdlib/ndarray/base/pop' ); import prependSingletonDimensions = require( '@stdlib/ndarray/base/prepend-singleton-dimensions' ); import promoteDataTypes = require( '@stdlib/ndarray/base/promote-dtypes' ); +import quaternaryLoopOrder = require( '@stdlib/ndarray/base/quaternary-loop-interchange-order' ); +import quinaryLoopOrder = require( '@stdlib/ndarray/base/quinary-loop-interchange-order' ); import removeSingletonDimensions = require( '@stdlib/ndarray/base/remove-singleton-dimensions' ); import reverse = require( '@stdlib/ndarray/base/reverse' ); import reverseDimension = require( '@stdlib/ndarray/base/reverse-dimension' ); @@ -745,6 +748,28 @@ interface Namespace { */ broadcastScalar: typeof broadcastScalar; + /** + * Broadcasts a scalar value to an ndarray having the same shape and data type as a provided input ndarray. + * + * @param x - input array + * @param value - scalar value + * @returns output ndarray + * + * @example + * var zeros = require( '@stdlib/ndarray/base/zeros' ); + * var getDType = require( '@stdlib/ndarray/dtype' ); + * + * var x = zeros( 'float64', [ 2, 2 ], 'row-major' ); + * // returns [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] + * + * var y = ns.broadcastScalarLike( x, 1.0 ); + * // returns [ [ 1.0, 1.0 ], [ 1.0, 1.0 ] ] + * + * var dt = String( getDType( y ) ); + * // returns 'float64' + */ + broadcastScalarLike: typeof broadcastScalarLike; + /** * Broadcasts array shapes to a single shape. * @@ -3194,6 +3219,136 @@ interface Namespace { */ promoteDataTypes: typeof promoteDataTypes; + /** + * Reorders ndarray dimensions and associated strides for loop interchange. + * + * ## Notes + * + * - The returned object has the following properties: + * + * - **sh**: dimensions sorted in loop order. + * - **sx**: first input ndarray strides sorted in loop order. + * - **sy**: second input ndarray strides sorted in loop order. + * - **sz**: third input ndarray strides sorted in loop order. + * - **sw**: fourth input ndarray strides sorted in loop order. + * - **su**: output ndarray strides sorted in loop order. + * + * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache. + * + * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference. + * + * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order. + * + * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting. + * + * @param shape - array dimensions + * @param stridesX - first input array stride lengths + * @param stridesY - second input array stride lengths + * @param stridesZ - third input array stride lengths + * @param stridesW - fourth input array stride lengths + * @param stridesU - output array stride lengths + * @returns loop interchange data + * + * @example + * var sh = [ 2, 3, 4 ]; + * + * var sx = [ 12, 4, 1 ]; // row-major + * var sy = [ 24, 8, 1 ]; // row-major + * var sz = [ 1, 4, 12 ]; // column-major + * var sw = [ 1, -2, 6 ]; // column-major + * var su = [ 1, -2, 6 ]; // column-major + * + * var o = ns.quaternaryLoopOrder( sh, sx, sy, sz, sw, su ); + * // returns {...} + * + * var ssh = o.sh; + * // returns [ 2, 3, 4 ] + * + * var ssx = o.sx; + * // returns [ 12, 4, 1 ] + * + * var ssy = o.sy; + * // returns [ 24, 8, 1 ] + * + * var ssz = o.sz; + * // returns [ 1, 4, 12 ] + * + * var ssw = o.sw; + * // returns [ 1, -2, 6 ] + * + * var ssu = o.su; + * // returns [ 1, -2, 6 ] + */ + quaternaryLoopOrder: typeof quaternaryLoopOrder; + + /** + * Reorders ndarray dimensions and associated strides for loop interchange. + * + * ## Notes + * + * - The returned object has the following properties: + * + * - **sh**: dimensions sorted in loop order. + * - **sx**: first input ndarray strides sorted in loop order. + * - **sy**: second input ndarray strides sorted in loop order. + * - **sz**: third input ndarray strides sorted in loop order. + * - **sw**: fourth input ndarray strides sorted in loop order. + * - **su**: fifth input ndarray strides sorted in loop order. + * - **sv**: output ndarray strides sorted in loop order. + * + * - When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache. + * + * The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference. + * + * - Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order. + * + * - The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting. + * + * @param shape - array dimensions + * @param stridesX - first input array stride lengths + * @param stridesY - second input array stride lengths + * @param stridesZ - third input array stride lengths + * @param stridesW - fourth input array stride lengths + * @param stridesU - fifth input array stride lengths + * @param stridesV - output array stride lengths + * @returns loop interchange data + * + * @example + * var sh = [ 2, 3, 4 ]; + * + * var sx = [ 12, 4, 1 ]; // row-major + * var sy = [ 24, 8, 1 ]; // row-major + * var sz = [ 12, 4, 1 ]; // row-major + * var sw = [ 24, 8, 1 ]; // row-major + * var su = [ 1, 4, 12 ]; // column-major + * var sv = [ 1, -2, 6 ]; // column-major + * + * var o = ns.quinaryLoopOrder( sh, sx, sy, sz, sw, su, sv ); + * // returns {...} + * + * var ssh = o.sh; + * // returns [ 4, 3, 2 ] + * + * var ssx = o.sx; + * // returns [ 1, 4, 12 ] + * + * var ssy = o.sy; + * // returns [ 1, 8, 24 ] + * + * var ssz = o.sz; + * // returns [ 1, 4, 12 ] + * + * var ssw = o.sw; + * // returns [ 1, 8, 24 ] + * + * var ssu = o.su; + * // returns [ 12, 4, 1 ] + * + * var ssv = o.sv; + * // returns [ 6, -2, 1 ] + */ + quinaryLoopOrder: typeof quinaryLoopOrder; + /** * Returns an array without singleton dimensions. *