Skip to content

Commit 1dda7d2

Browse files
aman-095kgryte
aman-095
and
kgryte
authored
feat: add blas/base/zcopy
PR-URL: #2064 Ref: #2039 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]> Signed-off-by: Athan Reines <[email protected]>
1 parent bcf0e37 commit 1dda7d2

40 files changed

+5111
-0
lines changed

‎lib/node_modules/@stdlib/blas/base/zcopy/README.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 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+
# zcopy
22+
23+
> Copy values from one complex double-precision floating-point vector to another complex double-precision floating-point vector.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var zcopy = require( '@stdlib/blas/base/zcopy' );
31+
```
32+
33+
#### zcopy( N, x, strideX, y, strideY )
34+
35+
Copies values from `x` into `y`.
36+
37+
```javascript
38+
var Complex128Array = require( '@stdlib/array/complex128' );
39+
var real = require( '@stdlib/complex/real' );
40+
var imag = require( '@stdlib/complex/imag' );
41+
42+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
43+
var y = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
44+
45+
zcopy( x.length, x, 1, y, 1 );
46+
47+
var z = y.get( 0 );
48+
// returns <Complex128>
49+
50+
var re = real( z );
51+
// returns 1.0
52+
53+
var im = imag( z );
54+
// returns 2.0
55+
```
56+
57+
The function has the following parameters:
58+
59+
- **N**: number of indexed elements.
60+
- **x**: input [`Complex128Array`][@stdlib/array/complex128].
61+
- **strideX**: index increment for `x`.
62+
- **y**: destination [`Complex128Array`][@stdlib/array/complex128].
63+
- **strideY**: index increment for `y`.
64+
65+
The `N` and stride parameters determine how values from `x` are copied into `y`. For example, to copy in reverse order every other value in `x` into the first `N` elements of `y`,
66+
67+
```javascript
68+
var Complex128Array = require( '@stdlib/array/complex128' );
69+
var real = require( '@stdlib/complex/real' );
70+
var imag = require( '@stdlib/complex/imag' );
71+
72+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
73+
var y = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
74+
75+
zcopy( 2, x, -2, y, 1 );
76+
77+
var z = y.get( 0 );
78+
// returns <Complex128>
79+
80+
var re = real( z );
81+
// returns 5.0
82+
83+
var im = imag( z );
84+
// returns 6.0
85+
```
86+
87+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
88+
89+
<!-- eslint-disable stdlib/capitalized-comments -->
90+
91+
```javascript
92+
var Complex128Array = require( '@stdlib/array/complex128' );
93+
var real = require( '@stdlib/complex/real' );
94+
var imag = require( '@stdlib/complex/imag' );
95+
96+
// Initial arrays...
97+
var x0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
98+
var y0 = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
99+
100+
// Create offset views...
101+
var x1 = new Complex128Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
102+
var y1 = new Complex128Array( y0.buffer, y0.BYTES_PER_ELEMENT*2 ); // start at 3rd element
103+
104+
// Copy in reverse order every other value from `x1` into `y1`...
105+
zcopy( 2, x1, -2, y1, 1 );
106+
107+
var z = y0.get( 2 );
108+
// returns <Complex128>
109+
110+
var re = real( z );
111+
// returns 7.0
112+
113+
var im = imag( z );
114+
// returns 8.0
115+
```
116+
117+
#### zcopy.ndarray( N, x, strideX, offsetX, y, strideY, offsetY )
118+
119+
Copies values from `x` into `y` using alternative indexing semantics.
120+
121+
```javascript
122+
var Complex128Array = require( '@stdlib/array/complex128' );
123+
var real = require( '@stdlib/complex/real' );
124+
var imag = require( '@stdlib/complex/imag' );
125+
126+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
127+
var y = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
128+
129+
zcopy.ndarray( x.length, x, 1, 0, y, 1, 0 );
130+
131+
var z = y.get( 0 );
132+
// returns <Complex128>
133+
134+
var re = real( z );
135+
// returns 1.0
136+
137+
var im = imag( z );
138+
// returns 2.0
139+
```
140+
141+
The function has the following additional parameters:
142+
143+
- **offsetX**: starting index for `x`.
144+
- **offsetY**: starting index for `y`.
145+
146+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example, to copy every other value in `x` starting from the second value into the last `N` elements in `y` where `x[i] = y[n]`, `x[i+2] = y[n-1]`,...,
147+
148+
```javascript
149+
var Complex128Array = require( '@stdlib/array/complex128' );
150+
var real = require( '@stdlib/complex/real' );
151+
var imag = require( '@stdlib/complex/imag' );
152+
153+
var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
154+
var y = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
155+
156+
zcopy.ndarray( 2, x, 2, 1, y, -1, y.length-1 );
157+
158+
var z = y.get( y.length-1 );
159+
// returns <Complex128>
160+
161+
var re = real( z );
162+
// returns 3.0
163+
164+
var im = imag( z );
165+
// returns 4.0
166+
```
167+
168+
</section>
169+
170+
<!-- /.usage -->
171+
172+
<section class="notes">
173+
174+
## Notes
175+
176+
- If `N <= 0`, both functions return `y` unchanged.
177+
- `zcopy()` corresponds to the [BLAS][blas] level 1 function [`zcopy`][zcopy].
178+
179+
</section>
180+
181+
<!-- /.notes -->
182+
183+
<section class="examples">
184+
185+
## Examples
186+
187+
<!-- eslint no-undef: "error" -->
188+
189+
```javascript
190+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
191+
var filledarrayBy = require( '@stdlib/array/filled-by' );
192+
var Complex128 = require( '@stdlib/complex/float64' );
193+
var zcopy = require( '@stdlib/blas/base/zcopy' );
194+
195+
function rand() {
196+
return new Complex128( discreteUniform( 0, 10 ), discreteUniform( -5, 5 ) );
197+
}
198+
199+
var x = filledarrayBy( 10, 'complex128', rand );
200+
console.log( x.get( 0 ).toString() );
201+
202+
var y = filledarrayBy( 10, 'complex128', rand );
203+
console.log( y.get( 0 ).toString() );
204+
205+
// Copy elements from `x` into `y` starting from the end of `y`:
206+
zcopy( x.length, x, 1, y, -1 );
207+
console.log( y.get( y.length-1 ).toString() );
208+
```
209+
210+
</section>
211+
212+
<!-- /.examples -->
213+
214+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
215+
216+
<section class="links">
217+
218+
[blas]: http://www.netlib.org/blas
219+
220+
[zcopy]: https://www.netlib.org/lapack/explore-html/d5/d2b/group__copy_gaca1a115319081adeb0a9b80ec37ce626.html#gaca1a115319081adeb0a9b80ec37ce626
221+
222+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
223+
224+
[@stdlib/array/complex128]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/complex128
225+
226+
</section>
227+
228+
<!-- /.links -->

‎lib/node_modules/@stdlib/blas/base/zcopy/benchmark/benchmark.js

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 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 uniform = require( '@stdlib/random/array/uniform' );
25+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
26+
var pow = require( '@stdlib/math/base/special/pow' );
27+
var Complex128Array = require( '@stdlib/array/complex128' );
28+
var reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' );
29+
var pkg = require( './../package.json' ).name;
30+
var zcopy = require( './../lib/zcopy.js' );
31+
32+
33+
// VARIABLES //
34+
35+
var options = {
36+
'dtype': 'float64'
37+
};
38+
39+
40+
// FUNCTIONS //
41+
42+
/**
43+
* Creates a benchmark function.
44+
*
45+
* @private
46+
* @param {PositiveInteger} len - array length
47+
* @returns {Function} benchmark function
48+
*/
49+
function createBenchmark( len ) {
50+
var viewY;
51+
var x;
52+
var y;
53+
54+
x = uniform( len*2, -100.0, 100.0, options );
55+
x = new Complex128Array( x.buffer );
56+
57+
y = new Complex128Array( len );
58+
viewY = reinterpret( y, 0 );
59+
60+
return benchmark;
61+
62+
/**
63+
* Benchmark function.
64+
*
65+
* @private
66+
* @param {Benchmark} b - benchmark instance
67+
*/
68+
function benchmark( b ) {
69+
var i;
70+
71+
for ( i = 0; i < len*2; i++ ) {
72+
viewY[ i ] = 0.0;
73+
}
74+
b.tic();
75+
for ( i = 0; i < b.iterations; i++ ) {
76+
zcopy( x.length, x, 1, y, 1 );
77+
if ( isnan( viewY[ i%(len*2) ] ) ) {
78+
b.fail( 'should not return NaN' );
79+
}
80+
}
81+
b.toc();
82+
if ( isnan( viewY[ i%(len*2) ] ) ) {
83+
b.fail( 'should not return NaN' );
84+
}
85+
b.pass( 'benchmark finished' );
86+
b.end();
87+
}
88+
}
89+
90+
91+
// MAIN //
92+
93+
/**
94+
* Main execution sequence.
95+
*
96+
* @private
97+
*/
98+
function main() {
99+
var len;
100+
var min;
101+
var max;
102+
var f;
103+
var i;
104+
105+
min = 1; // 10^min
106+
max = 6; // 10^max
107+
108+
for ( i = min; i <= max; i++ ) {
109+
len = pow( 10, i );
110+
f = createBenchmark( len );
111+
bench( pkg+':len='+len, f );
112+
}
113+
}
114+
115+
main();

0 commit comments

Comments
 (0)