Sparse-matrix backend functions

Sparse-matrix backend functions#

Efficiently construct fwt operations using sparse matrices.

ptwt.sparse_math.batch_mm(matrix: Tensor, matrix_batch: Tensor) → Tensor[source]#

Calculate a batched matrix-matrix product using torch tensors.

This calculates the product of a matrix with a batch of dense matrices. The former can be dense or sparse.

Parameters:

  • matrix (torch.Tensor) – Sparse or dense matrix, of shape [m, n].

  • matrix_batch (torch.Tensor) – Batched dense matrices, of shape [b, n, k].

Returns:

The batched matrix-matrix product of shape [b, m, k].

Raises:

ValueError – If the matrices cannot be multiplied due to incompatible matrix shapes.

ptwt.sparse_math.cat_sparse_identity_matrix(sparse_matrix: Tensor, new_length: int) → Tensor[source]#

Concatenate a sparse input matrix and a sparse identity matrix.

Parameters:

  • sparse_matrix (torch.Tensor) – The sparse square input matrix.

  • new_length (int) – The length up to which the diagonal should be elongated.

Returns:

Square [input, eye] matrix of size [new_length, new_length]

Raises:

ValueError – if sparse_matrix is not a square 2d sparse matrix of if new_length is smaller than the number of rows of sparse_matrix.

ptwt.sparse_math.construct_conv2d_matrix(filter: Tensor, input_rows: int, input_columns: int, *, mode: Literal['full', 'valid', 'same', 'sameshift'] = 'valid', fully_sparse: bool = True) → Tensor[source]#

Create a two-dimensional sparse convolution matrix.

Convolving with this matrix should be equivalent to a call to scipy.signal.convolve2d and a reshape.

Parameters:

  • filter (torch.tensor) – A filter of shape [height, width] to convolve with.

  • input_rows (int) – The number of rows in the input matrix.

  • input_columns (int) – The number of columns in the input matrix.

  • mode – (str) = The desired padding method. Options are full, same and valid. Defaults to valid or no padding.

  • fully_sparse (bool) – Use a sparse implementation of the Kronecker to save memory. Defaults to True.

Returns:

A sparse convolution matrix.

Raises:

ValueError – If the padding mode is neither full, same or valid.

ptwt.sparse_math.construct_conv_matrix(filter: Tensor, input_rows: int, *, mode: Literal['full', 'valid', 'same', 'sameshift'] = 'valid') → Tensor[source]#

Construct a convolution matrix.

Full, valid and same, padding are supported. For reference see: RoyiAvital/StackExchangeCodes master/StackOverflow/Q2080835/CreateConvMtxSparse.m

Parameters:

  • filter (torch.tensor) – The 1D-filter to convolve with.

  • input_rows (int) – The number of columns in the input.

  • mode – String identifier for the desired padding. Choose full, valid or same. Defaults to valid.

Returns:

The sparse convolution tensor.

Raises:

ValueError – If an unsupported PaddingMode value is passed as mode.

ptwt.sparse_math.construct_strided_conv2d_matrix(filter: Tensor, input_rows: int, input_columns: int, stride: int = 2, *, mode: Literal['full', 'valid', 'same', 'sameshift'] = 'full') → Tensor[source]#

Create a strided sparse two-dimensional convolution matrix.

Parameters:

  • filter (torch.Tensor) – The two-dimensional convolution filter.

  • input_rows (int) – The number of rows in the 2d input matrix.

  • input_columns (int) – The number of columns in the 2d input matrix.

  • stride (int) – The stride between the filter positions. Defaults to 2.

  • mode – The convolution type. Defaults to full. sameshift starts at 1 instead of 0.

Returns:

The sparse convolution tensor.

Raises:

ValueError – Raised if an unknown convolution string is provided.

ptwt.sparse_math.construct_strided_conv_matrix(filter: Tensor, input_rows: int, stride: int = 2, *, mode: Literal['full', 'valid', 'same', 'sameshift'] = 'valid') → Tensor[source]#

Construct a strided convolution matrix.

Parameters:

  • filter (torch.Tensor) – The filter coefficients to convolve with.

  • input_rows (int) – The number of rows in the input vector.

  • stride (int) – The step size of the convolution. Defaults to two.

  • mode – Choose valid, same or sameshift. Defaults to valid.

Returns:

The strided sparse convolution matrix.

ptwt.sparse_math.sparse_diag(diagonal: Tensor, col_offset: int, rows: int, cols: int) → Tensor[source]#

Create a rows-by-cols sparse diagonal-matrix.

The matrix is constructed by taking the columns of the input and placing them along the diagonal specified by col_offset.

Parameters:

  • diagonal (torch.Tensor) – The values for the diagonal.

  • col_offset (int) – Move the diagonal to the right by offset columns.

  • rows (int) – The number of rows in the final matrix.

  • cols (int) – The number of columns in the final matrix.

Returns:

A sparse matrix with a shifted diagonal.

ptwt.sparse_math.sparse_kron(sparse_tensor_a: Tensor, sparse_tensor_b: Tensor) → Tensor[source]#

Compute a sparse Kronecker product.

As defined at: https://en.wikipedia.org/wiki/Kronecker_product Adapted from: scipy/scipy

Parameters:

  • sparse_tensor_a (torch.Tensor) – Sparse 2d-Tensor a of shape [m, n].

  • sparse_tensor_b (torch.Tensor) – Sparse 2d-Tensor b of shape [p, q].

Returns:

The resulting tensor of shape [mp, nq].

Raises:

ValueError – if the tensors are on different devices.

ptwt.sparse_math.sparse_replace_row(matrix: Tensor, row_index: int, row: Tensor) → Tensor[source]#

Replace a row within a sparse [rows, cols] matrix.

I.e. matrix[row_no, :] = row.

Parameters:

  • matrix (torch.Tensor) – A sparse two-dimensional matrix.

  • row_index (int) – The row to replace.

  • row (torch.Tensor) – The row to insert into the sparse matrix.

Returns:

A sparse matrix, with the new row inserted at row_index.

Raises:

ValueError – if the size of the last axis of matrix and row does not match.

Contents