Overview

Value-returning, NumPy-like wrappers over the entry points.

Free functions only, no operator overloads. Membership rule: value-returning, backend from the Queue, workspace from the Queue's arena => linalg::; out-parameter, workspace yours => batchlas::.

Every function here enqueues and returns without waiting, including the value-returning ones: a returned matrix is readable only after ctx.wait(). The exceptions are norm(), cond(), svd(), solve(), solve_spd() and eigvalsh(), which wait because they free local scratch on return. Inputs are never modified, except by the _into forms (which write their last matrix argument) and scale(). A value-returning call allocates its result, so prefer the _into forms in an inner loop. User guide: docs/cpp-api.md (the linalg section); design notes: API conventions.

Functions

◆ elementwise_into()

template<typename T, BinaryOp Op>

Event batchlas::linalg::elementwise_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

Elementwise \(C := A \circ B\) for \(\circ\) = Op, per batch item.

Template Parameters

T	scalar type
Op	Add, Subtract, Multiply (Hadamard) or Divide

Parameters

ctx	queue the kernel is enqueued on
A	first operand
B	second operand, same shape and batch size as A
C	output of the same shape; may alias A or B

Returns: event of the enqueued kernel

◆ axpby_into()

template<typename T>

Event batchlas::linalg::axpby_into	(	Queue &	ctx,
		T	alpha,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		T	beta,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

\(C := \alpha A + \beta B\), elementwise, per batch item.

Parameters

ctx	queue the kernel is enqueued on
alpha	scale of A
A	first operand
beta	scale of B
B	second operand, same shape and batch size as A
C	output of the same shape; may alias A or B

Returns: event of the enqueued kernel

◆ scale()

template<typename T>

Event batchlas::linalg::scale	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		T	alpha )

In-place scaling \(A := \alpha A\).

Returns: event of the enqueued kernel

◆ triangular_mask_into()

template<typename T>

Event batchlas::linalg::triangular_mask_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	C,
		Uplo	uplo,
		int64_t	k = 0 )

\(C :=\) A with everything outside the requested triangle zeroed.

Parameters

ctx	queue the kernel is enqueued on
A	input, m x n per item
C	output of the same shape; may alias A
uplo	Upper keeps the part on and above diagonal k, Lower on and below
k	diagonal offset, as NumPy triu/tril: 0 is the main diagonal, > 0 toward the upper right, < 0 toward the lower left

Returns: event of the enqueued kernel

◆ add_into()

template<typename T>

Event batchlas::linalg::add_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

inline

\(C := A + B\) elementwise; see elementwise_into().

Definition at line 136 of file linalg-ops.hh.

◆ subtract_into()

template<typename T>

Event batchlas::linalg::subtract_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

inline

\(C := A - B\) elementwise; see elementwise_into().

Definition at line 145 of file linalg-ops.hh.

◆ multiply_into()

template<typename T>

Event batchlas::linalg::multiply_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

inline

\(C := A \odot B\) elementwise (Hadamard), not the matrix product; see matmul().

Definition at line 154 of file linalg-ops.hh.

◆ divide_into()

template<typename T>

Event batchlas::linalg::divide_into	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatrixView< T, MatrixFormat::Dense > &	C )

inline

\(C := A \oslash B\) elementwise; see elementwise_into().

Definition at line 163 of file linalg-ops.hh.

◆ add()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::add	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B )

inline

Returns a new matrix \(A + B\) (elementwise).

Definition at line 184 of file linalg-ops.hh.

◆ subtract()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::subtract	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B )

inline

Returns a new matrix \(A - B\) (elementwise).

Definition at line 195 of file linalg-ops.hh.

◆ multiply()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::multiply	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B )

inline

Returns a new matrix \(A \odot B\) (Hadamard, not matmul()).

Definition at line 205 of file linalg-ops.hh.

◆ divide()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::divide	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B )

inline

Returns a new matrix \(A \oslash B\) (elementwise).

Definition at line 215 of file linalg-ops.hh.

◆ scaled()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::scaled	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		T	alpha )

inline

Returns a new matrix \(\alpha A\); A is not modified (scale() works in place).

Definition at line 225 of file linalg-ops.hh.

