Skip to content

Commit f2ba078

Browse files
headlessNodeheadlessNode
committed
feat: add ndarray/base/reinterpret-complex
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---
1 parent 5a06940 commit f2ba078

10 files changed

Lines changed: 1023 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 ones = require( '@stdlib/ndarray/base/ones' );
45+
46+
var x = ones( 'complex128', [ 2, 2 ], 'row-major' );
47+
// returns <ndarray>[ [ <Complex128>[ 1.0, 0.0 ], <Complex128>[ 1.0, 0.0 ] ], [ <Complex128>[ 1.0, 0.0 ], <Complex128>[ 1.0, 0.0 ] ] ]
48+
49+
var out = reinterpretComplex( 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+
- If provided an [ndarray][@stdlib/ndarray/base/ctor] whose underlying data buffer is neither a `Complex128Array` nor a `Complex64Array`, the function returns the input [ndarray][@stdlib/ndarray/base/ctor] unchanged.
62+
- The returned [ndarray][@stdlib/ndarray/base/ctor] is a view on the input [ndarray][@stdlib/ndarray/base/ctor] data buffer.
63+
- 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].
64+
- 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.
65+
66+
</section>
67+
68+
<!-- /.notes -->
69+
70+
<section class="examples">
71+
72+
## Examples
73+
74+
<!-- eslint no-undef: "error" -->
75+
76+
```javascript
77+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
78+
var Complex128Array = require( '@stdlib/array/complex128' );
79+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
80+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
81+
var reinterpretComplex = require( '@stdlib/ndarray/base/reinterpret-complex' );
82+
83+
// Create a double-precision complex floating-point ndarray:
84+
var buf = new Complex128Array( discreteUniform( 8, -5, 5 ) );
85+
var x = ndarray( 'complex128', buf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
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: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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+
If provided an ndarray whose underlying data buffer is neither a
7+
Complex128Array nor a Complex64Array, the function returns the input
8+
ndarray unchanged.
9+
10+
The returned ndarray is a view on the input ndarray data buffer.
11+
12+
The returned ndarray has an additional trailing dimension of size two whose
13+
elements correspond to the real and imaginary components, respectively, of
14+
each complex-valued element in the input ndarray.
15+
16+
The returned ndarray is a "base" ndarray, and, thus, the returned ndarray
17+
does not perform bounds checking or afford any of the guarantees of the
18+
non-base ndarray constructor. The primary intent of this function is to
19+
reinterpret an ndarray-like object within internal implementations and to
20+
do so with minimal overhead.
21+
22+
Parameters
23+
----------
24+
x: ndarray
25+
Input ndarray.
26+
27+
Returns
28+
-------
29+
out: ndarray
30+
Real-valued floating-point ndarray view.
31+
32+
Examples
33+
--------
34+
> var dt = 'complex128';
35+
> var x = {{alias:@stdlib/ndarray/base/zeros}}( dt, [ 2, 2 ], 'row-major' );
36+
> var out = {{alias}}( x )
37+
<ndarray>[ [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ], [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] ]
38+
39+
See Also
40+
--------
41+

0 commit comments

Comments
 (0)