mindspore.ops.MatrixSetDiagV3

class mindspore.ops.MatrixSetDiagV3(align='RIGHT_LEFT')[source]

Updates the diagonal part of a batched tensor. It takes an Tensor x and diagonal as input and returns a Tensor in which the specified diagonal values in the innermost matrices will be replaced by the values in the diagonal.

Diagonals shorter than max_diag_len need to be padded, where max_diag_len is the longest diagonal value. The dimension of diagonal is \(shape[-2]\) must be equal to num_diags calculated by \(num\_diags = k[1] - k[0] + 1\). The dimension of diagonal is \(shape[-1]\) must be equal to the longest diagonal value max_diag_len calculated by \(max\_diag\_len = min(x.shape[-2] + min(k[1], 0), x.shape[-1] + min(-k[0], 0))\).

Assume x is an n-D Tensor with shape \((d_1, d_2, ..., d_{n-2}, d_{n-1}, d_n)\). If k is an integer or \(k[0] == k[1]\), diagonal is an (n-1)-D Tensor with shape \((d_1, d_2, ..., d_{n-2}, max\_diag\_len)\) Otherwise, it has the same rank as x with shape \((d_1, d_2, ..., d_{n-2}, num\_diags, max\_diag\_len)\).

Warning

This is an experimental API that is subject to change or deletion.

Parameters

align (str, optional) –

specifies how superdiagonals and subdiagonals should be aligned. Supported values:”RIGHT_LEFT”, “LEFT_RIGHT”, “LEFT_LEFT”, “RIGHT_RIGHT”. Default: “RIGHT_LEFT”.

  • When set to “RIGHT_LEFT”, the alignment of superdiagonals will be towards the right side (padding the row on the left), while subdiagonals will be towards the left side (padding the row on the right)

  • When set to “LEFT_RIGHT”, the alignment of superdiagonals will be towards the left side (padding the row on the right), while subdiagonals will be towards the right side (padding the row on the left)

  • When set to “LEFT_LEFT”, the alignment of both superdiagonals and subdiagonals will be towards the left side(padding the row on the right).

  • When set to “RIGHT_RIGHT”, the alignment of both superdiagonals and subdiagonals will be towards the right side(padding the row on the left).

Inputs:

  • x (Tensor) - A n-D Tensor, where \(n >= 2\).

  • diagonal (Tensor) - A Tensor with the same dtype as x. Its rank depends on k. If k is an integer or \(k[0] == k[1]\), its dimension is \(n-1\). Otherwise, it has dimension \(n\).

  • k (Tensor) - Diagonal offset(s), Tensor of type int32. k can either be a single integer, which represents a single diagonal, or a pair of integers that specify the low and high ends of a matrix band. In this case, k[0] should not be greater than k[1]. The value of k has restructions, which means that value of k must be in range \((-x.shape[-2], x.shape[-1])\). Input k must be const Tensor when taking Graph mode.

    • k > 0 refers to a superdiagonal.

    • k = 0 refers to the main diagonal.

    • k < 0 refers to subdiagonals.

Outputs:

Tensor. The same type and shape as x.

Raises

  • TypeError – If any input is not Tensor.

  • TypeError – If input x and diagonal are not the same dtype.

  • TypeError – If k is not int32 dtype.

  • ValueError – If align is not a string or not in the valid range.

  • ValueError – If rank of k is not equal to 0 or 1.

  • ValueError – If rank of x is not greater equal to 2.

  • ValueError – If size of k is not equal to 1 or 2.

  • ValueError – If k[1] is not greater equal to k[0] in case the size of k is 2.

  • ValueError – If the diagonal rank size don’t match with input x rank size.

  • ValueError – If the diagonal shape value don’t match with input x shape value.

  • ValueError – If the diagonal \(shape[-2]\) is not equal to num_diags calculated by \(k[1] - k[0] + 1\) .

  • ValueError – If the value of k is not in \((-x.shape[-2], x.shape[-1])\).

  • ValueError – If the diagonal \(shape[-1]\) is not equal to the max_diag_len calculated by \(min(x.shape[-2] + min(k[1], 0), x.shape[-1] + min(-k[0], 0))\) .

Supported Platforms:

Ascend GPU CPU

Examples

>>> x = Tensor(np.array([[7, 7, 7, 7],
...                      [7, 7, 7, 7],
...                      [7, 7, 7, 7]]), mindspore.float32)
>>> diagonal = Tensor(np.array([[0, 9, 1],
...                             [6, 5, 8],
...                             [1, 2, 3],
...                             [4, 5, 0]]), mindspore.float32)
>>> k =Tensor(np.array([-1, 2]), mindspore.int32)
>>> matrix_set_diag_v3 = ops.MatrixSetDiagV3(align='RIGHT_LEFT')
>>> output = matrix_set_diag_v3(x, diagonal, k)
>>> print(output)
[[1. 6. 9. 7.]
 [4. 2. 5. 1.]
 [7. 5. 3. 8.]]
>>> print(output.shape)
(3, 4)