Skip to content

Commit 51b8662

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: passed - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - 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 ---
1 parent c86cd76 commit 51b8662

File tree

3 files changed

+319
-1
lines changed

3 files changed

+319
-1
lines changed

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

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
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+
# dgebal
22+
23+
> Balances a general real matrix `A`.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var dgebal = require( '@stdlib/lapack/base/dgebal' );
31+
```
32+
33+
#### dgebal( order, job, N, A, LDA, out, scale )
34+
35+
Balances a general real matrix `A`.
36+
37+
```javascript
38+
var Float64Array = require( '@stdlib/array/float64' );
39+
var Int32Array = require( '@stdlib/array/int32' );
40+
41+
var A = new Float64Array( [ 1.0, 100.0, 0.0, 2.0, 200.0, 0.0, 0.0, 0.0, 3.0 ] );
42+
var out = new Int32Array( 2 );
43+
var scale = new Float64Array( 3 );
44+
45+
/*
46+
A = [
47+
[ 1.0, 100.0, 0.0 ],
48+
[ 2.0, 200.0, 0.0 ],
49+
[ 0.0, 0.0, 3.0 ],
50+
]
51+
*/
52+
53+
dgebal( 'row-major', 'both', 3, A, 3, out, scale );
54+
// A => <Float64Array>[ 1.0, 12.5, 0.0, 16.0, 200.0, 0.0, 0.0, 0.0, 3.0 ]
55+
// out => <Int32Array>[ 0, 1 ]
56+
// scale => <Float64Array>[ 8.0, 1.0, 2.0 ]
57+
```
58+
59+
The function has the following parameters:
60+
61+
- **order**: storage layout.
62+
- **job**: indicates the operations to be performed. The `job` parameter can be one of the following. `none` (do nothing), `permute` (permute only), `scale` (scale only) and `both` (both permute and scale).
63+
- **N**: number of row/columns in `A`.
64+
- **A**: input [`Float64Array`][mdn-float64array].
65+
- **LDA**: stride of the first dimension of `A` (a.k.a., leading dimension of the matrix `A`).
66+
- **out**: stores the first and last row/column of the balanced submatrix as a [`Int32Array`][mdn-int32array].
67+
- **scale**: scale factors are stored in the `scale` array as a [`Float64Array`][mdn-float64array]. Where the indices `0` to `out[ 0 ] - 1` and `out[ 1 ] + 1` to `N-1` contain the index of the interchanged row/column (zero based), and the indices `out[ 0 ]` to `out[ 1 ]` contains the scaling factor applied.
68+
69+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
70+
71+
<!-- eslint-disable stdlib/capitalized-comments, max-len -->
72+
73+
```javascript
74+
var Float64Array = require( '@stdlib/array/float64' );
75+
var Int32Array = require( '@stdlib/array/int32' );
76+
77+
// Initial arrays...
78+
var A0 = new Float64Array( [ 0.0, 1.0, 100.0, 0.0, 2.0, 200.0, 0.0, 0.0, 0.0, 3.0 ] );
79+
var out0 = new Int32Array( 3 );
80+
var scale0 = new Float64Array( 4 );
81+
82+
// Create offset views...
83+
var A1 = new Float64Array( A0.buffer, A0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
84+
var out1 = new Int32Array( out0.buffer, out0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
85+
var scale1 = new Float64Array( scale0.buffer, scale0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
86+
87+
/*
88+
A = [
89+
[ 1.0, 100.0, 0.0 ],
90+
[ 2.0, 200.0, 0.0 ],
91+
[ 0.0, 0.0, 3.0 ],
92+
]
93+
*/
94+
95+
dgebal( 'row-major', 'both', 3, A1, 3, out1, scale1 );
96+
// A0 => <Float64Array>[ 0.0, 1.0, 12.5, 0.0, 16.0, 200.0, 0.0, 0.0, 0.0, 3.0 ]
97+
// out0 => <Int32Array>[ 0, 0, 1 ]
98+
// scale0 => <Float64Array>[ 0.0, 8.0, 1.0, 2.0 ]
99+
```
100+
101+
#### dgebal.ndarray( uplo, M, N, A, sa1, sa2, oa, B, sb1, sb2, ob )
102+
103+
Balances a general real matrix `A` using alternative indexing semantics.
104+
105+
```javascript
106+
var Float64Array = require( '@stdlib/array/float64' );
107+
var Int32Array = require( '@stdlib/array/int32' );
108+
109+
var A = new Float64Array( [ 1.0, 100.0, 0.0, 2.0, 200.0, 0.0, 0.0, 0.0, 3.0 ] );
110+
var out = new Int32Array( 2 );
111+
var scale = new Float64Array( 3 );
112+
113+
/*
114+
A = [
115+
[ 1.0, 100.0, 0.0 ],
116+
[ 2.0, 200.0, 0.0 ],
117+
[ 0.0, 0.0, 3.0 ],
118+
]
119+
*/
120+
121+
dgebal.ndarray( 'both', 3, A, 3, 1, 0, out, 1, 0, scale, 1, 0 );
122+
// A => <Float64Array>[ 1.0, 12.5, 0.0, 16.0, 200.0, 0.0, 0.0, 0.0, 3.0 ]
123+
// out => <Int32Array>[ 0, 1 ]
124+
// scale => <Float64Array>[ 8.0, 1.0, 2.0 ]
125+
```
126+
127+
The function has the following parameters:
128+
129+
- **job**: indicates the operations to be performed. The `job` parameter can be one of the following. `none` (do nothing), `permute` (permute only), `scale` (scale only) and `both` (both permute and scale).
130+
- **N**: number of row/columns in `A`.
131+
- **A**: input [`Float64Array`][mdn-float64array].
132+
- **strideA1**: stride of the first dimension of `A`.
133+
- **strideA2**: stride of the second dimension of `A`.
134+
- **offsetA**: starting index for `A`.
135+
- **out**: stores the first and last row/column of the balanced submatrix as a [`Int32Array`][mdn-int32array].
136+
- **strideOut**: stride length of `out`.
137+
- **offsetOut**: starting index for `out`.
138+
- **scale**: scale factors are stored in the `scale` array as a [`Float64Array`][mdn-float64array]. Where the indices `0` to `out[ 0 ] - 1` and `out[ 1 ] + 1` to `N-1` contain the index of the interchanged row/column (zero based), and the indices `out[ 0 ]` to `out[ 1 ]` contains the scaling factor applied.
139+
- **strideScale**: stride length for `scale`.
140+
- **offsetScale**: starting index for `scale`.
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 Float64Array = require( '@stdlib/array/float64' );
148+
var Int32Array = require( '@stdlib/array/int32' );
149+
150+
var A = new Float64Array( [ 0.0, 1.0, 100.0, 0.0, 2.0, 200.0, 0.0, 0.0, 0.0, 3.0 ] );
151+
var out = new Int32Array( 3 );
152+
var scale = new Float64Array( 4 );
153+
154+
/*
155+
A = [
156+
[ 1.0, 100.0, 0.0 ],
157+
[ 2.0, 200.0, 0.0 ],
158+
[ 0.0, 0.0, 3.0 ],
159+
]
160+
*/
161+
162+
dgebal.ndarray( 'both', 3, A, 3, 1, 1, out, 1, 1, scale, 1, 1 );
163+
// A => <Float64Array>[ 0.0, 1.0, 12.5, 0.0, 16.0, 200.0, 0.0, 0.0, 0.0, 3.0 ]
164+
// out => <Int32Array>[ 0, 0, 1 ]
165+
// scale => <Float64Array>[ 0.0, 8.0, 1.0, 2.0 ]
166+
```
167+
168+
</section>
169+
170+
<!-- /.usage -->
171+
172+
<section class="notes">
173+
174+
## Notes
175+
176+
- `dgebal()` corresponds to the [LAPACK][lapack] routine [`dgebal`][lapack-dgebal].
177+
178+
</section>
179+
180+
<!-- /.notes -->
181+
182+
<section class="examples">
183+
184+
## Examples
185+
186+
<!-- eslint no-undef: "error" -->
187+
188+
```javascript
189+
var Float64Array = require( '@stdlib/array/float64' );
190+
var Int32Array = require( '@stdlib/array/int32' );
191+
var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
192+
var dgebal = require( '@stdlib/lapack/base/dgebal' );
193+
194+
// Specify matrix meta data:
195+
var shape = [ 3, 3 ];
196+
var strides = [ 3, 1 ];
197+
var offset = 0;
198+
var order = 'row-major';
199+
200+
// Create a matrix stored in linear memory:
201+
var A = new Float64Array( [ 1.0, 100.0, 0.0, 2.0, 200.0, 0.0, 0.0, 0.0, 3.0 ] );
202+
console.log( ndarray2array( A, shape, strides, offset, order ) );
203+
204+
// Define arrays to store the scaling factors
205+
var out = new Int32Array( 2 );
206+
var scale = new Float64Array( 3 );
207+
208+
// Permute and scale the matrix:
209+
dgebal( order, 'both', shape[ 0 ], A, strides[ 0 ], out, scale );
210+
211+
console.log( ndarray2array( A, shape, strides, offset, order ) );
212+
console.log( out );
213+
console.log( scale );
214+
```
215+
216+
</section>
217+
218+
<!-- /.examples -->
219+
220+
<!-- C interface documentation. -->
221+
222+
* * *
223+
224+
<section class="c">
225+
226+
## C APIs
227+
228+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
229+
230+
<section class="intro">
231+
232+
</section>
233+
234+
<!-- /.intro -->
235+
236+
<!-- C usage documentation. -->
237+
238+
<section class="usage">
239+
240+
### Usage
241+
242+
```c
243+
TODO
244+
```
245+
246+
#### TODO
247+
248+
TODO.
249+
250+
```c
251+
TODO
252+
```
253+
254+
TODO
255+
256+
```c
257+
TODO
258+
```
259+
260+
</section>
261+
262+
<!-- /.usage -->
263+
264+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
265+
266+
<section class="notes">
267+
268+
</section>
269+
270+
<!-- /.notes -->
271+
272+
<!-- C API usage examples. -->
273+
274+
<section class="examples">
275+
276+
### Examples
277+
278+
```c
279+
TODO
280+
```
281+
282+
</section>
283+
284+
<!-- /.examples -->
285+
286+
</section>
287+
288+
<!-- /.c -->
289+
290+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
291+
292+
<section class="related">
293+
294+
</section>
295+
296+
<!-- /.related -->
297+
298+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
299+
300+
<section class="links">
301+
302+
[lapack]: https://www.netlib.org/lapack/explore-html/
303+
304+
[lapack-dgebal]: https://www.netlib.org/lapack/explore-html-3.6.1/dd/d9a/group__double_g_ecomputational_ga411292dd693c20ff9c27650fb7bddf85.html
305+
306+
[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
307+
308+
[mdn-int32array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
309+
310+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
311+
312+
</section>
313+
314+
<!-- /.links -->

‎lib/node_modules/@stdlib/lapack/base/dgebal/docs/repl.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
matrix `A`).
3434

3535
out: Int32Array
36-
Output matrix `out`.
36+
Output matrix `out`. Stores the first and last row/column of the
37+
balanced submatrix.
3738

3839
scale: Float64Array
3940
Array containing permutation and scaling information.

‎lib/node_modules/@stdlib/lapack/base/dgebal/examples/index.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,4 +39,7 @@ var scale = new Float64Array( 3 );
3939

4040
// Permute and scale the matrix:
4141
dgebal( order, 'both', shape[ 0 ], A, strides[ 0 ], out, scale );
42+
4243
console.log( ndarray2array( A, shape, strides, offset, order ) );
44+
console.log( out );
45+
console.log( scale );

0 commit comments

Comments
 (0)