Skip to content

Commit e274909

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent dd4fa95 commit e274909

11 files changed

Lines changed: 1336 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@
44

55
<section class="release" id="unreleased">
66

7-
## Unreleased (2026-05-03)
7+
## Unreleased (2026-05-04)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`0710070`](https://github.com/stdlib-js/stdlib/commit/07100701aa7412f1d9eba15ae62511f5a74616ea) - add `ndarray/base/fill-diagonal` [(#11913)](https://github.com/stdlib-js/stdlib/pull/11913)
1314
- [`36044b1`](https://github.com/stdlib-js/stdlib/commit/36044b17e4a5cfb74f46eb66e0b8767a86fa5d38) - add `ndarray/first` [(#11907)](https://github.com/stdlib-js/stdlib/pull/11907)
1415
- [`5192af7`](https://github.com/stdlib-js/stdlib/commit/5192af79ff02342bed92b48a084f18b9316099e8) - add `ndarray/to-unflattened` [(#11891)](https://github.com/stdlib-js/stdlib/pull/11891)
1516
- [`02b39b4`](https://github.com/stdlib-js/stdlib/commit/02b39b48e4de069af553e2e599292d3b815056fc) - add `ndarray/diagonal` [(#11900)](https://github.com/stdlib-js/stdlib/pull/11900)
@@ -915,6 +916,7 @@ A total of 49 issues were closed in this release:
915916

916917
<details>
917918

919+
- [`0710070`](https://github.com/stdlib-js/stdlib/commit/07100701aa7412f1d9eba15ae62511f5a74616ea) - **feat:** add `ndarray/base/fill-diagonal` [(#11913)](https://github.com/stdlib-js/stdlib/pull/11913) _(by Muhammad Haris, Athan Reines)_
918920
- [`36044b1`](https://github.com/stdlib-js/stdlib/commit/36044b17e4a5cfb74f46eb66e0b8767a86fa5d38) - **feat:** add `ndarray/first` [(#11907)](https://github.com/stdlib-js/stdlib/pull/11907) _(by Muhammad Haris, Athan Reines)_
919921
- [`5192af7`](https://github.com/stdlib-js/stdlib/commit/5192af79ff02342bed92b48a084f18b9316099e8) - **feat:** add `ndarray/to-unflattened` [(#11891)](https://github.com/stdlib-js/stdlib/pull/11891) _(by Muhammad Haris)_
920922
- [`02b39b4`](https://github.com/stdlib-js/stdlib/commit/02b39b48e4de069af553e2e599292d3b815056fc) - **feat:** add `ndarray/diagonal` [(#11900)](https://github.com/stdlib-js/stdlib/pull/11900) _(by Muhammad Haris, Athan Reines)_

‎base/fill-diagonal/README.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
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+
# fillDiagonal
22+
23+
> Fill a specified diagonal of a matrix (or stack of matrices) with a scalar value.
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).
43+
44+
</section>
45+
46+
<!-- /.intro -->
47+
48+
<section class="usage">
49+
50+
## Usage
51+
52+
```javascript
53+
var fillDiagonal = require( '@stdlib/ndarray/base/fill-diagonal' );
54+
```
55+
56+
#### fillDiagonal( x, value, dims, k )
57+
58+
Fills a specified diagonal of a matrix (or stack of matrices) with a scalar value.
59+
60+
```javascript
61+
var zeros = require( '@stdlib/ndarray/zeros' );
62+
63+
var x = zeros( [ 3, 3 ] );
64+
// returns <ndarray>[ [ 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ] ]
65+
66+
var out = fillDiagonal( x, 1.0, [ 0, 1 ], 0 );
67+
// returns <ndarray>[ [ 1.0, 0.0, 0.0 ], [ 0.0, 1.0, 0.0 ], [ 0.0, 0.0, 1.0 ] ]
68+
69+
var bool = ( out === x );
70+
// returns true
71+
```
72+
73+
The function accepts the following arguments:
74+
75+
- **x**: input ndarray.
76+
- **value**: scalar value.
77+
- **dims**: dimension indices defining the plane in which to fill the diagonal.
78+
- **k**: diagonal offset.
79+
80+
</section>
81+
82+
<!-- /.usage -->
83+
84+
<section class="notes">
85+
86+
## Notes
87+
88+
- 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.
89+
- Each provided dimension index must reside on the interval `[-ndims, ndims-1]`.
90+
- The diagonal offset `k` is interpreted as `column - row`. Accordingly, when `k = 0`, the function fills the main diagonal; when `k > 0`, the function fills the diagonal above the main diagonal; and when `k < 0`, the function fills the diagonal below the main diagonal.
91+
- If `value` is a number and `x` has a complex [data type][@stdlib/ndarray/dtypes], the function fills an input ndarray with a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
92+
- A `value` must be able to safely cast to the input ndarray [data type][@stdlib/ndarray/dtypes]. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a `'float32'` input ndarray).
93+
- The function **mutates** the input ndarray in-place.
94+
95+
</section>
96+
97+
<!-- /.notes -->
98+
99+
<section class="examples">
100+
101+
## Examples
102+
103+
<!-- eslint no-undef: "error" -->
104+
105+
```javascript
106+
var zeros = require( '@stdlib/ndarray/zeros' );
107+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
108+
var fillDiagonal = require( '@stdlib/ndarray/base/fill-diagonal' );
109+
110+
// Create a stack of matrices:
111+
var x = zeros( [ 2, 3, 3 ] );
112+
113+
// Fill main diagonals:
114+
fillDiagonal( x, 1.0, [ 1, 2 ], 0 );
115+
console.log( ndarray2array( x ) );
116+
117+
// Fill super-diagonals:
118+
fillDiagonal( x, 2.0, [ 1, 2 ], 1 );
119+
console.log( ndarray2array( x ) );
120+
121+
// Fill sub-diagonals:
122+
fillDiagonal( x, 3.0, [ 1, 2 ], -1 );
123+
console.log( ndarray2array( x ) );
124+
```
125+
126+
</section>
127+
128+
<!-- /.examples -->
129+
130+
<section class="references">
131+
132+
</section>
133+
134+
<!-- /.references -->
135+
136+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
137+
138+
<section class="related">
139+
140+
</section>
141+
142+
<!-- /.related -->
143+
144+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
145+
146+
<section class="links">
147+
148+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray/tree/main/dtypes
149+
150+
</section>
151+
152+
<!-- /.links -->

0 commit comments

Comments
 (0)