BLAS level 3

Overview

Batched matrix-matrix operations: gemm, trsm, trmm, symm/hemm, syrk/herk, syr2k/her2k.

Lower-level functions (algorithm-specific variants, workspace queries, validation and helpers): BLAS level 3: lower-level API.

Functions

gemm()

template<Backend Back, typename T>

Event batchlas::gemm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Transpose	transA,
		Transpose	transB,
		ComputePrecision	precision = ComputePrecision::Default )

Batched general matrix-matrix multiply.

For every batch item \(b\) computes

\[ C_b := \alpha \, \mathrm{op}(A_b) \, \mathrm{op}(B_b) + \beta \, C_b \]

where \(\mathrm{op}(X)\) is \(X\), \(X^T\) or \(X^H\) according to transA / transB. With \(\mathrm{op}(A)\) of size m x k and \(\mathrm{op}(B)\) of size k x n, C is m x n.

Heterogeneous batch. A batch whose items carry differing active_rows / active_cols is handled by this same entry point on every backend: an item with m == 0 or n == 0 is skipped, an item with k == 0 computes \(C_b := \beta C_b\), and an all-skipped batch still returns a valid Event. There is no separate gemm_heterogeneous in C++ (the Python binding's one exists to coerce a list of differently-shaped arrays).

Also callable as gemm(ctx, A, B, C, GemmOptions<T>{...}), with owning Matrix arguments, and without Back (taken from ctx.backend()).

Template Parameters

Back	backend the call is compiled for; must match ctx's device
T	scalar type: float, double, std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of matrices, m x k (NoTrans) or k x m (Trans/ConjTrans)
B	batch of matrices, k x n (NoTrans) or n x k (Trans/ConjTrans)
C	batch of m x n matrices; input scaled by beta, overwritten with the result
alpha	scale of the product
beta	scale of the input C
transA	op() applied to A
transB	op() applied to B
precision	compute precision; ComputePrecision::Default computes in T. Other values are honoured only by the vendor library path.

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

A, B and C have the same batch size and conforming shapes per item.

Exceptions

batchlas::NoRouteError

in a build without the vendor BLAS for Back when no native kernel can run the call (a non-Default precision). An empty batch, m or n is a no-op, and k = 0 computes C = beta * C; neither reaches selection, so precision is not checked there.

See also

GemmOptions, docs/cpp-api.md

hemm()

template<Backend Ba, ComplexScalar T>

Event batchlas::hemm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Side	side,
		Uplo	uplo )

Batched Hermitian matrix-matrix multiply.

For every batch item computes

\[ C := \alpha A B + \beta C \quad (\texttt{Side::Left}), \qquad C := \alpha B A + \beta C \quad (\texttt{Side::Right}) \]

with A Hermitian. Only the triangle of A named by uplo is read; the other is taken to be its conjugate transpose, and the imaginary part of the diagonal is taken to be zero whatever is stored there. B and C are m x n; A is m x m (Left) or n x n (Right).

