Overview

How a call reaches a backend: the Queue's backend, owning arguments, and the backend::*_vendor declarations the vendor families call.

Which kernel runs for a shape is decided by flat kernel selection (developer docs: Kernel selection (developer); design: Flat kernel selection; per-op families and tables: Kernel selection tables). Measurements behind each op's choices: Routing and performance evidence.

Every entry point has two spellings. f<Backend::CUDA>(ctx, ...) fixes the backend at compile time; f(ctx, ...) takes it from ctx.backend() through with_backend(). The deducing overload of a positional entry point is generated by BATCHLAS_DISPATCH_ON_QUEUE(f), and the option-struct overloads in blas/options.hh deduce the same way. Library code templated on Backend must call the f<B> spelling, never the deducing one.

Every entry point also accepts owning arguments. A Matrix is a MatrixView and a Vector is a VectorView (public inheritance), so an owning argument binds to a view parameter directly and deduces T and MatrixFormat through derived-to-base deduction, in any position and with any template arguments named.

Pointer checks. The deducing spellings check that every non-empty pointer argument is reachable from the queue's device and throw std::invalid_argument naming the argument otherwise; the f<Backend> spellings do not check. BATCHLAS_SKIP_POINTER_CHECKS turns the check off (latched once per process).

The generating macros are omitted from this reference; see API conventions for their design and traps.

Functions

◆ gemm_vendor()

template<Backend Back, typename T>

Event batchlas::backend::gemm_vendor	(	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 )

Vendor-library implementation of gemm (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::gemm calls it when it selects the vendor kernel family. Same arguments and semantics as batchlas::gemm.

◆ gemv_vendor()

template<Backend B, typename T>

Event batchlas::backend::gemv_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const VectorView< T > &	X,
		const VectorView< T > &	Y,
		T	alpha,
		T	beta,
		Transpose	transA )

Vendor-library implementation of gemv (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::gemv calls it when it selects the vendor kernel family. Same arguments and semantics as batchlas::gemv.

◆ geqrf_vendor()

template<Backend B, typename T>

Event batchlas::backend::geqrf_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< T >	tau,
		Span< std::byte >	work_space )

Vendor arm of geqrf(); called by geqrf() when it selects the vendor kernel family, not by users.

◆ geqrf_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::geqrf_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< T >	tau )

Workspace query of the vendor arm of geqrf().

◆ gesvd_vendor()

template<Backend B, typename T>

Event batchlas::backend::gesvd_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< typename base_type< T >::type >	singular_values,
		const MatrixView< T, MatrixFormat::Dense > &	U,
		const MatrixView< T, MatrixFormat::Dense > &	Vh,
		SvdVectors	jobu,
		SvdVectors	jobvh,
		Span< std::byte >	workspace,
		Span< int32_t >	info_out = Span< int32_t >() )

The vendor solver's SVD (cuSOLVER gesvdjBatched or a LAPACKE loop), as gesvd()'s vendor kernel family calls it; same contract as the general gesvd().

Exceptions

batchlas::unsupported	on CUDA for max(m, n) > 32, a non-packed batch stride or Thin vectors (gesvdjBatched has no econ flag); on ROCm always
batchlas::convergence_error	on NETLIB for a non-converged item when info_out is empty

◆ gesvd_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::gesvd_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< typename base_type< T >::type >	singular_values,
		const MatrixView< T, MatrixFormat::Dense > &	U,
		const MatrixView< T, MatrixFormat::Dense > &	Vh,
		SvdVectors	jobu,
		SvdVectors	jobvh )

Workspace, in bytes, for backend::gesvd_vendor().

◆ getrf_vendor()

template<Backend B, typename T>

Event batchlas::backend::getrf_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< int64_t >	pivots,
		Span< std::byte >	work_space,
		Span< int32_t >	info_out )

Vendor arm of getrf(); called by getrf() when it selects the vendor kernel family, not by users.

◆ getrf_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::getrf_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A )

Workspace query of the vendor arm of getrf().

◆ getri_vendor()

template<Backend B, typename T>

Event batchlas::backend::getri_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		Span< int64_t >	pivots,
		Span< std::byte >	work_space,
		Span< int32_t >	info_out )

Vendor arm of getri(); called by getri() when it selects the vendor kernel family, not by users.

◆ getri_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::getri_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A )

Workspace query of the vendor arm of getri().

◆ getrs_vendor()

template<Backend Back, typename T>

