Skip to content

Commit 8cb6c7c

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/base/append-singleton-dimensions
PR-URL: #11782 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Closes: stdlib-js/metr-issue-tracker#405
1 parent 5a06940 commit 8cb6c7c

11 files changed

Lines changed: 824 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/base/append-singleton-dimensions/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# appendSingletonDimensions
22+
23+
> Append singleton dimensions.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
<!-- eslint-disable id-length -->
40+
41+
```javascript
42+
var appendSingletonDimensions = require( '@stdlib/ndarray/base/append-singleton-dimensions' );
43+
```
44+
45+
#### appendSingletonDimensions( x, n, writable )
46+
47+
Returns an ndarray with a specified number of appended singleton dimensions (i.e., dimensions whose size is equal to `1`).
48+
49+
<!-- eslint-disable id-length -->
50+
51+
```javascript
52+
var array = require( '@stdlib/ndarray/array' );
53+
54+
// Create a 2x2 ndarray:
55+
var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
56+
// returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
57+
58+
// Append singleton dimensions:
59+
var y = appendSingletonDimensions( x, 3, false );
60+
// returns <ndarray>[ [ [ [ [ 1 ] ] ], [ [ [ 2 ] ] ] ], [ [ [ [ 3 ] ] ], [ [ [ 4 ] ] ] ] ]
61+
```
62+
63+
The function accepts the following arguments:
64+
65+
- **x**: input ndarray.
66+
- **n**: number of singleton dimensions to append.
67+
- **writable**: boolean indicating whether a returned ndarray should be writable.
68+
69+
</section>
70+
71+
<!-- /.usage -->
72+
73+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
74+
75+
<section class="notes">
76+
77+
## Notes
78+
79+
- The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
80+
81+
</section>
82+
83+
<!-- /.notes -->
84+
85+
<!-- Package usage examples. -->
86+
87+
<section class="examples">
88+
89+
## Examples
90+
91+
<!-- eslint-disable id-length -->
92+
93+
<!-- eslint no-undef: "error" -->
94+
95+
```javascript
96+
var uniform = require( '@stdlib/random/uniform' );
97+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
98+
var appendSingletonDimensions = require( '@stdlib/ndarray/base/append-singleton-dimensions' );
99+
100+
var x = uniform( [ 3, 3, 3 ], -10.0, 10.0 );
101+
console.log( ndarray2array( x ) );
102+
103+
var y = appendSingletonDimensions( x, 3, false );
104+
console.log( ndarray2array( y ) );
105+
```
106+
107+
</section>
108+
109+
<!-- /.examples -->
110+
111+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
112+
113+
<section class="references">
114+
115+
</section>
116+
117+
<!-- /.references -->
118+
119+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
120+
121+
<section class="related">
122+
123+
</section>
124+
125+
<!-- /.related -->
126+
127+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
128+
129+
<section class="links">
130+
131+
</section>
132+
133+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/append-singleton-dimensions/benchmark/benchmark.js‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var Float64Array = require( '@stdlib/array/float64' );
25+
var ndarrayBase = require( '@stdlib/ndarray/base/ctor' );
26+
var ndarray = require( '@stdlib/ndarray/ctor' );
27+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
28+
var format = require( '@stdlib/string/format' );
29+
var pkg = require( './../package.json' ).name;
30+
var appendSingletonDimensions = require( './../lib' );
31+
32+
33+
// MAIN //
34+
35+
bench( format( '%s::base_ndarray,2d', pkg ), function benchmark( b ) {
36+
var strides;
37+
var values;
38+
var buffer;
39+
var offset;
40+
var dtype;
41+
var shape;
42+
var order;
43+
var out;
44+
var i;
45+
46+
dtype = 'float64';
47+
buffer = new Float64Array( 2 );
48+
shape = [ 2 ];
49+
strides = [ 1 ];
50+
offset = 0;
51+
order = 'row-major';
52+
53+
values = [
54+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
55+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
56+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
57+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
58+
ndarrayBase( dtype, buffer, shape, strides, offset, order )
59+
];
60+
61+
b.tic();
62+
for ( i = 0; i < b.iterations; i++ ) {
63+
out = appendSingletonDimensions( values[ i%values.length ], 1, false );
64+
if ( typeof out !== 'object' ) {
65+
b.fail( 'should return an object' );
66+
}
67+
}
68+
b.toc();
69+
if ( !isndarrayLike( out ) ) {
70+
b.fail( 'should return an ndarray' );
71+
}
72+
b.pass( 'benchmark finished' );
73+
b.end();
74+
});
75+
76+
bench( format( '%s::ndarray,2d', pkg ), function benchmark( b ) {
77+
var strides;
78+
var values;
79+
var buffer;
80+
var offset;
81+
var dtype;
82+
var shape;
83+
var order;
84+
var out;
85+
var i;
86+
87+
dtype = 'float64';
88+
buffer = new Float64Array( 2 );
89+
shape = [ 2 ];
90+
strides = [ 1 ];
91+
offset = 0;
92+
order = 'row-major';
93+
94+
values = [
95+
ndarray( dtype, buffer, shape, strides, offset, order ),
96+
ndarray( dtype, buffer, shape, strides, offset, order ),
97+
ndarray( dtype, buffer, shape, strides, offset, order ),
98+
ndarray( dtype, buffer, shape, strides, offset, order ),
99+
ndarray( dtype, buffer, shape, strides, offset, order )
100+
];
101+
102+
b.tic();
103+
for ( i = 0; i < b.iterations; i++ ) {
104+
out = appendSingletonDimensions( values[ i%values.length ], 1, false );
105+
if ( typeof out !== 'object' ) {
106+
b.fail( 'should return an object' );
107+
}
108+
}
109+
b.toc();
110+
if ( !isndarrayLike( out ) ) {
111+
b.fail( 'should return an ndarray' );
112+
}
113+
b.pass( 'benchmark finished' );
114+
b.end();
115+
});