Constrained to complex T: for a real matrix Hermitian and symmetric are the same statement, and the real spelling is symm. Also callable as hemm(ctx, A, B, C, HemmOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Not table-selected. On Backend::CUDA the cuBLAS backend chooses by a fixed rule between expanding A into scratch plus one strided-batched gemm and a per-item cublas?hemm loop (the loop also serves a scratch that does not fit); BATCHLAS_EXPAND_ROUTE = expand | loop pins it. The host backend runs the per-item cblas_?hemm loop.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of Hermitian matrices; only the uplo triangle is read
B	batch of m x n matrices; not modified
C	batch of m x n matrices; input scaled by beta, overwritten with the result
alpha	scale of the product
beta	scale of the input C
side	whether A multiplies from the left or the right
uplo	which triangle of A holds the data

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

All operands have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform (Backend::CUDA; the host backend checks inside its deferred host task and throws std::runtime_error there)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba: hemm has no native implementation.

Note

Not instantiated for Backend::ROCM (rocBLAS has no wrapper here).

See also

symm, HemmOptions, docs/cpp-api.md, docs/perf/level3.md (the rule's crossover)

her2k()

template<Backend Ba, ComplexScalar T>

Event batchlas::her2k	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		float_t< T >	beta,
		Uplo	uplo,
		Transpose	transA )

Batched Hermitian rank-2k update.

For every batch item computes, with A and B n x k (NoTrans) or k x n (ConjTrans) and C Hermitian n x n,

\[ C := \alpha A B^H + \bar\alpha B A^H + \beta C \quad (\texttt{NoTrans}) \]

\[ C := \alpha A^H B + \bar\alpha B^H A + \beta C \quad (\texttt{ConjTrans}) \]

Only the triangle of C named by uplo is written; the other is left as it was (use MatrixView::hermitize to mirror it). The diagonal comes out real.

The second term is the conjugate transpose of the first, not a copy with the operands swapped; that is what makes the sum Hermitian for any complex alpha, and is the whole difference from syr2k. beta scales an already-Hermitian C and so is real. Also callable as her2k(ctx, A, B, C, Her2kOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Not table-selected. On Backend::CUDA the cuBLAS backend chooses by a fixed rule between one strided-batched gemm into scratch that carries both terms, folded into the uplo triangle, and a per-item cublas?her2k loop (the loop also serves a scratch that does not fit); BATCHLAS_EXPAND_ROUTE = expand | loop pins it. The host backend runs the per-item cblas_?her2k loop.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of n x k (NoTrans) or k x n (ConjTrans) matrices; not modified
B	batch with the same shape as A; not modified
C	batch of n x n matrices; the uplo triangle is updated in place
alpha	complex scale of \(A B^H\) (its conjugate scales the mirror term)
beta	real scale of the input C
uplo	which triangle of C is written
transA	Transpose::NoTrans or Transpose::ConjTrans

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

All operands have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform (Backend::CUDA; the host backend checks inside its deferred host task and throws std::runtime_error there)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba: her2k has no native implementation.

Note

Not instantiated for Backend::ROCM.

See also

syr2k, herk, Her2kOptions, docs/cpp-api.md, docs/perf/level3.md (the rule's crossover)

herk()

template<Backend Ba, ComplexScalar T>

Event batchlas::herk	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		float_t< T >	alpha,
		float_t< T >	beta,
		Uplo	uplo,
		Transpose	transA )

Batched Hermitian rank-k update.

For every batch item computes

\[ C := \alpha A A^H + \beta C \quad (\texttt{NoTrans},\ A \text{ is } n \times k), \qquad C := \alpha A^H A + \beta C \quad (\texttt{ConjTrans},\ A \text{ is } k \times n) \]

with C Hermitian n x n. Only the triangle of C named by uplo is written; the other triangle is left exactly as it was (use MatrixView::hermitize to mirror it). The diagonal comes out real: an imaginary part on C's diagonal is neither read nor produced.

alpha and beta are real (float_t<T>), as in BLAS ?herk: a complex alpha would make \(\alpha A A^H\) non-Hermitian. Constrained to complex T; the real spelling is syrk. Also callable as herk(ctx, A, C, HerkOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Not table-selected. On Backend::CUDA the cuBLAS backend chooses by a fixed rule between one strided-batched gemm into scratch folded into the uplo triangle and a per-item cublas?herk loop (the loop also serves a scratch that does not fit); BATCHLAS_EXPAND_ROUTE = expand | loop pins it. BATCHLAS_SYRK_ROUTE=gram opts a GPU call into syrk's conjugating Gram tile kernel where it admits the shape (measured slower; kept for testing). The host backend runs the per-item cblas_?herk loop.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of n x k (NoTrans) or k x n (ConjTrans) matrices; not modified
C	batch of n x n matrices; the uplo triangle is updated in place
alpha	real scale of the product
beta	real scale of the input C
uplo	which triangle of C is written
transA	Transpose::NoTrans or Transpose::ConjTrans

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

A and C have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform (Backend::CUDA; the host backend checks inside its deferred host task and throws std::runtime_error there)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba: herk has no native implementation.

Note

Not instantiated for Backend::ROCM.

See also

syrk, her2k, HerkOptions, docs/cpp-api.md, docs/perf/level3.md (the rule's crossover)

symm()

template<Backend Ba, RealScalar T>

Event batchlas::symm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Side	side,
		Uplo	uplo )

Batched symmetric matrix-matrix multiply.

For every batch item computes

\[ C := \alpha A B + \beta C \quad (\texttt{Side::Left}), \qquad C := \alpha B A + \beta C \quad (\texttt{Side::Right}) \]

with A symmetric: only the triangle named by uplo is read and the other is taken to be its transpose. B and C are m x n; A is m x m (Left) or n x n (Right).

Constrained to real T; the complex spelling is hemm. Also callable as symm(ctx, A, B, C, SymmOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Each call takes a kernel family from the tuned table for its shape (Kernel selection tables): expand (mirror A's triangle into scratch leased from the queue's arena, then one strided-batched gemm) or vendor (the library's per-item ?symm loop). Pin one with BATCHLAS_SYMM_ROUTE = auto | native | vendor | expand.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	float or double

Parameters

ctx	queue the work is enqueued on
A	batch of symmetric matrices; only the uplo triangle is read
B	batch of m x n matrices; not modified
C	batch of m x n matrices; input scaled by beta, overwritten with the result
alpha	scale of the product
beta	scale of the input C
side	whether A multiplies from the left or the right
uplo	which triangle of A holds the data

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

All operands have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform, or if BATCHLAS_SYMM_ROUTE names a family that is not compiled for T or cannot run this call (native and vendor instead fall back to the tuned choice with a warning)
std::runtime_error	if no family can run the call in a build with the vendor BLAS (a heterogeneous batch: every family takes one (n, k) per launch)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba, unless the call is Backend::CUDA or Backend::ROCM on a GPU, with homogeneous operands, batch <= 65535 and an expansion scratch that fits (the expand choice; docs/perf/level3.md).

Note

Backend::ROCM has no vendor symm: its vendor choice symmetrizes a copy of A and calls gemm, and blocks the host until it finishes.

See also

hemm, SymmOptions, docs/cpp-api.md

syr2k()

template<Backend Ba, RealScalar T>

Event batchlas::syr2k	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Uplo	uplo,
		Transpose	transA )

Batched symmetric rank-2k update.

For every batch item computes, with A and B n x k (NoTrans) or k x n (Trans) and C symmetric n x n,

\[ C := \alpha A B^T + \alpha B A^T + \beta C \quad (\texttt{NoTrans}) \]

\[ C := \alpha A^T B + \alpha B^T A + \beta C \quad (\texttt{Trans}) \]

Only the triangle of C named by uplo is written; the other is left as it was (use MatrixView::symmetrize to mirror it).

Constrained to real T; the complex spelling is her2k. Also callable as syr2k(ctx, A, B, C, Syr2kOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Each call takes a kernel family from the tuned table for its shape (Kernel selection tables): triangular (float only: both products fused into 128-wide tiles of the requested half) or vendor (the library's per-item ?syr2k loop). Pin one with BATCHLAS_SYR2K_ROUTE = auto | native | vendor | triangular.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	float or double

Parameters

ctx	queue the work is enqueued on
A	batch of n x k (NoTrans) or k x n (Trans) matrices; not modified
B	batch with the same shape as A; not modified
C	batch of n x n matrices; the uplo triangle is updated in place
alpha	scale of both products
beta	scale of the input C
uplo	which triangle of C is written
transA	Transpose::NoTrans or Transpose::Trans, applied to A and B

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

All operands have the same batch size and conforming shapes per item; k > 0.

Exceptions

std::invalid_argument	if the shapes do not conform, or if BATCHLAS_SYR2K_ROUTE names a family that is not compiled for T or cannot run this call (native and vendor instead fall back to the tuned choice with a warning)
std::runtime_error	if no family can run the call in a build with the vendor BLAS (a heterogeneous batch: every family takes one (n, k) per launch)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba, unless the call is Backend::CUDA on a GPU, float, not ConjTrans, with homogeneous operands and batch <= 65535 (the triangular tiles; docs/perf/level3.md).

See also

her2k, syrk, Syr2kOptions, docs/cpp-api.md

syrk()

template<Backend Ba, RealScalar T>

Event batchlas::syrk	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Uplo	uplo,
		Transpose	transA )

Batched symmetric rank-k update.

For every batch item computes

\[ C := \alpha A A^T + \beta C \quad (\texttt{NoTrans},\ A \text{ is } n \times k), \qquad C := \alpha A^T A + \beta C \quad (\texttt{Trans},\ A \text{ is } k \times n) \]

with C symmetric n x n. Only the triangle of C named by uplo is written; the other triangle is left exactly as it was, uninitialised memory included (use MatrixView::symmetrize to mirror it).

Constrained to real T; the complex spelling is herk. Also callable as syrk(ctx, A, C, SyrkOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Each call takes a kernel family from the tuned table for its shape (Kernel selection tables): gram (one tile covers C, n <= 128), triangular (float only: 128-wide tiles of the requested half) or vendor (the library's per-item ?syrk loop). Pin one with BATCHLAS_SYRK_ROUTE = auto | native | vendor | gram | triangular.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	float or double

Parameters

ctx	queue the work is enqueued on
A	batch of n x k (NoTrans) or k x n (Trans) matrices; not modified
C	batch of n x n matrices; the uplo triangle is updated in place
alpha	scale of the product
beta	scale of the input C
uplo	which triangle of C is written
transA	Transpose::NoTrans or Transpose::Trans (ConjTrans is accepted and means Trans)

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

A and C have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform, or if BATCHLAS_SYRK_ROUTE names a family that is not compiled for T or cannot run this call (native and vendor instead fall back to the tuned choice with a warning)
std::runtime_error	if no family can run the call in a build with the vendor BLAS (a heterogeneous batch: every family takes one (n, k) per launch)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba, unless the call is Backend::CUDA on a GPU, with homogeneous operands, batch <= 65535, and either T is float (the triangular tiles) or the gram tile admits the shape (docs/perf/level3.md).

See also

herk, syr2k, SyrkOptions, docs/cpp-api.md

trmm()

template<Backend Ba, typename T>

Event batchlas::trmm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		Side	side,
		Uplo	uplo,
		Transpose	transA,
		Diag	diag )

Batched triangular matrix-matrix multiply, out of place.

For every batch item computes

\[ C := \alpha \, \mathrm{op}(A) \, B \quad (\texttt{Side::Left}), \qquad C := \alpha \, B \, \mathrm{op}(A) \quad (\texttt{Side::Right}) \]

with A triangular (uplo), unit or non-unit diagonal (diag), and \(\mathrm{op}(A)\) one of \(A, A^T, A^H\). B and C are m x n; A is m x m (Left) or n x n (Right). Under Diag::Unit the stored diagonal of A is not read.

Unlike reference BLAS ?trmm, which overwrites B, this writes the product into C and leaves B unmodified. trsm, by contrast, is in place. Also callable as trmm(ctx, A, B, C, TrmmOptions<T>{...}), with owning Matrix arguments, and without Ba (taken from ctx.backend()).

Each call takes a kernel family from the tuned table for its shape (Kernel selection tables): triangular (Side::Left only: row tiles that skip the zero half of A), expand (op(A) written densely into scratch leased from the queue's arena, then one strided-batched gemm) or vendor (the library's per-item ?trmm loop). Pin one with BATCHLAS_TRMM_ROUTE = auto | native | vendor | triangular | expand.

Template Parameters

Ba	backend the call is compiled for; must match ctx's device
T	scalar type: float, double, std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of triangular matrices; only the uplo triangle is read
B	batch of m x n input matrices; not modified
C	batch of m x n output matrices; overwritten with the product
alpha	scale of the product
side	whether op(A) multiplies from the left or the right
uplo	which triangle of A holds the data
transA	op() applied to A
diag	whether A has an implicit unit diagonal

Returns

event of the last enqueued kernel; C is valid once it completes

Precondition

All operands have the same batch size and conforming shapes per item.

Exceptions

std::invalid_argument	if the shapes do not conform, or if BATCHLAS_TRMM_ROUTE names a family that is not compiled for T or cannot run this call (native and vendor instead fall back to the tuned choice with a warning)
std::runtime_error	if no family can run the call in a build with the vendor BLAS (a heterogeneous batch: every family takes one (n, k) per launch)
batchlas::NoRouteError	in a build without the vendor BLAS for Ba, unless the call is Backend::CUDA on a GPU, with homogeneous operands, batch <= 65535 and a shape the triangular tiles or the expand scratch admit (docs/perf/level3.md).

See also

trsm, TrmmOptions, docs/cpp-api.md

trsm() [1/2]

template<Backend Back, typename T>

Event batchlas::trsm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		T	alpha,
		Side	side,
		Uplo	uplo,
		Transpose	transA,
		Diag	diag )

Batched triangular solve with multiple right-hand sides, in place.

For every batch item solves

\[ \mathrm{op}(A) \, X = \alpha B \quad (\texttt{Side::Left}), \qquad X \, \mathrm{op}(A) = \alpha B \quad (\texttt{Side::Right}) \]

and overwrites B with \(X\). A is triangular (uplo), unit or non-unit diagonal (diag), and \(\mathrm{op}(A)\) is one of \(A, A^T, A^H\). B is m x n; A is m x m (Left) or n x n (Right). No singularity check is made: a zero on a non-unit diagonal gives Inf/NaN.

Also callable as trsm(ctx, A, B, TrsmOptions<T>{...}), with owning Matrix arguments, and without Back (taken from ctx.backend()).

Template Parameters

Back	backend the call is compiled for; must match ctx's device
T	scalar type: float, double, std::complex<float> or std::complex<double>

Parameters

ctx	queue the work is enqueued on
A	batch of triangular matrices; only the uplo triangle is read
B	batch of m x n right-hand sides; overwritten with the solution
alpha	scale of the right-hand side
side	whether op(A) is applied from the left or the right
uplo	which triangle of A holds the data
transA	op() applied to A
diag	whether A has an implicit unit diagonal

Returns

event of the last enqueued kernel; B holds \(X\) once it completes

Exceptions

batchlas::invalid_argument	from trsm_validate_params (bad shape, ld, enum value, or A and B batch sizes that differ), before anything is enqueued
batchlas::NoRouteError	in a build without the vendor BLAS for Back when no native kernel can run the shape

Note

On Backend::NETLIB, alpha == 0 still reads B, so a NaN in B survives (known defect 5, docs/design/known-defects.md).

See also

trmm, TrsmOptions, TRSM, docs/cpp-api.md

trsm() [2/2]

template<Backend Back, typename T>

Event batchlas::trsm ( Queue & , const MatrixView< T, MatrixFormat::Dense > & , const MatrixView< T, MatrixFormat::Dense > & , Side , Uplo , Transpose , Diag , T  )

delete

Deleted: the old argument order with alpha last.

Pass alpha right after B.

Topics
	BLAS level 3: lower-level API
	Argument validation and workspace queries behind the level-3 entry points.