toeplitz

hypercoil.functional.matrix.toeplitz(c: Tensor, r: Tensor | None = None, shape: Tuple[int, int] | None = None, fill_value: float = 0.0) → Tensor

Populate a block of tensors with Toeplitz banded structure.

Warning

Inputs c and r must contain the same first element for functionality to match scipy.toeplitz. This is not checked. In the event that this is not the case, c[0] is ignored. Note that this is the opposite of scipy.toeplitz.

Dimension:

c : \((C, *)\)

C denotes the number of elements in the first column whose values are propagated along the matrix diagonals. * denotes any number of additional dimensions.

r : \((R, *)\)

R denotes the number of elements in the first row whose values are propagated along the matrix diagonals.

fill_value : \((*)\)

As above.

Output : \((*, C^{*}, R^{*})\)

\(C^{*}\) and \({*}\) default to C and R unless specified otherwise in the dim argument.

Parameters:

c: Tensor

Tensor of entries in the first column of each Toeplitz matrix. The first axis corresponds to a single matrix column; additional dimensions correspond to concatenation of Toeplitz matrices into a stack or block tensor.

r: Tensor

Tensor of entries in the first row of each Toeplitz matrix. The first axis corresponds to a single matrix row; additional dimensions correspond to concatenation of Toeplitz matrices into a stack or block tensor. The first entry in each column should be the same as the first entry in the corresponding column of c; otherwise, it will be ignored.

dim: 2-tuple of (int, int) or None (default)

Dimension of each Toeplitz banded matrix in the output block. If this is None or unspecified, it defaults to the sizes of the first axes of inputs c and r. Otherwise, the row and column inputs are extended until their dimensions equal those specified here. This can be useful, for instance, to create a large banded matrix with mostly zero off-diagonals.

fill_value: Tensor or float (default 0)

Specifies the value that should be used to populate the off-diagonals of each Toeplitz matrix if the specified row and column elements are extended to conform with the specified dim. If this is a tensor, then each entry corresponds to the fill value in a different data channel. Has no effect if dim is None.

Returns:

out: Tensor

Block of Toeplitz matrices populated from the specified row and column elements.