Skip to content

Commit 600710a

Browse files
aayush0325aayush0325
committed
docs: update docs
--- 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: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - 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: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent efbae24 commit 600710a

File tree

7 files changed

+322
-14
lines changed

7 files changed

+322
-14
lines changed

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

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
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+
# dlartg
22+
23+
> LAPACK routine to construct a Givens rotation of a two-dimensional vector that zeros out the second component.
24+
25+
<section class="intro">
26+
27+
`dlartg` constructs a Givens rotation for a two-dimensional vector such that the following equation is satisfied:
28+
29+
30+
<!-- <equation class="equation" label="eq:givens_rotation" align="center" raw="\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}
31+
" alt="Equation for Givens rotation."> -->
32+
33+
```math
34+
\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}
35+
```
36+
37+
<!-- </equation> -->
38+
39+
where `C` represents the cosine of the rotation `S` represents the sine of the rotation and `R` represents the length of the vector after rotation.
40+
41+
</section>
42+
43+
<!-- /.intro -->
44+
45+
<section class="usage">
46+
47+
## Usage
48+
49+
```javascript
50+
var dlartg = require( '@stdlib/lapack/base/dlartg' );
51+
```
52+
53+
#### dlartg( F, G, C, S, R )
54+
55+
Constructs a Givens rotation of a two-dimensional vector that zeros out the second component. For a two-dimensional vector `( F, G )` it computes the sine `S`, cosine `C` and the resultant `R`.
56+
57+
```javascript
58+
var Float64Array = require( '@stdlib/array/float64' );
59+
60+
var F = new Float64Array( [ 3.0 ] );
61+
var G = new Float64Array( [ 4.0 ] );
62+
var C = new Float64Array( 1 );
63+
var S = new Float64Array( 1 );
64+
var R = new Float64Array( 1 );
65+
66+
dlartg( F, G, C, S, R );
67+
// R => <Float64Array>[ 5.0 ]
68+
// C => <Float64Array>[ 0.6 ]
69+
// S => <Float64Array>[ 0.8 ]
70+
```
71+
72+
The function has the following parameters:
73+
74+
- **F**: single element array representing the first component of the vector to be rotated as a [`Float64Array`][mdn-float64array].
75+
- **G**: single element array representing the second component of the vector to be rotated as a [`Float64Array`][mdn-float64array].
76+
- **C**: single element array overwritten by the cosine of the rotation as a [`Float64Array`][mdn-float64array].
77+
- **S**: single element array overwritten by the sine of the rotation as a [`Float64Array`][mdn-float64array].
78+
- **R**: single element array overwritten by the length of the rotated vector as a [`Float64Array`][mdn-float64array].
79+
80+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
81+
82+
<!-- eslint-disable stdlib/capitalized-comments -->
83+
84+
```javascript
85+
var Float64Array = require( '@stdlib/array/float64' );
86+
87+
// Initial arrays...
88+
var F0 = new Float64Array( [ 0.0, 3.0 ] );
89+
var G0 = new Float64Array( [ 0.0, 4.0 ] );
90+
var C0 = new Float64Array( [ 0.0, 0.0 ] );
91+
var S0 = new Float64Array( [ 0.0, 0.0 ] );
92+
var R0 = new Float64Array( [ 0.0, 0.0 ] );
93+
94+
// Create offset views...
95+
var F1 = new Float64Array( F0.buffer, F0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
96+
var G1 = new Float64Array( G0.buffer, G0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
97+
var C1 = new Float64Array( C0.buffer, C0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
98+
var S1 = new Float64Array( S0.buffer, S0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
99+
var R1 = new Float64Array( R0.buffer, R0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
100+
101+
dlartg( F1, G1, C1, S1, R1 );
102+
// R0 => <Float64Array>[ 0.0, 5.0 ]
103+
// C0 => <Float64Array>[ 0.0, 0.6 ]
104+
// S0 => <Float64Array>[ 0.0, 0.8 ]
105+
```
106+
107+
#### dlartg.ndarray( F, offsetF, G, offsetG, C, offsetC, S, offsetS, R, offsetR )
108+
109+
Constructs a Givens rotation of a two-dimensional vector that zeros out the second component, using alternative indexing semantics. For a two-dimensional vector `( F, G )` it computes the sine `S`, cosine `C` and the resultant `R`.
110+
111+
```javascript
112+
var Float64Array = require( '@stdlib/array/float64' );
113+
114+
var F = new Float64Array( [ 3.0 ] );
115+
var G = new Float64Array( [ 4.0 ] );
116+
var C = new Float64Array( 1 );
117+
var S = new Float64Array( 1 );
118+
var R = new Float64Array( 1 );
119+
120+
dlartg.ndarray( F, 0, G, 0, C, 0, S, 0, R, 0 );
121+
// R => <Float64Array>[ 5.0 ]
122+
// C => <Float64Array>[ 0.6 ]
123+
// S => <Float64Array>[ 0.8 ]
124+
```
125+
126+
The function has the following parameters:
127+
128+
- **F**: single element array representing the first component of the vector to be rotated as a [`Float64Array`][mdn-float64array].
129+
- **offsetF**: starting index for `F`.
130+
- **G**: single element array representing the second component of the vector to be rotated as a [`Float64Array`][mdn-float64array].
131+
- **offsetG**: starting index for `G`.
132+
- **C**: single element array overwritten by the cosine of the rotation as a [`Float64Array`][mdn-float64array].
133+
- **offsetC**: starting index for `C`.
134+
- **S**: single element array overwritten by the sine of the rotation as a [`Float64Array`][mdn-float64array].
135+
- **offsetS**: starting index for `S`.
136+
- **R**: single element array overwritten by the length of the rotated vector as a [`Float64Array`][mdn-float64array].
137+
- **offsetR**: starting index for `R`.
138+
139+
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,
140+
141+
<!-- eslint-disable max-len -->
142+
143+
```javascript
144+
var Float64Array = require( '@stdlib/array/float64' );
145+
146+
var F = new Float64Array( [ 0.0, 3.0 ] );
147+
var G = new Float64Array( [ 0.0, 4.0 ] );
148+
var C = new Float64Array( 2 );
149+
var S = new Float64Array( 2 );
150+
var R = new Float64Array( 2 );
151+
152+
dlartg.ndarray( F, 1, G, 1, C, 1, S, 1, R, 1 );
153+
// R => <Float64Array>[ 0.0, 5.0 ]
154+
// C => <Float64Array>[ 0.0, 0.6 ]
155+
// S => <Float64Array>[ 0.0, 0.8 ]
156+
```
157+
158+
</section>
159+
160+
<!-- /.usage -->
161+
162+
<section class="notes">
163+
164+
## Notes
165+
166+
- `dlartg()` corresponds to the [LAPACK][LAPACK] function [`dlartg`][lapack-dlartg].
167+
168+
</section>
169+
170+
<!-- /.notes -->
171+
172+
<section class="examples">
173+
174+
## Examples
175+
176+
<!-- eslint no-undef: "error" -->
177+
178+
```javascript
179+
var Float64Array = require( '@stdlib/array/float64' );
180+
var uniform = require( '@stdlib/random/array/uniform' );
181+
var dlartg = require( '@stdlib/lapack/base/dlartg' );
182+
183+
var F = uniform( 1, -10.0, 10.0 );
184+
var G = uniform( 1, -10.0, 10.0 );
185+
var C = new Float64Array( 1 );
186+
var S = new Float64Array( 1 );
187+
var R = new Float64Array( 1 );
188+
189+
dlartg( F, G, C, S, R );
190+
191+
console.log( C );
192+
console.log( S );
193+
console.log( R );
194+
```
195+
196+
</section>
197+
198+
<!-- /.examples -->
199+
200+
<!-- C interface documentation. -->
201+
202+
* * *
203+
204+
<section class="c">
205+
206+
## C APIs
207+
208+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
209+
210+
<section class="intro">
211+
212+
</section>
213+
214+
<!-- /.intro -->
215+
216+
<!-- C usage documentation. -->
217+
218+
<section class="usage">
219+
220+
### Usage
221+
222+
```c
223+
TODO
224+
```
225+
226+
#### TODO
227+
228+
TODO.
229+
230+
```c
231+
TODO
232+
```
233+
234+
TODO
235+
236+
```c
237+
TODO
238+
```
239+
240+
</section>
241+
242+
<!-- /.usage -->
243+
244+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
245+
246+
<section class="notes">
247+
248+
</section>
249+
250+
<!-- /.notes -->
251+
252+
<!-- C API usage examples. -->
253+
254+
<section class="examples">
255+
256+
### Examples
257+
258+
```c
259+
TODO
260+
```
261+
262+
</section>
263+
264+
<!-- /.examples -->
265+
266+
</section>
267+
268+
<!-- /.c -->
269+
270+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
271+
272+
<section class="related">
273+
274+
</section>
275+
276+
<!-- /.related -->
277+
278+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
279+
280+
<section class="links">
281+
282+
[lapack]: https://www.netlib.org/lapack/explore-html/
283+
284+
[lapack-dlartg]: https://netlib.org/lapack/explore-html/da/dd3/group__lartg_ga86f8f877eaea0386cdc2c3c175d9ea88.html#ga86f8f877eaea0386cdc2c3c175d9ea88
285+
286+
[mdn-float64array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
287+
288+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
289+
290+
</section>
291+
292+
<!-- /.links -->

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

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@
2323
*/
2424
interface Routine {
2525
/**
26-
* Generates a plane rotation of a vector such that the following equation is satisfied.
26+
* Constructs a Givens rotation of a two-dimensional vector that zeros out the second component.
27+
*
28+
* For a two-dimensional vector ( f, g ) it computes the sine `S`, cosine `C` and the resultant `R` such that the following equation is satisfied:
2729
*
2830
* ```tex
2931
* \(\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}\)
@@ -33,7 +35,7 @@ interface Routine {
3335
* @param G - single element array representing the second component of the vector to be rotated
3436
* @param C - single element array overwritten by the cosine of the rotation
3537
* @param S - single element array overwritten by the sine of the rotation
36-
* @param R - single element array overwritten by the non-zero component of the rotated vector
38+
* @param R - single element array overwritten by the length of the rotated vector
3739
* @returns {void}
3840
*
3941
* @example
@@ -53,7 +55,9 @@ interface Routine {
5355
( F: Float64Array, G: Float64Array, C: Float64Array, S: Float64Array, R: Float64Array ): void;
5456

5557
/**
56-
* Generates a plane rotation of a vector using alternative indexing semantics such that the following equation is satisfied.
58+
* Constructs a Givens rotation of a two-dimensional vector that zeros out the second component.
59+
*
60+
* For a two-dimensional vector ( f, g ) it computes the sine `S`, cosine `C` and the resultant `R` such that the following equation is satisfied:
5761
*
5862
* ```tex
5963
* \(\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}\)
@@ -67,7 +71,7 @@ interface Routine {
6771
* @param offsetC - starting index for `C`
6872
* @param S - single element array overwritten by the sine of the rotation
6973
* @param offsetS - starting index for `S`
70-
* @param R - single element array overwritten by the non-zero component of the rotated vector
74+
* @param R - single element array overwritten by the length of the rotated vector
7175
* @param offsetR - starting index for `R`
7276
* @returns {void}
7377
*
@@ -89,7 +93,9 @@ interface Routine {
8993
}
9094

9195
/**
92-
* Generates a plane rotation of a vector such that the following equation is satisfied.
96+
* Constructs a Givens rotation of a two-dimensional vector that zeros out the second component.
97+
*
98+
* For a two-dimensional vector ( f, g ) it computes the sine `S`, cosine `C` and the resultant `R` such that the following equation is satisfied:
9399
*
94100
* ```tex
95101
* \(\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}\)
@@ -99,7 +105,7 @@ interface Routine {
99105
* @param G - single element array representing the second component of the vector to be rotated
100106
* @param C - single element array overwritten by the cosine of the rotation
101107
* @param S - single element array overwritten by the sine of the rotation
102-
* @param R - single element array overwritten by the non-zero component of the rotated vector
108+
* @param R - single element array overwritten by the length of the rotated vector
103109
* @returns {void}
104110
*
105111
* @example

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,9 @@ var rtmax = sqrt( safmax / 2.0 );
3939
// MAIN //
4040

4141
/**
42-
* Generates a plane rotation of a vector such that the following equation is satisfied.
42+
* Constructs a Givens rotation of a two-dimensional vector that zeros out the second component.
43+
*
44+
* For a two-dimensional vector ( f, g ) it computes the sine `S`, cosine `C` and the resultant `R` such that the following equation is satisfied:
4345
*
4446
* ```tex
4547
* \(\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}\)
@@ -54,7 +56,7 @@ var rtmax = sqrt( safmax / 2.0 );
5456
* @param {NonNegativeInteger} offsetC - starting index for `C`
5557
* @param {Float64Array} S - single element array overwritten by the sine of the rotation
5658
* @param {NonNegativeInteger} offsetS - starting index for `S`
57-
* @param {Float64Array} R - single element array overwritten by the non-zero component of the rotated vector
59+
* @param {Float64Array} R - single element array overwritten by the length of the rotated vector
5860
* @param {NonNegativeInteger} offsetR - starting index for `R`
5961
* @returns {void}
6062
*

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,9 @@ var base = require( './base.js' );
2626
// MAIN //
2727

2828
/**
29-
* Generates a plane rotation of a vector such that the following equation is satisfied.
29+
* Constructs a Givens rotation of a two-dimensional vector that zeros out the second component.
30+
*
31+
* For a two-dimensional vector ( f, g ) it computes the sine `S`, cosine `C` and the resultant `R` such that the following equation is satisfied:
3032
*
3133
* ```tex
3234
* \(\begin{bmatrix} C & S \\ -S & C \end{bmatrix} \begin{bmatrix} F \\ G \end{bmatrix} = \begin{bmatrix} R \\ 0 \end{bmatrix}\)
@@ -36,7 +38,7 @@ var base = require( './base.js' );
3638
* @param {Float64Array} G - single element array representing the second component of the vector to be rotated
3739
* @param {Float64Array} C - single element array overwritten by the cosine of the rotation
3840
* @param {Float64Array} S - single element array overwritten by the sine of the rotation
39-
* @param {Float64Array} R - single element array overwritten by the non-zero component of the rotated vector
41+
* @param {Float64Array} R - single element array overwritten by the length of the rotated vector
4042
* @returns {void}
4143
*
4244
* @example

0 commit comments

Comments
 (0)