Skip to content

Commit 12d678c

Browse files
headlessNodeheadlessNode
committed
feat: add ndarray/base/diagonal
--- 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: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - 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: passed - task: lint_license_headers status: passed ---
1 parent ba7a157 commit 12d678c

10 files changed

Lines changed: 1429 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/base/diagonal/README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 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+
# diagonal
22+
23+
> Return a view of the diagonal of a matrix (or stack of matrices).
24+
25+
<section class="intro">
26+
27+
For an `M`-by-`N` matrix `A`, the `k`-th diagonal is defined as
28+
29+
<!-- <equation class="equation" label="eq:diagonal_definition" align="center" raw="D_k = \{\, A_{i,j} : j - i = k \,\}" alt="Definition of the k-th diagonal of a matrix."> -->
30+
31+
```math
32+
D_k = \{\, A_{i,j} : j - i = k \,\}
33+
```
34+
35+
<!-- <div class="equation" align="center" data-raw-text="D_k = \{\, A_{i,j} : j - i = k \,\}" data-equation="eq:diagonal_definition">
36+
<img src="" alt="Definition of the k-th diagonal of a matrix.">
37+
<br>
38+
</div> -->
39+
40+
<!-- </equation> -->
41+
42+
where `k = 0` corresponds to the main diagonal, `k > 0` corresponds to the super-diagonals (above the main diagonal), and `k < 0` corresponds to the sub-diagonals (below the main diagonal). For example, given the matrix
43+
44+
<!-- <equation class="equation" label="eq:diagonal_example" align="center" raw="A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}" alt="Example matrix."> -->
45+
46+
```math
47+
A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}
48+
```
49+
50+
<!-- <div class="equation" align="center" data-raw-text="A = \begin{bmatrix} a_{0,0} & a_{0,1} & a_{0,2} \\ a_{1,0} & a_{1,1} & a_{1,2} \\ a_{2,0} & a_{2,1} & a_{2,2} \end{bmatrix}" data-equation="eq:diagonal_example">
51+
<img src="" alt="Example matrix.">
52+
<br>
53+
</div> -->
54+
55+
<!-- </equation> -->
56+
57+
the main diagonal is `[ a_{0,0}, a_{1,1}, a_{2,2} ]`, the super-diagonal `k = 1` is `[ a_{0,1}, a_{1,2} ]`, and the sub-diagonal `k = -1` is `[ a_{1,0}, a_{2,1} ]`.
58+
59+
</section>
60+
61+
<!-- /.intro -->
62+
63+
<section class="usage">
64+
65+
## Usage
66+
67+
```javascript
68+
var diagonal = require( '@stdlib/ndarray/base/diagonal' );
69+
```
70+
71+
#### diagonal( x, dims, k, writable )
72+
73+
Returns a view of the diagonal of a matrix (or stack of matrices) `x`.
74+
75+
```javascript
76+
var array = require( '@stdlib/ndarray/array' );
77+
78+
var x = array( [ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ] );
79+
// returns <ndarray>[ [ 1.0, 2.0, 3.0 ], [ 4.0, 5.0, 6.0 ], [ 7.0, 8.0, 9.0 ] ]
80+
81+
var y = diagonal( x, [ 0, 1 ], 0, false );
82+
// returns <ndarray>[ 1.0, 5.0, 9.0 ]
83+
```
84+
85+
The function accepts the following arguments:
86+
87+
- **x**: input ndarray.
88+
- **dims**: dimension indices defining the plane in which to extract the diagonal.
89+
- **k**: diagonal offset.
90+
- **writable**: boolean indicating whether the returned ndarray should be writable.
91+
92+
</section>
93+
94+
<!-- /.usage -->
95+
96+
<section class="notes">
97+
98+
## Notes
99+
100+
- The order of the dimension indices contained in `dims` matters. The first element specifies the row-like dimension. The second element specifies the column-like dimension.
101+
- Each provided dimension index must reside on the interval `[-ndims, ndims-1]`.
102+
- The diagonal offset `k` is interpreted as `column - row`. Accordingly, when `k = 0`, the function returns the main diagonal; when `k > 0`, the function returns the diagonal above the main diagonal; and when `k < 0`, the function returns the diagonal below the main diagonal.
103+
- The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa.
104+
- The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
105+
106+
</section>
107+
108+
<!-- /.notes -->
109+
110+
<section class="examples">
111+
112+
## Examples
113+
114+
<!-- eslint no-undef: "error" -->
115+
116+
```javascript
117+
var uniform = require( '@stdlib/random/uniform' );
118+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
119+
var diagonal = require( '@stdlib/ndarray/base/diagonal' );
120+
121+
// Create a stack of matrices:
122+
var x = uniform( [ 2, 3, 3 ], -10.0, 10.0, {
123+
'dtype': 'float64'
124+
});
125+
126+
console.log( 'X: ', ndarray2array( x ) );
127+
128+
// Extract the main diagonals of the stack:
129+
var y = diagonal( x, [ 1, 2 ], 0, false );
130+
console.log( 'diagonal( X, [ 1, 2 ], 0 ): ', ndarray2array( y ) );
131+
132+
// Extract the super-diagonals of the stack:
133+
y = diagonal( x, [ 1, 2 ], 1, false );
134+
console.log( 'diagonal( X, [ 1, 2 ], 1 ): ', ndarray2array( y ) );
135+
136+
// Extract the sub-diagonals of the stack:
137+
y = diagonal( x, [ 1, 2 ], -1, false );
138+
console.log( 'diagonal( X, [ 1, 2 ], -1 ): ', ndarray2array( y ) );
139+
```
140+
141+
</section>
142+
143+
<!-- /.examples -->
144+
145+
<section class="references">
146+
147+
</section>
148+
149+
<!-- /.references -->
150+
151+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
152+
153+
<section class="related">
154+
155+
</section>
156+
157+
<!-- /.related -->
158+
159+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
160+
161+
<section class="links">
162+
163+
</section>
164+
165+
<!-- /.links -->

0 commit comments

Comments
 (0)