Event batchlas::backend::getrs_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		Transpose	transA,
		Span< int64_t >	pivots,
		Span< std::byte >	work_space )

Vendor arm of getrs(); called by getrs() when it selects the vendor kernel family, not by users.

◆ getrs_vendor_buffer_size()

template<Backend Back, typename T>

size_t batchlas::backend::getrs_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		Transpose	transA )

Workspace query of the vendor arm of getrs().

◆ hemm_vendor()

template<Backend Back, ComplexScalar T>

Event batchlas::backend::hemm_vendor	(	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 )

Vendor-library implementation of hemm (cuBLAS, host BLAS).

Not an entry point: batchlas::hemm calls it. Same arguments and semantics.

◆ her2k_vendor()

template<Backend Back, ComplexScalar T>

Event batchlas::backend::her2k_vendor	(	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 )

Vendor-library implementation of her2k (cuBLAS, host BLAS).

Not an entry point: batchlas::her2k calls it. Same arguments and semantics.

◆ herk_vendor()

template<Backend Back, ComplexScalar T>

Event batchlas::backend::herk_vendor	(	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 )

Vendor-library implementation of herk (cuBLAS, host BLAS).

Not an entry point: batchlas::herk calls it. Same arguments and semantics.

◆ orgqr_vendor()

template<Backend B, typename T>

Event batchlas::backend::orgqr_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< T >	tau,
		Span< std::byte >	workspace )

Vendor arm of orgqr(); called by the public orgqr(), not by users.

◆ orgqr_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::orgqr_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Span< T >	tau )

Workspace query of the vendor arm of orgqr().

◆ ormqr_vendor()

template<Backend B, typename T>

Event batchlas::backend::ormqr_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		Side	side,
		Transpose	trans,
		Span< T >	tau,
		Span< std::byte >	workspace )

Vendor arm of ormqr() (cuSOLVER / rocSOLVER / LAPACKE); not for direct use.

◆ ormqr_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::ormqr_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		Side	side,
		Transpose	trans,
		Span< T >	tau )

Workspace query of the vendor arm of ormqr().

◆ potrf_vendor()

template<Backend B, typename T>

Event batchlas::backend::potrf_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	descrA,
		Uplo	uplo,
		Span< std::byte >	workspace,
		Span< int32_t >	info_out )

Vendor arm of potrf(); called by the public potrf(), not by users.

◆ potrf_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::potrf_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Uplo	uplo )

Workspace query of the vendor arm of potrf().

◆ spmm_vendor()

template<Backend B, typename T, MatrixFormat MFormat>

Event batchlas::backend::spmm_vendor	(	Queue &	ctx,
		const MatrixView< T, MFormat > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B_mat,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Transpose	transA,
		Transpose	transB,
		Span< std::byte >	workspace )

Vendor-library implementation of spmm (cuSPARSE, rocSPARSE, host).

Not an entry point: batchlas::spmm calls it. Same arguments and semantics.

◆ spmm_vendor_buffer_size()

template<Backend B, typename T, MatrixFormat MFormat>

size_t batchlas::backend::spmm_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MFormat > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B_mat,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		T	alpha,
		T	beta,
		Transpose	transA,
		Transpose	transB )

Workspace bytes spmm_vendor needs; called by batchlas::spmm_buffer_size.

◆ syev_vendor()

template<Backend B, typename T>

Event batchlas::backend::syev_vendor	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	descrA,
		Span< typename base_type< T >::type >	eigenvalues,
		JobType	jobtype,
		Uplo	uplo,
		Span< std::byte >	workspace,
		Span< int32_t >	info_out = Span< int32_t >() )

The vendor solver's syev (cuSOLVER, rocSOLVER or a LAPACKE loop), as syev()'s vendor family calls it; same contract as syev(), with info_out as info.

◆ syev_vendor_buffer_size()

template<Backend B, typename T>

size_t batchlas::backend::syev_vendor_buffer_size	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	descrA,
		Span< typename base_type< T >::type >	eigenvalues,
		JobType	jobtype,
		Uplo	uplo )

Workspace, in bytes, for backend::syev_vendor().

◆ symm_vendor()

template<Backend Back, RealScalar T>

Event batchlas::backend::symm_vendor	(	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 )

Vendor-library implementation of symm (cuBLAS, host BLAS).

Not an entry point: batchlas::symm calls it. Same arguments and semantics.

◆ syr2k_vendor()

template<Backend Back, RealScalar T>

