Norms, condition numbers and utilities

Overview

Matrix norms, condition estimates, inversion and scaling helpers.

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

Functions

inv() [1/2]

template<Backend B, typename T>

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

Computes the explicit inverse of each dense square matrix in the batch, \( A_{inv} := A^{-1} \), by LU factorisation (getrf()) and getri().

A is copied into the workspace first and is not modified. Singular items are not reported: check the result where the input may be ill-conditioned.

Parameters

ctx	Execution context/device queue
A	Input matrices to invert, n x n per item; read only
Ainv	Output matrices storing the inverses, n x n per item
workspace	Pre-allocated workspace buffer, at least inv_buffer_size() bytes

Returns

Event Event to track operation completion

inv() [2/2]

template<Backend B, typename T>

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

inv() returning a newly allocated result; workspace is leased from the Queue's arena.

Returns without waiting.

lascl()

template<MatrixFormat MType, typename T>

Event batchlas::lascl	(	Queue &	ctx,
		const MatrixView< T, MType > &	mat,
		T	cfrom,
		T	cto )

Scales mat by cto / cfrom without overflow or underflow (LAPACK ?lascl).

The factor is applied in safe steps when forming cto / cfrom directly would over- or underflow. Instantiated for real float and double, dense format.

Returns

event of the last scaling step

norm() [1/2]

template<typename T, MatrixFormat MF>

Event batchlas::norm	(	Queue &	ctx,
		const MatrixView< T, MF > &	A,
		const NormType	norm_type,
		const Span< float_t< T > >	norms )

Per-item matrix norm, written into a caller-owned span.

For each batch item \(A_i\), norms[i] receives \(\|A_i\|\) in the requested norm: Frobenius, One (max column sum), Inf (max row sum), Max (max absolute entry) or Spectral (largest \(|\lambda|\)).

Template Parameters

T	float, double, std::complex<float> or std::complex<double>
MF	matrix format; only MatrixFormat::Dense is instantiated

Parameters

ctx	queue the kernels are enqueued on
A	batch of matrices; not modified
norm_type	which norm
norms	device-accessible output, at least A.batch_size() elements

Returns

event of the last enqueued kernel; norms is valid after it (Spectral waits before returning, so norms is valid on return)

Precondition

NormType::Spectral requires square symmetric/Hermitian A (the lower triangle is read).

Exceptions

batchlas::invalid_argument	for Spectral on a non-square A
batchlas::unsupported	for Spectral on a non-dense format or when no backend with a vendor syev is compiled in
batchlas::NoRouteError	for Spectral when the chosen backend's solver library is not compiled in (the vendor syev is called directly; Backend::SYCL calls the native syev instead)
batchlas::unsupported	for double or complex<double> on a GPU without fp64

norm() [2/2]

template<typename T, MatrixFormat MF>

UnifiedVector< float_t< T > > batchlas::norm	(	Queue &	ctx,
		const MatrixView< T, MF > &	A,
		const NormType	norm_type = NormType::Frobenius )

Per-item matrix norm, returned in a new vector.

Blocks until done.

Same contract as the span overload, but allocates the result and waits on it before returning.

Returns

one real norm per batch item

cond() [1/2]

template<Backend B, typename T, MatrixFormat MF>
requires RealScalar<T>

Event batchlas::cond	(	Queue &	ctx,
		const MatrixView< T, MF > &	A,
		const NormType	norm_type,
		const Span< T >	conds,
		const Span< std::byte >	workspace )

Per-item condition number, written into a caller-owned span.

For norm types other than Spectral, conds[i] = \(\|A_i\|\,\|A_i^{-1}\|\), computed by explicit inversion. For NormType::Spectral, the ratio of the largest to the smallest eigenvalue magnitude of a symmetric/Hermitian \(A_i\) (lower triangle read; infinity when an eigenvalue is exactly zero).

Template Parameters

B	backend; deduced from the Queue on the cond(ctx, ...) spelling
T	float or double (real only)
MF	MatrixFormat::Dense

Parameters

ctx	queue the kernels are enqueued on
A	batch of square matrices; not modified
norm_type	which norm
conds	device-accessible output, at least A.batch_size() elements
workspace	scratch of at least cond_buffer_size() bytes; must outlive the kernels

Returns

event of the last enqueued kernel

Precondition

A is square and nonsingular

Exceptions

batchlas::invalid_argument	for Spectral on a non-square A
batchlas::unsupported	for Spectral on a non-dense format

Note

The Spectral path calls the vendor syev directly, bypassing syev's kernel selection, and throws batchlas::NoRouteError in a vendor-free build; see docs/design/known-defects.md (defect 2). Backend::SYCL calls the native syev instead.

cond() [2/2]

template<Backend B, typename T, MatrixFormat MF>
requires RealScalar<T>

