Skip to content

Commit e7f973d

Browse files
aayush0325kgrytestdlib-bot
authored
feat: add lapack/base/zlaswp
PR-URL: #5496 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]> Co-authored-by: stdlib-bot <[email protected]>
1 parent 27b7e04 commit e7f973d

40 files changed

+4290
-0
lines changed

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

+303
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
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+
# zlaswp
22+
23+
> Perform a series of row interchanges on an input matrix.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var zlaswp = require( '@stdlib/lapack/base/zlaswp' );
31+
```
32+
33+
#### zlaswp( N, A, LDA, k1, k2, IPIV, incx )
34+
35+
Performs a series of row interchanges on an input matrix `A` using pivot indices stored in `IPIV`.
36+
37+
<!-- eslint-disable max-len -->
38+
39+
```javascript
40+
var Int32Array = require( '@stdlib/array/int32' );
41+
var Complex128Array = require( '@stdlib/array/complex128' );
42+
43+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
44+
var IPIV = new Int32Array( [ 2, 0, 1 ] );
45+
46+
zlaswp( 'row-major', 2, A, 2, 0, 2, IPIV, 1 );
47+
// A => <Complex128Array>[ 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
48+
```
49+
50+
The function has the following parameters:
51+
52+
- **order**: storage layout.
53+
- **N**: number of columns in `A`.
54+
- **A**: input matrix stored in linear memory as a [`Complex128Array`][@stdlib/array/complex128].
55+
- **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
56+
- **k1**: index of first row to interchange when `incx` is positive and the index of the last row to interchange when `incx` is negative.
57+
- **k2**: index of last row to interchange when `incx` is positive and the index of the first row to interchange when `incx` is negative.
58+
- **IPIV**: vector of pivot indices as an [`Int32Array`][@stdlib/array/int32]. Must contain at least `k1+(k2-k1)*abs(incx)` elements. Only the elements in positions `k1` through `k1+(k2-k1)*abs(incx)` are accessed.
59+
- **incx**: increment between successive values of `IPIV`. Elements from `IPIV` are accessed according to `IPIV[k1+(k-k1)*abs(incx)] = j`, thus implying that rows `k` and `j` should be interchanged. If `incx` is negative, the pivots are applied in reverse order.
60+
61+
The sign of the increment parameter `incx` determines the order in which pivots are applied. For example, to apply pivots in reverse order,
62+
63+
<!-- eslint-disable max-len -->
64+
65+
```javascript
66+
var Int32Array = require( '@stdlib/array/int32' );
67+
var Complex128Array = require( '@stdlib/array/complex128' );
68+
69+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
70+
var IPIV = new Int32Array( [ 2, 0, 1 ] );
71+
72+
zlaswp( 'row-major', 2, A, 2, 0, 2, IPIV, -1 );
73+
// A => <Complex128Array>[ 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
74+
```
75+
76+
To perform strided access over `IPIV`, provide an `abs(incx)` value greater than one. For example, to access every other element in `IPIV`,
77+
78+
<!-- eslint-disable max-len -->
79+
80+
```javascript
81+
var Int32Array = require( '@stdlib/array/int32' );
82+
var Complex128Array = require( '@stdlib/array/complex128' );
83+
84+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
85+
var IPIV = new Int32Array( [ 2, 999, 0, 999, 1 ] );
86+
87+
zlaswp( 'row-major', 2, A, 2, 0, 2, IPIV, 2 );
88+
// A => <Complex128Array>[ 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
89+
```
90+
91+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
92+
93+
<!-- eslint-disable stdlib/capitalized-comments, max-len -->
94+
95+
```javascript
96+
var Int32Array = require( '@stdlib/array/int32' );
97+
var Complex128Array = require( '@stdlib/array/complex128' );
98+
99+
// Initial arrays...
100+
var A0 = new Complex128Array( [ 0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
101+
var IPIV0 = new Int32Array( [ 0, 2, 0, 1 ] );
102+
103+
// Create offset views...
104+
var A1 = new Complex128Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
105+
var IPIV1 = new Int32Array( IPIV0.buffer, IPIV0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
106+
107+
zlaswp( 'row-major', 2, A1, 2, 0, 2, IPIV1, 1 );
108+
// A0 => <Complex128Array>[ 0.0, 0.0, 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
109+
```
110+
111+
#### zlaswp.ndarray( N, A, sa1, sa2, oa, k1, k2, inck, IPIV, si, oi )
112+
113+
Performs a series of row interchanges on the matrix `A` using pivot indices stored in `IPIV` and alternative indexing semantics.
114+
115+
<!-- eslint-disable max-len -->
116+
117+
```javascript
118+
var Int32Array = require( '@stdlib/array/int32' );
119+
var Complex128Array = require( '@stdlib/array/complex128' );
120+
121+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
122+
var IPIV = new Int32Array( [ 2, 0, 1 ] );
123+
124+
zlaswp.ndarray( 2, A, 2, 1, 0, 0, 2, 1, IPIV, 1, 0 );
125+
// A => <Complex128Array>[ 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
126+
```
127+
128+
The function has the following additional parameters:
129+
130+
- **N**: number of columns in `A`.
131+
- **A**: input matrix stored in linear memory as a [`Complex128Array`][@stdlib/array/complex128].
132+
- **sa1**: stride of the first dimension of `A`.
133+
- **sa2**: stride of the second dimension of `A`.
134+
- **oa**: starting index for `A`.
135+
- **k1**: index of first row to interchange when `inck` is positive and the index of the last row to interchange when `inck` is negative.
136+
- **k2**: index of last row to interchange when `inck` is positive and the index of the first row to interchange when `inck` is negative.
137+
- **inck**: direction in which to apply pivots (-1 to apply pivots in reverse order; otherwise, apply in provided order).
138+
- **IPIV**: vector of pivot indices as an [`Int32Array`][@stdlib/array/int32].
139+
- **si**: index increment for `IPIV`.
140+
- **oi**: starting index for `IPIV`.
141+
142+
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,
143+
144+
<!-- eslint-disable max-len -->
145+
146+
```javascript
147+
var Int32Array = require( '@stdlib/array/int32' );
148+
var Complex128Array = require( '@stdlib/array/complex128' );
149+
150+
var A = new Complex128Array( [ 0.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
151+
var IPIV = new Int32Array( [ 0, 0, 2, 0, 1 ] );
152+
153+
zlaswp.ndarray( 2, A, 2, 1, 2, 0, 2, 1, IPIV, 1, 2 );
154+
// A => <Complex128Array>[ 0.0, 0.0, 0.0, 0.0, 5.0, 6.0, 7.0, 8.0, 1.0, 2.0, 3.0, 4.0, 9.0, 10.0, 11.0, 12.0 ]
155+
```
156+
157+
</section>
158+
159+
<!-- /.usage -->
160+
161+
<section class="notes">
162+
163+
## Notes
164+
165+
- Both functions access `k2-k1+1` elements from `IPIV`.
166+
- While `zlaswp` conflates the order in which pivots are applied with the order in which elements in `IPIV` are accessed, the `ndarray` method delineates control of those behaviors with separate parameters `inck` and `si`.
167+
- `zlaswp()` corresponds to the [LAPACK][LAPACK] level 1 function [`zlaswp`][lapack-zlaswp].
168+
169+
</section>
170+
171+
<!-- /.notes -->
172+
173+
<section class="examples">
174+
175+
## Examples
176+
177+
<!-- eslint-disable max-len -->
178+
179+
<!-- eslint no-undef: "error" -->
180+
181+
```javascript
182+
var Complex128Array = require( '@stdlib/array/complex128' );
183+
var Int32Array = require( '@stdlib/array/int32' );
184+
var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
185+
var zlaswp = require( '@stdlib/lapack/base/zlaswp' );
186+
187+
// Specify matrix meta data:
188+
var shape = [ 4, 2 ];
189+
var strides = [ 1, 4 ];
190+
var offset = 0;
191+
var order = 'column-major';
192+
193+
// Create a matrix stored in linear memory:
194+
var A = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0 ] );
195+
console.log( ndarray2array( A, shape, strides, offset, order ) );
196+
197+
// Define a vector of pivot indices:
198+
var IPIV = new Int32Array( [ 2, 0, 3, 1 ] );
199+
200+
// Interchange rows:
201+
zlaswp( order, shape[ 1 ], A, strides[ 1 ], 0, shape[ 0 ]-1, IPIV, 1 );
202+
console.log( ndarray2array( A, shape, strides, offset, order ) );
203+
```
204+
205+
</section>
206+
207+
<!-- /.examples -->
208+
209+
<!-- C interface documentation. -->
210+
211+
* * *
212+
213+
<section class="c">
214+
215+
## C APIs
216+
217+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
218+
219+
<section class="intro">
220+
221+
</section>
222+
223+
<!-- /.intro -->
224+
225+
<!-- C usage documentation. -->
226+
227+
<section class="usage">
228+
229+
### Usage
230+
231+
```c
232+
TODO
233+
```
234+
235+
#### TODO
236+
237+
TODO.
238+
239+
```c
240+
TODO
241+
```
242+
243+
TODO
244+
245+
```c
246+
TODO
247+
```
248+
249+
</section>
250+
251+
<!-- /.usage -->
252+
253+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
254+
255+
<section class="notes">
256+
257+
</section>
258+
259+
<!-- /.notes -->
260+
261+
<!-- C API usage examples. -->
262+
263+
<section class="examples">
264+
265+
### Examples
266+
267+
```c
268+
TODO
269+
```
270+
271+
</section>
272+
273+
<!-- /.examples -->
274+
275+
</section>
276+
277+
<!-- /.c -->
278+
279+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
280+
281+
<section class="related">
282+
283+
</section>
284+
285+
<!-- /.related -->
286+
287+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
288+
289+
<section class="links">
290+
291+
[lapack]: https://www.netlib.org/lapack/explore-html/
292+
293+
[lapack-zlaswp]: https://www.netlib.org/lapack/explore-html/d1/d7e/group__laswp_ga6c7f83bff7887543bcb6c019e06e131d.html
294+
295+
[@stdlib/array/complex128]: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/%40stdlib/array/complex128
296+
297+
[@stdlib/array/int32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/int32
298+
299+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
300+
301+
</section>
302+
303+
<!-- /.links -->

0 commit comments

Comments
 (0)