Skip to content

Commit 5e9a3e9

Browse files
rreusserkgrytestdlib-bot
authored
feat: add lapack/base/zlacpy
PR-URL: #4703 Ref: #2464 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]> Co-authored-by: stdlib-bot <[email protected]>
1 parent 59f2160 commit 5e9a3e9

File tree

16 files changed

+2889
-0
lines changed

16 files changed

+2889
-0
lines changed

‎lib/node_modules/@stdlib/lapack/base/zlacpy/README.md

+275
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# zlacpy
22+
23+
> Copy all or part of a matrix `A` to another matrix `B`.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var zlacpy = require( '@stdlib/lapack/base/zlacpy' );
31+
```
32+
33+
#### zlacpy( order, uplo, M, N, A, LDA, B, LDB )
34+
35+
Copies all or part of a matrix `A` to another matrix `B`.
36+
37+
```javascript
38+
var Complex128Array = require( '@stdlib/array/complex128' );
39+
var reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' );
40+
41+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
42+
var B = new Complex128Array( 4 );
43+
44+
zlacpy( 'row-major', 'all', 2, 2, A, 2, B, 2 );
45+
46+
var viewB = reinterpret( B, 0 );
47+
// returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ]
48+
```
49+
50+
The function has the following parameters:
51+
52+
- **order**: storage layout.
53+
- **uplo**: specifies whether to copy the upper or lower triangular/trapezoidal part of a matrix `A`.
54+
- **M**: number of rows in `A`.
55+
- **N**: number of columns in `A`.
56+
- **A**: input [`Complex128Array`][@stdlib/array/complex128].
57+
- **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
58+
- **B**: output [`Complex128Array`][@stdlib/array/complex128].
59+
- **LDB**: stride of the first dimension of `B` (a.k.a., leading dimension of the matrix `B`).
60+
61+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
62+
63+
<!-- eslint-disable stdlib/capitalized-comments, max-len -->
64+
65+
```javascript
66+
var Complex128Array = require( '@stdlib/array/complex128' );
67+
var reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' );
68+
69+
// Initial arrays...
70+
var A0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 ] );
71+
var B0 = new Complex128Array( 5 );
72+
73+
// Create offset views...
74+
var A1 = new Complex128Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
75+
var B1 = new Complex128Array( B0.buffer, B0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
76+
77+
zlacpy( 'row-major', 'all', 2, 2, A1, 2, B1, 2 );
78+
79+
var viewB = reinterpret( B0, 0 );
80+
// returns <Float64Array>[ 0.0, 0.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 ]
81+
```
82+
83+
#### zlacpy.ndarray( uplo, M, N, A, sa1, sa2, oa, B, sb1, sb2, ob )
84+
85+
Copies all or part of a matrix `A` to another matrix `B` using alternative indexing semantics.
86+
87+
```javascript
88+
var Complex128Array = require( '@stdlib/array/complex128' );
89+
var reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' );
90+
91+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
92+
var B = new Complex128Array( 4 );
93+
94+
zlacpy.ndarray( 'all', 2, 2, A, 2, 1, 0, B, 2, 1, 0 );
95+
96+
var viewB = reinterpret( B, 0 );
97+
// returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ]
98+
```
99+
100+
The function has the following parameters:
101+
102+
- **uplo**: specifies whether to copy the upper or lower triangular/trapezoidal part of a matrix `A`.
103+
- **M**: number of rows in `A`.
104+
- **N**: number of columns in `A`.
105+
- **A**: input [`Complex128Array`][@stdlib/array/complex128].
106+
- **sa1**: stride of the first dimension of `A`.
107+
- **sa2**: stride of the second dimension of `A`.
108+
- **oa**: starting index for `A`.
109+
- **B**: output [`Complex128Array`][@stdlib/array/complex128].
110+
- **sb1**: stride of the first dimension of `B`.
111+
- **sb2**: stride of the second dimension of `B`.
112+
- **ob**: starting index for `B`.
113+
114+
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,
115+
116+
<!-- eslint-disable max-len -->
117+
118+
```javascript
119+
var Complex128Array = require( '@stdlib/array/complex128' );
120+
var reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' );
121+
122+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 ] );
123+
var B = new Complex128Array( 6 );
124+
125+
zlacpy.ndarray( 'all', 2, 2, A, 2, 1, 1, B, 2, 1, 2 );
126+
127+
var viewB = reinterpret( B, 0 );
128+
// returns <Float64Array>[ 0.0, 0.0, 0.0, 0.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0 ]
129+
```
130+
131+
</section>
132+
133+
<!-- /.usage -->
134+
135+
<section class="notes">
136+
137+
## Notes
138+
139+
- `zlacpy()` corresponds to the [LAPACK][lapack] routine [`zlacpy`][lapack-zlacpy].
140+
141+
</section>
142+
143+
<!-- /.notes -->
144+
145+
<section class="examples">
146+
147+
## Examples
148+
149+
<!-- eslint no-undef: "error" -->
150+
151+
```javascript
152+
var Complex128Array = require( '@stdlib/array/complex128' );
153+
var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
154+
var uniform = require( '@stdlib/random/array/discrete-uniform' );
155+
var numel = require( '@stdlib/ndarray/base/numel' );
156+
var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
157+
var zlacpy = require( '@stdlib/lapack/base/zlacpy' );
158+
159+
var shape = [ 5, 8 ];
160+
var order = 'row-major';
161+
var strides = shape2strides( shape, order );
162+
163+
var N = numel( shape );
164+
165+
var A = new Complex128Array( uniform( 2*N, -10, 10, {
166+
'dtype': 'generic'
167+
}));
168+
console.log( ndarray2array( A, shape, strides, 0, order ) );
169+
170+
var B = new Complex128Array( uniform( 2*N, -10, 10, {
171+
'dtype': 'generic'
172+
}));
173+
console.log( ndarray2array( B, shape, strides, 0, order ) );
174+
175+
zlacpy( order, 'all', shape[ 0 ], shape[ 1 ], A, strides[ 0 ], B, strides[ 0 ] );
176+
console.log( ndarray2array( B, shape, strides, 0, order ) );
177+
```
178+
179+
</section>
180+
181+
<!-- /.examples -->
182+
183+
<!-- C interface documentation. -->
184+
185+
* * *
186+
187+
<section class="c">
188+
189+
## C APIs
190+
191+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
192+
193+
<section class="intro">
194+
195+
</section>
196+
197+
<!-- /.intro -->
198+
199+
<!-- C usage documentation. -->
200+
201+
<section class="usage">
202+
203+
### Usage
204+
205+
```c
206+
TODO
207+
```
208+
209+
#### TODO
210+
211+
TODO.
212+
213+
```c
214+
TODO
215+
```
216+
217+
TODO
218+
219+
```c
220+
TODO
221+
```
222+
223+
</section>
224+
225+
<!-- /.usage -->
226+
227+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
228+
229+
<section class="notes">
230+
231+
</section>
232+
233+
<!-- /.notes -->
234+
235+
<!-- C API usage examples. -->
236+
237+
<section class="examples">
238+
239+
### Examples
240+
241+
```c
242+
TODO
243+
```
244+
245+
</section>
246+
247+
<!-- /.examples -->
248+
249+
</section>
250+
251+
<!-- /.c -->
252+
253+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
254+
255+
<section class="related">
256+
257+
</section>
258+
259+
<!-- /.related -->
260+
261+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
262+
263+
<section class="links">
264+
265+
[lapack]: https://www.netlib.org/lapack/explore-html/
266+
267+
[lapack-zlacpy]: https://netlib.org/lapack/explore-html/d0/d9e/group__lacpy_ga243f0a47458b9a525136a69146c10192.html#ga243f0a47458b9a525136a69146c10192
268+
269+
[@stdlib/array/complex128]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/complex128
270+
271+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
272+
273+
</section>
274+
275+
<!-- /.links -->

‎lib/node_modules/@stdlib/lapack/base/zlacpy/benchmark/benchmark.js

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

0 commit comments

Comments
 (0)