◆ matmul()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::matmul	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		const MatmulOptions< T > &	opts = {} )

inline

Returns a new matrix \(C = \alpha\,\mathrm{op}(A)\,\mathrm{op}(B)\).

Parameters

ctx	queue; supplies the backend
A	op(A) is m x k per item
B	op(B) is k x n per item, same batch size
opts	alpha, transA, transB, precision

Returns: m x n x batch matrix, fully written once the queue is waited on

Definition at line 251 of file linalg-ops.hh.

◆ cholesky()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::cholesky	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Uplo	uplo = kDefaultUplo )

inline

Returns the Cholesky factor of a Hermitian positive-definite A; A is not modified.

Parameters

ctx	queue; supplies the backend and the arena
A	n x n per item; the uplo triangle is read
uplo	Lower gives \(L\) with \(A = LL^H\), Upper gives \(U\) with \(A = U^HU\)

Returns: new matrix holding the factor in the uplo triangle; the other triangle holds a copy of A's

Note: No status is reported; a non-positive-definite item yields an undefined factor.

Definition at line 280 of file linalg-ops.hh.

◆ eigvalsh()

template<typename T>

UnifiedVector< typename base_type< T >::type > batchlas::linalg::eigvalsh	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Uplo	uplo = kDefaultUplo )

inline

Returns the eigenvalues of a symmetric/Hermitian A, ascending per item; A is not modified.

Parameters

ctx	queue; supplies the backend and the arena
A	n x n per item; the uplo triangle is read
uplo	triangle of A that is read

Returns: real vector of n * batch_size values, item b at offset b * n

Definition at line 295 of file linalg-ops.hh.

◆ eigh()

template<typename T>

Eigh< T > batchlas::linalg::eigh	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		Uplo	uplo = kDefaultUplo )

inline

Eigenvalues and eigenvectors of a symmetric/Hermitian A; A is not modified.

Parameters

ctx	queue; supplies the backend and the arena
A	n x n per item; the uplo triangle is read
uplo	triangle of A that is read

Returns: values, vectors and per-item info, valid after the queue is waited on

Exceptions

batchlas::invalid_argument if A is not square

Definition at line 324 of file linalg-ops.hh.

◆ solve()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::solve	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		Transpose	trans = Transpose::NoTrans )

inline

Solves \(\mathrm{op}(A_i)X_i = B_i\) by LU with partial pivoting; returns X.

Neither A nor B is modified; pivots and workspace come from the arena. No status is reported: a singular or near-singular item yields a plausible-looking but wrong X, so check the residual where conditioning is not known.

Parameters

ctx	queue; supplies the backend and the arena
A	n x n per item
B	n x nrhs per item, same batch size
trans	op(A)

Returns: new n x nrhs x batch matrix

Exceptions

batchlas::internal_error for NoTrans when an extent (n, nrhs or batch) is below 1: gesv has no kernel for an empty problem

Definition at line 357 of file linalg-ops.hh.

◆ solve_spd()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::solve_spd	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		const MatrixView< T, MatrixFormat::Dense > &	B,
		Uplo	uplo = Uplo::Lower )

inline

Solves \(A_iX_i = B_i\) for Hermitian positive-definite A by Cholesky; returns X.

About half the arithmetic of solve(), which stays the safe default: the SPD claim is the caller's. A matrix that is not positive definite gives an undefined X for that item, as LAPACK ?POSV, and nothing is reported. Neither A nor B is modified; the workspace comes from the arena.

Parameters

ctx	queue; supplies the backend and the arena
A	n x n per item; the uplo triangle is read
B	n x nrhs per item
uplo	triangle of A that is read

Returns: new n x nrhs x batch matrix

Exceptions

batchlas::internal_error when an extent (n, nrhs or batch) is below 1: posv has no kernel for an empty problem

Definition at line 402 of file linalg-ops.hh.

◆ triu()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::triu	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		int64_t	k = 0 )

inline

Returns a copy of A with everything below diagonal k zeroed (NumPy triu).

Definition at line 420 of file linalg-ops.hh.

◆ tril()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::tril	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		int64_t	k = 0 )

inline

Returns a copy of A with everything above diagonal k zeroed (NumPy tril).

Definition at line 430 of file linalg-ops.hh.

