Skip to content

Commit c1d72a0

Browse files
headlessNodeheadlessNode
authored
feat: add ndarray/base/reinterpret-complex64
PR-URL: #11706 Reviewed-by: Athan Reines <kgryte@gmail.com> Closes: stdlib-js/metr-issue-tracker#270
1 parent 7e92216 commit c1d72a0

File tree

10 files changed

+798
-0
lines changed

10 files changed

+798
-0
lines changed

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex64/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
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+
# reinterpretComplex64
22+
23+
> Reinterpret a single-precision complex floating-point [ndarray][@stdlib/ndarray/base/ctor] as a real-valued single-precision floating-point [ndarray][@stdlib/ndarray/base/ctor] containing interleaved real and imaginary components.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var reinterpretComplex64 = require( '@stdlib/ndarray/base/reinterpret-complex64' );
37+
```
38+
39+
#### reinterpretComplex64( x )
40+
41+
Reinterprets a single-precision complex floating-point [ndarray][@stdlib/ndarray/base/ctor] as a real-valued single-precision floating-point [ndarray][@stdlib/ndarray/base/ctor] containing interleaved real and imaginary components.
42+
43+
```javascript
44+
var ones = require( '@stdlib/ndarray/base/ones' );
45+
46+
var x = ones( 'complex64', [ 2, 2 ], 'row-major' );
47+
// returns <ndarray>[ [ <Complex64>[ 1.0, 0.0 ], <Complex64>[ 1.0, 0.0 ] ], [ <Complex64>[ 1.0, 0.0 ], <Complex64>[ 1.0, 0.0 ] ] ]
48+
49+
var out = reinterpretComplex64( x );
50+
// returns <ndarray>[ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ]
51+
```
52+
53+
</section>
54+
55+
<!-- /.usage -->
56+
57+
<section class="notes">
58+
59+
## Notes
60+
61+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a view on the input [ndarray][@stdlib/ndarray/base/ctor] data buffer.
62+
- The returned [ndarray][@stdlib/ndarray/base/ctor] has an additional trailing dimension of size two whose elements correspond to the real and imaginary components, respectively, of each complex-valued element in the input [ndarray][@stdlib/ndarray/base/ctor].
63+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a "base" [ndarray][@stdlib/ndarray/base/ctor], and, thus, the returned [ndarray][@stdlib/ndarray/base/ctor] does not perform bounds checking or afford any of the guarantees of the non-base [ndarray][@stdlib/ndarray/ctor] constructor. The primary intent of this function is to reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead.
64+
65+
</section>
66+
67+
<!-- /.notes -->
68+
69+
<section class="examples">
70+
71+
## Examples
72+
73+
<!-- eslint no-undef: "error" -->
74+
75+
```javascript
76+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
77+
var Complex64Array = require( '@stdlib/array/complex64' );
78+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
79+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
80+
var reinterpretComplex64 = require( '@stdlib/ndarray/base/reinterpret-complex64' );
81+
82+
// Create a single-precision complex floating-point ndarray:
83+
var buf = new Complex64Array( discreteUniform( 8, -5, 5 ) );
84+
var x = ndarray( 'complex64', buf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
85+
86+
// Reinterpret as a single-precision floating-point ndarray:
87+
var out = reinterpretComplex64( x );
88+
console.log( ndarray2array( out ) );
89+
```
90+
91+
</section>
92+
93+
<!-- /.examples -->
94+
95+
<section class="references">
96+
97+
</section>
98+
99+
<!-- /.references -->
100+
101+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
102+
103+
<section class="related">
104+
105+
</section>
106+
107+
<!-- /.related -->
108+
109+
<section class="links">
110+
111+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
112+
113+
[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/ctor
114+
115+
</section>
116+
117+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex64/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 Complex64Array = require( '@stdlib/array/complex64' );
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 reinterpretComplex64 = 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 = 'complex64';
47+
buffer = new Complex64Array( 4 );
48+
shape = [ 2, 2 ];
49+
strides = [ 2, 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 = reinterpretComplex64( values[ i%values.length ] );
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 = 'complex64';
88+
buffer = new Complex64Array( 4 );
89+
shape = [ 2, 2 ];
90+
strides = [ 2, 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 = reinterpretComplex64( values[ i%values.length ] );
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/reinterpret-complex64/docs/repl.txt‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
{{alias}}( x )
3+
Reinterprets a single-precision complex floating-point ndarray as a real-
4+
valued single-precision floating-point ndarray containing interleaved real
5+
and imaginary components.
6+
7+
The returned ndarray is a view on the input ndarray data buffer.
8+
9+
The returned ndarray has an additional trailing dimension of size two whose
10+
elements correspond to the real and imaginary components, respectively, of
11+
each complex-valued element in the input ndarray.
12+
13+
The returned ndarray is a "base" ndarray, and, thus, the returned ndarray
14+
does not perform bounds checking or afford any of the guarantees of the
15+
non-base ndarray constructor. The primary intent of this function is to
16+
reinterpret an ndarray-like object within internal implementations and to
17+
do so with minimal overhead.
18+
19+
Parameters
20+
----------
21+
x: ndarray
22+
Input ndarray.
23+
24+
Returns
25+
-------
26+
out: ndarray
27+
Single-precision floating-point ndarray view.
28+
29+
Examples
30+
--------
31+
> var dt = 'complex64';
32+
> var x = {{alias:@stdlib/ndarray/base/zeros}}( dt, [ 2, 2 ], 'row-major' );
33+
> var out = {{alias}}( x )
34+
<ndarray>[ [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ], [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] ]
35+
36+
See Also
37+
--------
38+

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex64/docs/types/index.d.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
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+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { complex64ndarray, float32ndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Reinterprets a single-precision complex floating-point ndarray as a real-valued single-precision floating-point ndarray containing interleaved real and imaginary components.
27+
*
28+
* ## Notes
29+
*
30+
* - The returned ndarray is a view on the input ndarray data buffer.
31+
* - The returned ndarray has an additional trailing dimension of size two whose elements correspond to the real and imaginary components, respectively, of each complex-valued element in the input ndarray.
32+
* - The returned ndarray is a "base" ndarray, and, thus, the returned ndarray does not perform bounds checking or afford any of the guarantees of the non-base ndarray constructor. The primary intent of this function is to reinterpret an ndarray-like object within internal implementations and to do so with minimal overhead.
33+
*
34+
* @param x - input ndarray
35+
* @returns single-precision floating-point ndarray view
36+
*
37+
* @example
38+
* var ones = require( '@stdlib/ndarray/base/ones' );
39+
*
40+
* var x = ones( 'complex64', [ 2, 2 ], 'row-major' );
41+
* // returns <ndarray>[ [ <Complex64>[ 1.0, 0.0 ], <Complex64>[ 1.0, 0.0 ] ], [ <Complex64>[ 1.0, 0.0 ], <Complex64>[ 1.0, 0.0 ] ] ]
42+
*
43+
* var out = reinterpretComplex64( x );
44+
* // returns <ndarray>[ [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 1.0, 0.0 ], [ 1.0, 0.0 ] ] ]
45+
*/
46+
declare function reinterpretComplex64( x: complex64ndarray ): float32ndarray;
47+
48+
49+
// EXPORTS //
50+
51+
export = reinterpretComplex64;

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex64/docs/types/test.ts‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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+
import zeros = require( '@stdlib/ndarray/base/zeros' );
20+
import reinterpretComplex64 = require( './index' );
21+
22+
23+
// TESTS //
24+
25+
// The function returns a float32ndarray...
26+
{
27+
const x = zeros( 'complex64', [ 2, 2 ], 'row-major' );
28+
29+
reinterpretComplex64( x ); // $ExpectType float32ndarray
30+
}
31+
32+
// The compiler throws an error if the function is not provided a first argument which is a complex64ndarray...
33+
{
34+
reinterpretComplex64( '5' ); // $ExpectError
35+
reinterpretComplex64( 5 ); // $ExpectError
36+
reinterpretComplex64( true ); // $ExpectError
37+
reinterpretComplex64( false ); // $ExpectError
38+
reinterpretComplex64( null ); // $ExpectError
39+
reinterpretComplex64( {} ); // $ExpectError
40+
reinterpretComplex64( [ '5' ] ); // $ExpectError
41+
reinterpretComplex64( ( x: number ): number => x ); // $ExpectError
42+
reinterpretComplex64( zeros( 'float64', [ 2, 2 ], 'row-major' ) ); // $ExpectError
43+
reinterpretComplex64( zeros( 'float32', [ 2, 2 ], 'row-major' ) ); // $ExpectError
44+
reinterpretComplex64( zeros( 'int32', [ 2, 2 ], 'row-major' ) ); // $ExpectError
45+
reinterpretComplex64( zeros( 'complex128', [ 2, 2 ], 'row-major' ) ); // $ExpectError
46+
}
47+
48+
// The compiler throws an error if the function is provided an unsupported number of arguments...
49+
{
50+
const x = zeros( 'complex64', [ 2, 2 ], 'row-major' );
51+
52+
reinterpretComplex64(); // $ExpectError
53+
reinterpretComplex64( x, {} ); // $ExpectError
54+
}

0 commit comments

Comments
 (0)