Skip to content

Commit 2eb9120

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/base/reinterpret-complex
PR-URL: #11779 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Closes: stdlib-js/metr-issue-tracker#272
1 parent 792a723 commit 2eb9120

10 files changed

Lines changed: 1058 additions & 0 deletions

File tree

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
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+
# reinterpret
22+
23+
> Reinterpret a complex-valued floating-point [ndarray][@stdlib/ndarray/base/ctor] as a real-valued floating-point [ndarray][@stdlib/ndarray/base/ctor] having the same precision.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var reinterpretComplex = require( '@stdlib/ndarray/base/reinterpret-complex' );
37+
```
38+
39+
#### reinterpretComplex( x )
40+
41+
Reinterprets a complex-valued floating-point [ndarray][@stdlib/ndarray/base/ctor] as a real-valued floating-point [ndarray][@stdlib/ndarray/base/ctor] having the same precision.
42+
43+
```javascript
44+
var zeroTo = require( '@stdlib/blas/ext/zero-to' );
45+
46+
var x = zeroTo( [ 2, 2 ], {
47+
'dtype': 'complex128'
48+
});
49+
// returns <ndarray>[ [ <Complex128>[ 0.0, 0.0 ], <Complex128>[ 1.0, 0.0 ] ], [ <Complex128>[ 0.0, 0.0 ], <Complex128>[ 1.0, 0.0 ] ] ]
50+
51+
var out = reinterpretComplex( x );
52+
// returns <ndarray>[ [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ], [ [ 0.0, 0.0 ], [ 1.0, 0.0 ] ] ]
53+
```
54+
55+
</section>
56+
57+
<!-- /.usage -->
58+
59+
<section class="notes">
60+
61+
## Notes
62+
63+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a view on the input [ndarray][@stdlib/ndarray/base/ctor] data buffer.
64+
- 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].
65+
- 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.
66+
67+
</section>
68+
69+
<!-- /.notes -->
70+
71+
<section class="examples">
72+
73+
## Examples
74+
75+
<!-- eslint no-undef: "error" -->
76+
77+
```javascript
78+
var zeroTo = require( '@stdlib/blas/ext/zero-to' );
79+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
80+
var reinterpretComplex = require( '@stdlib/ndarray/base/reinterpret-complex' );
81+
82+
// Create a double-precision complex floating-point ndarray:
83+
var x = zeroTo( [ 2, 2 ], {
84+
'dtype': 'complex128'
85+
});
86+
87+
// Reinterpret as a double-precision floating-point ndarray:
88+
var out = reinterpretComplex( x );
89+
console.log( ndarray2array( out ) );
90+
```
91+
92+
</section>
93+
94+
<!-- /.examples -->
95+
96+
<section class="references">
97+
98+
</section>
99+
100+
<!-- /.references -->
101+
102+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
103+
104+
<section class="related">
105+
106+
</section>
107+
108+
<!-- /.related -->
109+
110+
<section class="links">
111+
112+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
113+
114+
[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/ctor
115+
116+
</section>
117+
118+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex/benchmark/benchmark.js‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
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 Complex128Array = require( '@stdlib/array/complex128' );
25+
var Complex64Array = require( '@stdlib/array/complex64' );
26+
var ndarrayBase = require( '@stdlib/ndarray/base/ctor' );
27+
var ndarray = require( '@stdlib/ndarray/ctor' );
28+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
29+
var format = require( '@stdlib/string/format' );
30+
var pkg = require( './../package.json' ).name;
31+
var reinterpretComplex = require( './../lib' );
32+
33+
34+
// MAIN //
35+
36+
bench( format( '%s::base_ndarray:dtype=complex128', pkg ), function benchmark( b ) {
37+
var strides;
38+
var values;
39+
var buffer;
40+
var offset;
41+
var dtype;
42+
var shape;
43+
var order;
44+
var out;
45+
var i;
46+
47+
dtype = 'complex128';
48+
buffer = new Complex128Array( 4 );
49+
shape = [ 2, 2 ];
50+
strides = [ 2, 1 ];
51+
offset = 0;
52+
order = 'row-major';
53+
54+
values = [
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+
ndarrayBase( dtype, buffer, shape, strides, offset, order )
60+
];
61+
62+
b.tic();
63+
for ( i = 0; i < b.iterations; i++ ) {
64+
out = reinterpretComplex( values[ i%values.length ] );
65+
if ( typeof out !== 'object' ) {
66+
b.fail( 'should return an object' );
67+
}
68+
}
69+
b.toc();
70+
if ( !isndarrayLike( out ) ) {
71+
b.fail( 'should return an ndarray' );
72+
}
73+
b.pass( 'benchmark finished' );
74+
b.end();
75+
});
76+
77+
bench( format( '%s::ndarray:dtype=complex128', pkg ), function benchmark( b ) {
78+
var strides;
79+
var values;
80+
var buffer;
81+
var offset;
82+
var dtype;
83+
var shape;
84+
var order;
85+
var out;
86+
var i;
87+
88+
dtype = 'complex128';
89+
buffer = new Complex128Array( 4 );
90+
shape = [ 2, 2 ];
91+
strides = [ 2, 1 ];
92+
offset = 0;
93+
order = 'row-major';
94+
95+
values = [
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+
ndarray( dtype, buffer, shape, strides, offset, order )
101+
];
102+
103+
b.tic();
104+
for ( i = 0; i < b.iterations; i++ ) {
105+
out = reinterpretComplex( values[ i%values.length ] );
106+
if ( typeof out !== 'object' ) {
107+
b.fail( 'should return an object' );
108+
}
109+
}
110+
b.toc();
111+
if ( !isndarrayLike( out ) ) {
112+
b.fail( 'should return an ndarray' );
113+
}
114+
b.pass( 'benchmark finished' );
115+
b.end();
116+
});
117+
118+
bench( format( '%s::base_ndarray:dtype=complex64', pkg ), function benchmark( b ) {
119+
var strides;
120+
var values;
121+
var buffer;
122+
var offset;
123+
var dtype;
124+
var shape;
125+
var order;
126+
var out;
127+
var i;
128+
129+
dtype = 'complex64';
130+
buffer = new Complex64Array( 4 );
131+
shape = [ 2, 2 ];
132+
strides = [ 2, 1 ];
133+
offset = 0;
134+
order = 'row-major';
135+
136+
values = [
137+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
138+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
139+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
140+
ndarrayBase( dtype, buffer, shape, strides, offset, order ),
141+
ndarrayBase( dtype, buffer, shape, strides, offset, order )
142+
];
143+
144+
b.tic();
145+
for ( i = 0; i < b.iterations; i++ ) {
146+
out = reinterpretComplex( values[ i%values.length ] );
147+
if ( typeof out !== 'object' ) {
148+
b.fail( 'should return an object' );
149+
}
150+
}
151+
b.toc();
152+
if ( !isndarrayLike( out ) ) {
153+
b.fail( 'should return an ndarray' );
154+
}
155+
b.pass( 'benchmark finished' );
156+
b.end();
157+
});
158+
159+
bench( format( '%s::ndarray:dtype=complex64', pkg ), function benchmark( b ) {
160+
var strides;
161+
var values;
162+
var buffer;
163+
var offset;
164+
var dtype;
165+
var shape;
166+
var order;
167+
var out;
168+
var i;
169+
170+
dtype = 'complex64';
171+
buffer = new Complex64Array( 4 );
172+
shape = [ 2, 2 ];
173+
strides = [ 2, 1 ];
174+
offset = 0;
175+
order = 'row-major';
176+
177+
values = [
178+
ndarray( dtype, buffer, shape, strides, offset, order ),
179+
ndarray( dtype, buffer, shape, strides, offset, order ),
180+
ndarray( dtype, buffer, shape, strides, offset, order ),
181+
ndarray( dtype, buffer, shape, strides, offset, order ),
182+
ndarray( dtype, buffer, shape, strides, offset, order )
183+
];
184+
185+
b.tic();
186+
for ( i = 0; i < b.iterations; i++ ) {
187+
out = reinterpretComplex( values[ i%values.length ] );
188+
if ( typeof out !== 'object' ) {
189+
b.fail( 'should return an object' );
190+
}
191+
}
192+
b.toc();
193+
if ( !isndarrayLike( out ) ) {
194+
b.fail( 'should return an ndarray' );
195+
}
196+
b.pass( 'benchmark finished' );
197+
b.end();
198+
});

‎lib/node_modules/@stdlib/ndarray/base/reinterpret-complex/docs/repl.txt‎

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

0 commit comments

Comments
 (0)