Skip to content

Commit a1a6e5c

Browse files
aayush0325aayush0325
committed
docs: add README
--- 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: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: passed - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---
1 parent c65944e commit a1a6e5c

File tree

1 file changed

+295
-0
lines changed
  • lib/node_modules/@stdlib/lapack/base/zlaswp

1 file changed

+295
-0
lines changed

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

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

0 commit comments

Comments
 (0)