‎lib/node_modules/@stdlib/ndarray/base/append-singleton-dimensions/benchmark/benchmark.ndims.js‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var array = require( '@stdlib/ndarray/array' );
25+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
26+
var format = require( '@stdlib/string/format' );
27+
var pkg = require( './../package.json' ).name;
28+
var appendSingletonDimensions = require( './../lib' );
29+
30+
31+
// FUNCTIONS //
32+
33+
/**
34+
* Creates a benchmark function.
35+
*
36+
* @private
37+
* @param {PositiveInteger} ndims - number of singleton dimensions
38+
* @returns {Function} benchmark function
39+
*/
40+
function createBenchmark( ndims ) {
41+
var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
42+
return benchmark;
43+
44+
/**
45+
* Benchmark function.
46+
*
47+
* @private
48+
* @param {Benchmark} b - benchmark instance
49+
*/
50+
function benchmark( b ) {
51+
var out;
52+
var i;
53+
54+
b.tic();
55+
for ( i = 0; i < b.iterations; i++ ) {
56+
out = appendSingletonDimensions( x, ndims, false );
57+
if ( typeof out !== 'object' ) {
58+
b.fail( 'should return an object' );
59+
}
60+
}
61+
b.toc();
62+
if ( !isndarrayLike( out ) ) {
63+
b.fail( 'should return an ndarray' );
64+
}
65+
b.pass( 'benchmark finished' );
66+
b.end();
67+
}
68+
}
69+
70+
71+
// MAIN //
72+
73+
/**
74+
* Main execution sequence.
75+
*
76+
* @private
77+
*/
78+
function main() {
79+
var min;
80+
var max;
81+
var f;
82+
var i;
83+
84+
min = 1;
85+
max = 10;
86+
87+
for ( i = min; i <= max; i++ ) {
88+
f = createBenchmark( i );
89+
bench( format( '%s::ndarray,2d:singleton_dimensions=%d', pkg, i ), f );
90+
}
91+
}
92+
93+
main();

‎lib/node_modules/@stdlib/ndarray/base/append-singleton-dimensions/docs/repl.txt‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
2+
{{alias}}( x, n, writable )
3+
Returns an array with a specified number of appended singleton dimensions.
4+
5+
Parameters
6+
----------
7+
x: ndarray
8+
Input array.
9+
10+
n: integer
11+
Number of singleton dimensions to append.
12+
13+
writable: boolean
14+
Boolean indicating whether a returned array should be writable.
15+
16+
Returns
17+
-------
18+
out: ndarray
19+
Output array.
20+
21+
Examples
22+
--------
23+
> var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] )
24+
<ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
25+
> var y = {{alias}}( x, 1, false )
26+
<ndarray>[ [ [ 1 ], [ 2 ] ], [ [ 3 ], [ 4 ] ] ]
27+
28+
See Also
29+
--------
30+

0 commit comments

Comments
 (0)