UnifiedVector< T > batchlas::cond	(	Queue &	ctx,
		const MatrixView< T, MF > &	A,
		const NormType	norm_type )

Per-item condition number, returned in a new vector.

Blocks until done.

Leases its workspace from the queue's arena and waits before returning.

Returns

one condition number per batch item

random_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42,
		OrthoAlgorithm	algo = OrthoAlgorithm::CGS2 )

Random dense matrices with a prescribed log10 condition number.

Builds \(A_i = U \Sigma V^H\) with random orthonormal factors and a singular spectrum chosen so that \(\log_{10}\kappa(A_i)\) equals log10_kappa in the requested metric. Blocks until the result is written.

Note

On Backend::NETLIB the result is the diagonal \(\Sigma\) itself, with no random rotation.

Template Parameters

B	backend (not deducible; spell f<Backend, T>(...))
T	scalar type (not deducible)

Parameters

ctx	queue the kernels are enqueued on
n	order of each matrix, > 0
log10_kappa	target \(\log_{10}\kappa\), >= 0 (>= \(\log_{10} n\) for Frobenius)
metric	NormType::Spectral ( \(\kappa_2\)) or NormType::Frobenius ( \(\kappa_F\))
batch_size	number of matrices, > 0
seed	RNG seed; equal seeds give equal batches
algo	orthogonalisation used to build the random factors. Keep the CGS2 default: Chol-QR and Householder can silently miss the requested kappa.

Returns

a new n x n x batch_size matrix

Exceptions

batchlas::invalid_argument

on a non-positive size, a negative log10_kappa, or a metric other than Spectral/Frobenius

random_hermitian_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_hermitian_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42,
		OrthoAlgorithm	algo = OrthoAlgorithm::CGS2 )

Random symmetric/Hermitian matrices with a prescribed log10 condition number.

As random_with_log10_cond_metric(), with \(A_i = Q \Lambda Q^H\).

random_banded_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_banded_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		int	kd,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42 )

Random banded matrices with a prescribed log10 condition number.

The resulting bandwidth is at most kd; for small kd the result may be diagonal.

Parameters

kd	maximum bandwidth, >= 0

Exceptions

batchlas::invalid_argument

on a negative kd, and as random_with_log10_cond_metric()

random_hermitian_banded_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_hermitian_banded_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		int	kd,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42 )

Random symmetric/Hermitian banded matrices with a prescribed log10 condition number.

Parameters

kd	maximum bandwidth, >= 0

random_tridiagonal_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_tridiagonal_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42 )

Random tridiagonal matrices with a prescribed log10 condition number.

The condition number is set through the diagonal spectrum; the off-diagonals are zero.

random_hermitian_tridiagonal_with_log10_cond_metric()

template<Backend B, typename T>

Matrix< T, MatrixFormat::Dense > batchlas::random_hermitian_tridiagonal_with_log10_cond_metric	(	Queue &	ctx,
		int	n,
		float_t< T >	log10_kappa,
		NormType	metric,
		int	batch_size = 1,
		unsigned int	seed = 42 )

Random Hermitian tridiagonal matrices with a prescribed log10 condition number.

transpose() [1/2]

template<typename T, MatrixFormat MF>

Event batchlas::transpose	(	Queue &	ctx,
		const MatrixView< T, MF > &	A,
		const MatrixView< T, MF > &	B )

Batched plain transpose \(B_i := A_i^T\) (no conjugation).

Template Parameters

T	float or double

Parameters

ctx	queue the kernel is enqueued on
A	batch of m x n matrices; not modified
B	batch of n x m matrices, same batch size; must not alias A

Returns

event of the enqueued kernel

transpose() [2/2]

template<typename T, MatrixFormat MF>

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

Batched plain transpose into a newly allocated matrix.

Returns

a new n x m x batch matrix holding \(A_i^T\); valid after the queue is waited on

scale() [1/2]

template<typename T, MatrixFormat MType>

Event batchlas::scale	(	Queue &	ctx,
		const T &	alpha,
		const MatrixView< T, MType > &	mat_view )

In-place A := alpha * A on every element of every item (dense).

Parameters

ctx	queue the kernel is enqueued on
alpha	scale factor
mat_view	matrices to scale, within rows() x cols() (ld and stride honoured)

Returns

event of the kernel

Exceptions

batchlas::unsupported

for CSR

scale() [2/2]

template<typename T>

Event batchlas::scale	(	Queue &	ctx,
		const T &	alpha,
		const VectorView< T > &	vec_view )

In-place x := alpha * x on every entry of every item.

Returns

event of the kernel

Topics
	Utilities: lower-level API
	Workspace queries and the explicit-inverse helper.

Files
file	include/batchlas/blas/extra.hh
	Matrix norms, condition numbers, conditioned test-matrix generators and transpose.