Skip to content

Commit 50e4a64

Browse files
aayush0325aayush0325
committed
docs: write some docs
1 parent 89b7e76 commit 50e4a64

File tree

7 files changed

+300
-0
lines changed

7 files changed

+300
-0
lines changed

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

+284
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
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+
# dgttrf
22+
23+
> Compute an `LU` factorization of a real tri diagonal matrix `A` using elimination with partial pivoting and row interchanges.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
31+
```
32+
33+
#### dgttrf( N, DL, D, DU, DU2, IPIV )
34+
35+
Computes an `LU` factorization of a real tri diagonal matrix `A` using elimination with partial pivoting and row interchanges.
36+
37+
```javascript
38+
var Float64Array = require( '@stdlib/array/float64' );
39+
var Int32Array = require( '@stdlib/array/int32' );
40+
41+
var DL = new Float64Array( [ 1.0, 1.0 ] );
42+
var D = new Float64Array( [ 2.0, 3.0, 1.0 ] );
43+
var DU = new Float64Array( [ 1.0, 1.0 ] );
44+
var DU2 = new Float64Array( 1 );
45+
var IPIV = new Int32Array( 3 );
46+
47+
dgttrf( 3, DL, D, DU, DU2, IPIV );
48+
// DL => <Float64Array>[ 0.5, 0.4 ]
49+
// D => <Float64Array>[ 2, 2.5, 0.6 ]
50+
// DU => <Float64Array>[ 1, 1 ]
51+
// DU2 => <Float64Array>[ 0 ]
52+
// IPIV => <Int32Array>[ 0, 1, 2 ]
53+
```
54+
55+
The function has the following parameters:
56+
57+
- **N**: order of matrix `A`.
58+
- **DL**: the sub diagonall elements of `A` as a [`Float64Array`][mdn-float64array]. On exit, DL is overwritten by the multipliers that define the matrix `L` from the `LU` factorization of `A`.
59+
- **D**: the diagonal elements of `A` as a [`Float64Array`][mdn-float64array]. On exit, D is overwritten by the diagonal elements of the upper triangular matrix `U` from the `LU` factorization of `A`.
60+
- **DU**: the super diagonal elements of `A` as a [`Float64Array`][mdn-float64array]. On exit, DU is overwritten by the elements of the first super-diagonal of `U`.
61+
- **DU2**: On exit, DU2 is overwritten by the elements of the second super-diagonal of `U` as a [`Float64Array`][mdn-float64array].
62+
- **IPIV**: vector of pivot indices as a [`Int32Array`][mdn-int32array].
63+
64+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
65+
66+
<!-- eslint-disable stdlib/capitalized-comments -->
67+
68+
```javascript
69+
var Float64Array = require( '@stdlib/array/float64' );
70+
71+
// Initial arrays...
72+
var D0 = new Float64Array( [ 0.0, 4.0, 5.0, 6.0 ] );
73+
var E0 = new Float64Array( [ 0.0, 1.0, 2.0 ] );
74+
75+
// Create offset views...
76+
var D1 = new Float64Array( D0.buffer, D0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
77+
var E1 = new Float64Array( E0.buffer, E0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
78+
79+
dgttrf( 3, D1, E1 );
80+
// D0 => <Float64Array>[ 0.0, 4.0, 4.75, ~5.15789 ]
81+
// E0 => <Float64Array>[ 0.0, 0.25, ~0.4210 ]
82+
```
83+
84+
#### dgttrf.ndarray( N, D, strideD, offsetD, E, strideE, offsetE )
85+
86+
Computes an `LU` factorization of a real tri diagonal matrix `A` using elimination with partial pivoting and row interchanges and alternative indexing semantics.
87+
88+
```javascript
89+
var Float64Array = require( '@stdlib/array/float64' );
90+
var Int32Array = require( '@stdlib/array/int32' );
91+
var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
92+
93+
var DL = new Float64Array( [ 1.0, 1.0 ] );
94+
var D = new Float64Array( [ 2.0, 3.0, 1.0 ] );
95+
var DU = new Float64Array( [ 1.0, 1.0 ] );
96+
var DU2 = new Float64Array( 1 );
97+
var IPIV = new Int32Array( 3 );
98+
99+
dgttrf.ndarray( 3, DL, 1, 0, D, 1, 0, DU, 1, 0, DU2, 1, 0, IPIV, 1, 0 );
100+
// DL => <Float64Array>[ 0.5, 0.4 ]
101+
// D => <Float64Array>[ 2, 2.5, 0.6 ]
102+
// DU => <Float64Array>[ 1, 1 ]
103+
// DU2 => <Float64Array>[ 0 ]
104+
// IPIV => <Int32Array>[ 0, 1, 2 ]
105+
```
106+
107+
The function has the following additional parameters:
108+
109+
- **strideD**: stride length for `D`.
110+
- **offsetD**: starting index for `D`.
111+
- **strideE**: stride length for `E`.
112+
- **offsetE**: starting index for `E`.
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 Float64Array = require( '@stdlib/array/float64' );
120+
121+
var D = new Float64Array( [ 0.0, 4.0, 5.0, 6.0 ] );
122+
var E = new Float64Array( [ 0.0, 1.0, 2.0 ] );
123+
124+
dgttrf.ndarray( 3, D, 1, 1, E, 1, 1 );
125+
// D => <Float64Array>[ 0.0, 4.0, 4.75, ~5.15789 ]
126+
// E => <Float64Array>[ 0.0, 0.25, ~0.4210 ]
127+
```
128+
129+
</section>
130+
131+
<!-- /.usage -->
132+
133+
<section class="notes">
134+
135+
## Notes
136+
137+
- Both functions mutate the input arrays `DL`, `D`, `DU`, `DU2` and `IPIV`.
138+
139+
- Both functions return a status code indicating success or failure. A status code indicates the following conditions:
140+
141+
- `0`: factorization was successful.
142+
- `<0`: the k-th argument had an illegal value, where `-k` equals the status code value.
143+
- `>0`: `U( k, k )` is exactly zero the factorization has been completed, but the factor `U` is exactly singular, and division
144+
by zero will occur if it is used to solve a system of equations, where `k` equals the status code value.
145+
146+
- `dgttrf()` corresponds to the [LAPACK][LAPACK] routine [`dgttrf`][lapack-dgttrf].
147+
148+
</section>
149+
150+
<!-- /.notes -->
151+
152+
<section class="examples">
153+
154+
## Examples
155+
156+
<!-- eslint no-undef: "error" -->
157+
158+
```javascript
159+
var Int32Array = require( '@stdlib/array/int32' );
160+
var Float64Array = require( '@stdlib/array/float64' );
161+
var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
162+
163+
var N = 9;
164+
165+
var DL = new Float64Array( [ 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0 ] );
166+
167+
var D = new Float64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
168+
169+
var DU = new Float64Array( [ 4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0 ] );
170+
171+
var DU2 = new Float64Array( N-2 );
172+
173+
var IPIV = new Int32Array( N );
174+
175+
// Perform the `A = LU` factorization:
176+
var info = dgttrf( N, DL, D, DU, DU2, IPIV );
177+
178+
console.log( DL );
179+
console.log( D );
180+
console.log( DU );
181+
console.log( DU2 );
182+
console.log( IPIV );
183+
console.log( info );
184+
```
185+
186+
</section>
187+
188+
<!-- /.examples -->
189+
190+
<!-- C interface documentation. -->
191+
192+
* * *
193+
194+
<section class="c">
195+
196+
## C APIs
197+
198+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
199+
200+
<section class="intro">
201+
202+
</section>
203+
204+
<!-- /.intro -->
205+
206+
<!-- C usage documentation. -->
207+
208+
<section class="usage">
209+
210+
### Usage
211+
212+
```c
213+
TODO
214+
```
215+
216+
#### TODO
217+
218+
TODO.
219+
220+
```c
221+
TODO
222+
```
223+
224+
TODO
225+
226+
```c
227+
TODO
228+
```
229+
230+
</section>
231+
232+
<!-- /.usage -->
233+
234+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
235+
236+
<section class="notes">
237+
238+
</section>
239+
240+
<!-- /.notes -->
241+
242+
<!-- C API usage examples. -->
243+
244+
<section class="examples">
245+
246+
### Examples
247+
248+
```c
249+
TODO
250+
```
251+
252+
</section>
253+
254+
<!-- /.examples -->
255+
256+
</section>
257+
258+
<!-- /.c -->
259+
260+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
261+
262+
<section class="related">
263+
264+
</section>
265+
266+
<!-- /.related -->
267+
268+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
269+
270+
<section class="links">
271+
272+
[lapack]: https://www.netlib.org/lapack/explore-html/
273+
274+
[lapack-dgttrf]: https://www.netlib.org/lapack/explore-html/d6/d46/group__gttrf_ga8d1e46216e6c861c89bd4328b8be52a1.html#ga8d1e46216e6c861c89bd4328b8be52a1
275+
276+
[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
277+
278+
[mdn-int32array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
279+
280+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
281+
282+
</section>
283+
284+
<!-- /.links -->

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

+6
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@
6363
<Float64Array>[ 1, 1 ]
6464
> DU2
6565
<Float64Array>[ 0 ]
66+
> IPIV
67+
<Int32Array>[ 0, 1, 2 ]
6668

6769
// Using typed array views:
6870
> var DL0 = new {{alias:@stdlib/array/float64}}( [ 0.0, 1.0, 1.0 ] );
@@ -83,6 +85,8 @@
8385
<Float64Array>[ 1, 1 ]
8486
> DU2
8587
<Float64Array>[ 0 ]
88+
> IPIV
89+
<Int32Array>[ 0, 1, 2 ]
8690

8791

8892
{{alias}}.ndarray( N,DL,sdl,odl,D,sd,od,DU,sdu,odu,DU2,sdu2,odu2,IPIV,si,oi )
@@ -181,6 +185,8 @@
181185
<Float64Array>[ 1, 1 ]
182186
> DU2
183187
<Float64Array>[ 0 ]
188+
> IPIV
189+
<Int32Array>[ 0, 1, 2 ]
184190

185191
See Also
186192
--------

‎lib/node_modules/@stdlib/lapack/base/dgttrf/docs/types/index.d.ts

+4
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ interface Routine {
6161
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
6262
* // DU => <Float64Array>[ 1, 1 ]
6363
* // DU2 => <Float64Array>[ 0 ]
64+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
6465
*/
6566
( N: number, DL: Float64Array, D: Float64Array, DU: Float64Array, DU2: Float64Array, IPIV: Int32Array ): StatusCode;
6667

@@ -97,6 +98,7 @@ interface Routine {
9798
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
9899
* // DU => <Float64Array>[ 1, 1 ]
99100
* // DU2 => <Float64Array>[ 0 ]
101+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
100102
*/
101103
ndarray( N: number, DL: Float64Array, sdl: number, odl: number, D: Float64Array, sd: number, od: number, DU: Float64Array, sdu: number, odu: number, DU2: Float64Array, sdu2: number, odu2: number, IPIV: Int32Array, si: number, oi: number ): StatusCode;
102104
}
@@ -127,6 +129,7 @@ interface Routine {
127129
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
128130
* // DU => <Float64Array>[ 1, 1 ]
129131
* // DU2 => <Float64Array>[ 0 ]
132+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
130133
*
131134
* @example
132135
* var Float64Array = require( '@stdlib/array/float64' );
@@ -143,6 +146,7 @@ interface Routine {
143146
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
144147
* // DU => <Float64Array>[ 1, 1 ]
145148
* // DU2 => <Float64Array>[ 0 ]
149+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
146150
*/
147151
declare var dgttrf: Routine;
148152

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

+1
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ var DU2 = new Float64Array( N-2 );
3434

3535
var IPIV = new Int32Array( N );
3636

37+
// Perform the `A = LU` factorization:
3738
var info = dgttrf( N, DL, D, DU, DU2, IPIV );
3839

3940
console.log( DL );

‎lib/node_modules/@stdlib/lapack/base/dgttrf/lib/base.js

+1
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ var abs = require( '@stdlib/math/base/special/abs' );
6262
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
6363
* // DU => <Float64Array>[ 1, 1 ]
6464
* // DU2 => <Float64Array>[ 0 ]
65+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
6566
*/
6667
function dgttrf( N, DL, sdl, odl, D, sd, od, DU, sdu, odu, DU2, sdu2, odu2, IPIV, si, oi ) { // eslint-disable-line max-len, max-params
6768
var fact;

‎lib/node_modules/@stdlib/lapack/base/dgttrf/lib/index.js

+3
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
*
2626
* @example
2727
* var Float64Array = require( '@stdlib/array/float64' );
28+
* var Int32Array = require( '@stdlib/array/int32' );
2829
* var dgttrf = require( '@stdlib/lapack/base/dgttrf' );
2930
*
3031
* var DL = new Float64Array( [ 1.0, 1.0 ] );
@@ -38,6 +39,7 @@
3839
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
3940
* // DU => <Float64Array>[ 1, 1 ]
4041
* // DU2 => <Float64Array>[ 0 ]
42+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
4143
*
4244
* @example
4345
* var Float64Array = require( '@stdlib/array/float64' );
@@ -55,6 +57,7 @@
5557
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
5658
* // DU => <Float64Array>[ 1, 1 ]
5759
* // DU2 => <Float64Array>[ 0 ]
60+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
5861
*/
5962

6063
// MODULES //

‎lib/node_modules/@stdlib/lapack/base/dgttrf/lib/ndarray.js

+1
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ var base = require( './base.js' );
6262
* // D => <Float64Array>[ 2, 2.5, 0.6 ]
6363
* // DU => <Float64Array>[ 1, 1 ]
6464
* // DU2 => <Float64Array>[ 0 ]
65+
* // IPIV => <Int32Array>[ 0, 1, 2 ]
6566
*/
6667
function dgttrf( N, DL, sdl, odl, D, sd, od, DU, sdu, odu, DU2, sdu2, odu2, IPIV, si, oi ) { // eslint-disable-line max-len, max-params
6768
if ( N < 0 ) {

0 commit comments

Comments
 (0)