◆ inv()

template<typename T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::inv	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A )

inline

Returns \(A^{-1}\) as a new matrix; A is not modified.

Precondition: A is square

Definition at line 445 of file linalg-ops.hh.

◆ transpose()

template<typename T>
requires RealScalar<T>

Matrix< T, MatrixFormat::Dense > batchlas::linalg::transpose	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A )

inline

Returns \(A^T\) as a new matrix.

Real T only.

Plain transpose; a complex call is a compile error because nothing conjugates.

Definition at line 455 of file linalg-ops.hh.

◆ norm()

template<typename T>

UnifiedVector< typename base_type< T >::type > batchlas::linalg::norm	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		NormType	norm_type = NormType::Frobenius )

inline

Returns one norm per batch item.

Blocks until the result is ready.

See also: batchlas::norm for the asynchronous out-parameter form

Definition at line 463 of file linalg-ops.hh.

◆ cond()

template<typename T>
requires RealScalar<T>

UnifiedVector< T > batchlas::linalg::cond	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		NormType	norm_type = NormType::Frobenius )

inline

Returns \(\|A_i\|\,\|A_i^{-1}\|\) per item (eigenvalue-magnitude ratio for Spectral).

Blocks until the result is ready. Real T only.

Definition at line 475 of file linalg-ops.hh.

◆ svd()

template<typename T>

Svd< T > batchlas::linalg::svd	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A,
		SvdVectors	vectors = SvdVectors::All )

inline

Singular value decomposition \(A_i = U_i\Sigma_iV_i^H\); A is not modified.

Blocks before returning (its internal copy of A must outlive the kernels).

Parameters

ctx	queue; supplies the backend and the arena
A	m x n per item
vectors	All or Thin

Returns: U, singular values, Vh and per-item info

Exceptions

batchlas::invalid_argument for SvdVectors::None; call batchlas::gesvd directly for values only

Note: Complex input the one-sided Jacobi kernel cannot take (beyond its size limit, or on a device without sub-group 32) needs the vendor library: no other native gesvd kernel takes complex general input, so a build without it throws batchlas::NoRouteError.

Definition at line 507 of file linalg-ops.hh.

◆ lu()

template<typename T>

Lu< T > batchlas::linalg::lu	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	A )

inline

LU factorisation with partial pivoting, \(A_i = P_iL_iU_i\); A is not modified.

Precondition: A is square

Returns: packed factors and pivots, valid after the queue is waited on

Definition at line 554 of file linalg-ops.hh.

Enumerations

◆ BinaryOp

enum class batchlas::linalg::BinaryOp

strong

Elementwise operation selected by elementwise_into().

Enumerator
Add
Subtract
Multiply
Divide

Definition at line 54 of file linalg-ops.hh.

Variables

◆ kDefaultUplo

Uplo batchlas::linalg::kDefaultUplo = Uplo::Lower

inlineconstexpr

Default triangle of the linalg wrappers that read one.

Definition at line 270 of file linalg-ops.hh.

Files
file	include/batchlas/blas/linalg-ops.hh
	The batchlas::linalg convenience layer: elementwise operations and value-returning wrappers.

Classes
struct	batchlas::linalg::MatmulOptions< T >
	Options for matmul(). Deliberately has no beta: C is freshly allocated. More...
struct	batchlas::linalg::Eigh< T >
	Result of eigh(). More...
struct	batchlas::linalg::Svd< T >
	Result of svd(). More...
struct	batchlas::linalg::Lu< T >
	Result of lu(). More...

Overview

Functions

◆ elementwise_into()

◆ axpby_into()

◆ scale()

◆ triangular_mask_into()

◆ add_into()

◆ subtract_into()

◆ multiply_into()

◆ divide_into()

◆ add()

◆ subtract()

◆ multiply()

◆ divide()

◆ scaled()

◆ matmul()

◆ cholesky()

◆ eigvalsh()

◆ eigh()

◆ solve()

◆ solve_spd()

◆ triu()

◆ tril()

◆ inv()

◆ transpose()

◆ norm()

◆ cond()

◆ svd()

◆ lu()

Enumerations

◆ BinaryOp

Variables

◆ kDefaultUplo

Files

Classes