Diagonal

Shipping

array_diag

numpy diag: 1-D input → diagonal matrix, 2-D input → extract the k-th diagonal

Signature

Inputs

aSignal|Arrayrequired— A 1-D array (→ build a diagonal matrix) or a 2-D array (→ extract its k-th diagonal). Anything of rank ≥ 3 is an error.

Outputs

resultArray— For a 1-D input: a square Matrix with the values on the k-th diagonal. For a 2-D input: a 1-D Vector holding the extracted k-th diagonal.

Parameters

Key	Type	Default	Notes
`k`	int	0	Which diagonal: 0 = main, >0 above, <0 below. A 1-D input builds a matrix with the values on this diagonal; a 2-D input extracts this diagonal.

Description

Diagonal is numpy's dual diag operator — the only array builder with an input. Its behaviour flips on the input rank:

1-D input → build a square matrix with the input values placed on the $k$ -th diagonal (zeros elsewhere). Side length is $len (v) + ∣ k ∣$ .
2-D input → extract the $k$ -th diagonal as a 1-D Vector.

The Diagonal (k) offset selects which diagonal in both directions: $k > 0$ is above the main diagonal, $k < 0$ below. A rank-3+ input is a hard error. The build and extract paths are exact inverses on the main diagonal ( $diag (diag (v)) = v$ ). Stateless.

Mathematics

build: D [i, j] = {v_{i} 0 (i, j) on the k -th diagonal otherwise, D \in R^{(n + ∣ k ∣) \times (n + ∣ k ∣)}

extract: v_{i} = M [i, i + k] (k \geq 0), v_{i} = M [i - k, i] (k < 0)

Examples

Vector → diagonal matrix

Feed the Vector $[1, 2, 3]$ with k = 0. Output is $100020003$ .

Matrix → its diagonal

Feed a 2×2 Matrix $[[1, 2], [3, 4]]$ with k = 0. Output is the Vector $[1, 4]$ . Set k = 1 on the same matrix and you get $[2]$ (the single super-diagonal entry).

Applications

Turning a vector of eigenvalues or gains into a diagonal weighting matrix.
Reading the diagonal (variances / self-terms) out of a covariance or Gram matrix.
Constructing sub/super-diagonal skeletons for banded operators.

Neat

One node, two numpy behaviours, disambiguated purely by input rank — a 1-D fixture builds, a 2-D fixture extracts, matching `np.diag`'s famous overloaded contract.

The built matrix's side length grows with |k| (len + |k|) so the whole off-diagonal band fits — an off-main diagonal never truncates the input values.

Known issues

Inputs of rank ≥ 3 are rejected with an error (diag is only defined for 1-D and 2-D).

Extraction from a non-square matrix stops at the shorter dimension, and an out-of-range k yields an empty diagonal.

The result never carries a unit (the string is emptied on both paths).