Event batchlas::backend::syr2k_vendor	(	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 )

Vendor-library implementation of syr2k (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::syr2k calls it. Same arguments and semantics.

◆ syrk_vendor()

template<Backend Back, RealScalar T>

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

Vendor-library implementation of syrk (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::syrk calls it. Same arguments and semantics.

◆ trmm_vendor()

template<Backend Back, typename T>

Event batchlas::backend::trmm_vendor	(	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 )

Vendor-library implementation of trmm (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::trmm calls it. Same arguments and semantics.

◆ trsm_vendor()

template<Backend Back, typename T>

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

Vendor-library implementation of trsm (cuBLAS, rocBLAS, host BLAS).

Not an entry point: batchlas::trsm calls it after validation, when kernel selection picks the Vendor family. Same semantics as batchlas::trsm, but alpha is the last argument.

◆ with_backend()

template<typename F>

auto batchlas::with_backend	(	Queue &	ctx,
		F &&	f )

inline

Call f with the queue's backend as a compile-time constant.

Converts ctx.backend() into std::integral_constant<Backend, B> and invokes f with it, so the body can name B.value as a template argument:

with_backend(ctx, [&](auto B) { return gemm<B.value, T>(ctx, ...); });

batchlas::gemm

Event 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.

batchlas::with_backend

auto with_backend(Queue &ctx, F &&f)

Call f with the queue's backend as a compile-time constant.

Definition queue-dispatch.hh:163

This is a switch over existing instantiations, not a virtual call.

Template Parameters

F	callable taking std::integral_constant<Backend, B>

Parameters

ctx	queue whose backend is dispatched on
f	callable; every branch must return the same type

Returns: whatever f returns

Exceptions

batchlas::unsupported if ctx.backend() has no implementation in this build (always the case for Backend::MAGMA)

Note: In a build without device fp64 (BATCHLAS_HAS_DEVICE_FP64 0), Backend::SYCL has no double or complex<double> instantiations: f must not name them for Backend::SYCL. The entry points' deducing overloads check this and throw batchlas::unsupported instead.

See also: Queue::backend_available

Definition at line 163 of file queue-dispatch.hh.

◆ with_backend_for()

template<typename T, typename F>

auto batchlas::with_backend_for	(	Queue &	ctx,
		const char *	op,
		F &&	f )

inline

with_backend() for a call on element type T: throws batchlas::unsupported before dispatch when T is double or complex<double> and the queue's backend is Backend::SYCL in a build without device fp64.

Definition at line 171 of file queue-dispatch.hh.

Files
file	include/batchlas/blas/queue-dispatch.hh
	Backend deduction from the Queue and the USM pointer check.

Namespaces
namespace	batchlas::detail

Classes
struct	batchlas::detail::container_elem< A >
struct	batchlas::detail::container_elem< P< T > >
struct	batchlas::detail::container_elem< std::complex< T > >
struct	batchlas::detail::container_elem< Matrix< T, F > >
struct	batchlas::detail::container_elem< MatrixView< T, F > >
struct	batchlas::detail::container_elem< Vector< T > >
struct	batchlas::detail::container_elem< VectorView< T > >
struct	batchlas::detail::container_elem< Span< T > >
struct	batchlas::detail::container_elem< UnifiedVector< T > >

Overview

Functions

◆ gemm_vendor()

◆ gemv_vendor()

◆ geqrf_vendor()

◆ geqrf_vendor_buffer_size()

◆ gesvd_vendor()

◆ gesvd_vendor_buffer_size()

◆ getrf_vendor()

◆ getrf_vendor_buffer_size()

◆ getri_vendor()

◆ getri_vendor_buffer_size()

◆ getrs_vendor()

◆ getrs_vendor_buffer_size()

◆ hemm_vendor()

◆ her2k_vendor()

◆ herk_vendor()

◆ orgqr_vendor()

◆ orgqr_vendor_buffer_size()

◆ ormqr_vendor()

◆ ormqr_vendor_buffer_size()

◆ potrf_vendor()

◆ potrf_vendor_buffer_size()

◆ spmm_vendor()

◆ spmm_vendor_buffer_size()

◆ syev_vendor()

◆ syev_vendor_buffer_size()

◆ symm_vendor()

◆ syr2k_vendor()

◆ syrk_vendor()

◆ trmm_vendor()

◆ trsm_vendor()

◆ with_backend()

◆ with_backend_for()

Files

Namespaces

Classes