warp.sparse.bsr_mv#

warp.sparse.bsr_mv(
A,
x,
y=None,
alpha=1.0,
beta=0.0,
transpose=False,
work_buffer=None,
tile_size=0,
algorithm='auto',
)[source]#

Perform the sparse matrix-vector product y := alpha * A * x + beta * y and return y.

The x and y vectors are allowed to alias.

x may also be a batch: a contiguous 2D array whose rows each hold one vector with A’s column dimension, for example of shape (count, A.shape[1]) for a scalar dtype. Each row is then multiplied independently, y[r] := alpha * A * x[r] + beta * y[r], and y has one row per vector. A 2D array holding a single vector keeps its single-vector meaning unless algorithm is set.

Parameters:
  • A (BsrMatrixOrExpression[BlockType[Rows, Cols, Scalar]]) – Read-only, left matrix operand of the matrix-vector product.

  • x (Array[Vector[Scalar, Cols] | Scalar]) – Read-only, right vector operand of the matrix-vector product.

  • y (Array[Vector[Scalar, Rows] | Scalar] | None) – Mutable affine operand and result vector. If y is not provided, it will be allocated and treated as zero.

  • alpha (Scalar) – Uniform scaling factor for x. If zero, x will not be read and may be left uninitialized.

  • beta (Scalar) – Uniform scaling factor for y. If zero, y will not be read and may be left uninitialized.

  • transpose (bool) – If True, use the transpose of the matrix A. In this case the result is non-deterministic.

  • work_buffer (Array[Vector[Scalar, Rows] | Scalar] | None) – Temporary storage is required if and only if x and y are the same vector. If provided, the work_buffer array will be used for this purpose, otherwise a temporary allocation will be performed. For a batch with algorithm="loop", its first output-vector-sized part serves each row in turn. With "rows" or "columns", it is instead a contiguous 1D array of A’s scalar type with at least count * A.shape[0] or count * (A.shape[0] + A.shape[1]) entries respectively, and reusing one avoids a temporary allocation on every call.

  • tile_size (int) – If a positive integer, use tiles of this size to compute the matrix-vector product. On CPU, values greater than 1 require warp.config.enable_cpu_blocks and otherwise raise a ValueError. Ignored when transpose is True. If negative, disable tile-based computation. Defaults to 0, which determines whether to use tiles using a heuristic based on the matrix shape and number of non-zeros.

  • algorithm (Literal['auto', 'loop', 'rows', 'columns']) –

    Kernel strategy for a batch of vectors:

    • "loop" applies the single-vector product to each vector in turn. It supports every matrix, device and transpose.

    • "rows" computes each result row directly: one thread per vector and scalar row, or for square blocks on CUDA beyond two vectors, eight lanes per block row. It supports square blocks.

    • "columns" transposes the batch so that the vectors’ entries are adjacent, reads each matrix row once for up to eight vectors, and transposes back. It supports square blocks on CUDA and needs scratch storage for both transposed operands.

    • "auto" selects a strategy without synchronizing. It uses "loop" for a single vector, for transpose, when any operand requires gradients, and on CUDA for block shapes other than 1x1 and 3x3. Otherwise it uses "rows" on CPU and for CSR matrices on CUDA, and for 3x3 BSR on CUDA "rows" up to four vectors and "columns" beyond. It cannot see how many entries each row stores, so pin "columns" for CSR matrices with long or irregular rows, which can be several times faster from four vectors.

    Explicit choices always run the named strategy and raise ValueError where it is unsupported, including for operands that require gradients, since "rows" and "columns" are forward-only. A single vector requires "auto" or "loop".

Return type:

Array[Vector[Scalar, Rows] | Scalar]

When recorded on a warp.Tape, the product is differentiable with respect to x, the input y and the values of A, restricted to its non-zero topology. For a batch of vectors, "auto" and "loop" are differentiable; "rows" and "columns" are forward-only.