Overview

Reduction to tridiagonal form and the tridiagonal eigensolvers (steqr, stedc, stebz, stein).

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

Functions

◆ tridiagonal_solver()

template<Backend B, typename T>

Event batchlas::tridiagonal_solver	(	Queue &	ctx,
		Span< T >	alphas,
		Span< T >	betas,
		Span< typename base_type< T >::type >	W,
		Span< std::byte >	workspace,
		JobType	jobz,
		const MatrixView< T, MatrixFormat::Dense > &	Q,
		size_t	n,
		size_t	batch_size )

Eigenvalues, and optionally eigenvectors, of a batch of small symmetric tridiagonal matrices by shifted QR with 2x2 reflections.

One work-group of 32 per batch item; the working arrays live in local memory when they fit and in the workspace otherwise. With EigenVectors, Q is first set to the identity.

Parameters

ctx	queue the work is enqueued on
alphas	diagonals, packed: item b at alphas[bn .. bn+n)
betas	off-diagonals, packed with the same stride n
W	eigenvalue output (real type), packed with stride n
workspace	at least tridiagonal_solver_buffer_size() bytes
jobz	whether Q receives the eigenvectors
Q	n x n eigenvector output per item
n	order of each tridiagonal matrix
batch_size	number of batch items

Returns: event of the kernel; the call waits for it before returning

Exceptions

batchlas::convergence_error if an eigenvalue of any item does not deflate within 30 QR steps

Note: steqr() and stedc() are the maintained tridiagonal solvers.

◆ stebz()

template<Backend B, typename T>

Event batchlas::stebz	(	Queue &	ctx,
		const VectorView< T > &	d,
		const VectorView< T > &	e,
		const VectorView< T > &	w,
		Span< int32_t >	m,
		const Span< std::byte > &	ws,
		StebzParams< T >	params = StebzParams< T >() )

Computes selected eigenvalues of a batch of symmetric tridiagonal matrices by bisection on Sturm sequence sign counts.

Eigenvalues only; one work-item per eigenvalue, so a subset costs proportionally less. Use stein() for vectors.

Parameters

ctx	Execution context/device queue
d	Diagonal, n entries per batch item
e	Off-diagonal, n-1 entries per batch item
w	Output eigenvalues; must hold at least the number selected (n for Value)
m	Output count of eigenvalues found, per batch item (device-written)
ws	Pre-allocated workspace buffer, at least stebz_buffer_size() bytes
params	Selection range, tolerance and ordering

Returns: Event Event to track operation completion

Exceptions

batchlas::invalid_argument for n < 1, a short e, m or w, or an invalid index range

◆ stein() [1/2]

template<Backend B, typename T>

Event batchlas::stein	(	Queue &	ctx,
		const VectorView< T > &	d,
		const VectorView< T > &	e,
		const VectorView< T > &	w,
		size_t	k,
		const MatrixView< T, MatrixFormat::Dense > &	Z,
		const Span< std::byte > &	ws,
		SteinParams< T >	params = SteinParams< T >() )

Computes eigenvectors of a batch of symmetric tridiagonal matrices by inverse iteration, given previously computed eigenvalues.

Pairs with stebz().

Parameters

ctx	Execution context/device queue
d	Diagonal, n entries per batch item
e	Off-diagonal, n-1 entries per batch item
w	Eigenvalues, k per batch item, in ascending order (cluster detection walks consecutive values)
k	Number of eigenvectors to compute, at least 1
Z	Output eigenvectors, n x k per batch item, columns matching w
ws	Pre-allocated workspace buffer, at least stein_buffer_size() bytes
params	Iteration count and clustering threshold

Returns: Event Event to track operation completion

Exceptions

batchlas::invalid_argument for n < 1, k < 1, or a short e, w or Z

◆ stein() [2/2]

template<Backend B, typename T>

Event batchlas::stein	(	Queue &	ctx,
		const VectorView< T > &	d,
		const VectorView< T > &	e,
		const VectorView< T > &	w,
		size_t	k,
		Span< const int32_t >	counts,
		const MatrixView< T, MatrixFormat::Dense > &	Z,
		const Span< std::byte > &	ws,
		SteinParams< T >	params = SteinParams< T >() )

stein() with a per-batch-item count of valid eigenvalues.

k is a capacity (columns of Z, entries of w per item); counts[b] is how many leading entries of item b's w are real eigenvalues – the rest hold stale workspace, and are neither iterated on nor joined to a cluster. Columns [counts[b], k) of Z are written as EXACTLY ZERO, not left untouched, so callers may back-transform a uniform k columns. counts is read on the device, so it may be the m span stebz just wrote; empty (or stein_all_counts) means all k are valid, and it is clamped to [0, k]. Other parameters as for the counts-less form.

Exceptions

batchlas::invalid_argument additionally if a non-empty counts is shorter than the batch

◆ steqr()

template<Backend B, typename T>

Event batchlas::steqr	(	Queue &	ctx,
		const VectorView< T > &	d,
		const VectorView< T > &	e,
		const VectorView< T > &	eigenvalues,
		const Span< std::byte > &	ws,
		JobType	jobz = JobType::NoEigenVectors,
		SteqrParams< T >	params = SteqrParams< T >(),
		const MatrixView< T, MatrixFormat::Dense > &	eigvects = MatrixView< T, MatrixFormat::Dense >(),
		Span< int32_t >	info = Span< int32_t >() )

Eigenvalues, and optionally eigenvectors, of a batch of symmetric tridiagonal matrices by implicit QR/QL iteration (LAPACK ?steqr).

Real T only. Runs the CTA kernel (steqr_cta()) when n is at most the device's largest sub-group size (never on ROCm) and the work-group kernel otherwise; steqr_buffer_size() returns the larger of the two needs.

Parameters

ctx	queue the work is enqueued on
d	diagonal, n entries per batch item
e	off-diagonal, n-1 entries per batch item
eigenvalues	output, n per batch item; ascending when SteqrParams::sort is set
ws	at least steqr_buffer_size() bytes
jobz	whether eigvects receives the eigenvectors
params	sweep cap, deflation threshold, sorting and CTA tuning
eigvects	n x n per item; with SteqrParams::back_transform the rotations are applied to its contents, otherwise it is set to the identity first
info	per-item convergence status (0 = converged, > 0 LAPACK-like), or empty to not request it; see docs/cpp-api.md

Exceptions

batchlas::invalid_argument	if eigvects is not n x n with the same batch
batchlas::convergence_error	as steqr_cta() does, when the CTA kernel runs

Returns: event of the last enqueued kernel

See also: STEQR: implicit QR/QL on symmetric tridiagonals

◆ sytrd_blocked()

template<Backend B, typename T>

Event batchlas::sytrd_blocked	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	a_in,
		const VectorView< T > &	d_out,
		const VectorView< T > &	e_out,
		const VectorView< T > &	tau_out,
		Uplo	uplo,
		const Span< std::byte > &	ws,
		int32_t	block_size = tuning::SYTRD_BLOCK_SIZE_MEDIUM )

Blocked symmetric/Hermitian tridiagonal reduction, n > 32: LATRD-style panel plus a BLAS-3 trailing update.

Same SYTD2-style output as sytrd_cta. In-order queue only.

A is overwritten with the reflector storage (LAPACK sytd2 layout, with the tridiagonal entries restored on the first off-diagonal), the diagonal goes to d_out, the off-diagonal to e_out and the reflector scalars to tau_out.

Precondition: ctx is in-order (SYCL kernels and backend BLAS calls are not separately ordered); ws holds at least sytrd_blocked_buffer_size() bytes (the W panel)

Exceptions

batchlas::invalid_argument	on a non-square A, short d/e/tau, a batch mismatch or an out-of-order ctx
batchlas::unsupported	for Uplo::Upper (only Lower is implemented)

◆ sytrd_band_reduction() [1/2]

template<Backend B, typename T>

Event batchlas::sytrd_band_reduction	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	ab_in,
		const VectorView< typename base_type< T >::type > &	d_out,
		const VectorView< typename base_type< T >::type > &	e_out,
		const VectorView< T > &	tau_out,
		Uplo	uplo,
		int32_t	kd,
		const Span< std::byte > &	ws,
		int32_t	block_size )

Symmetric/Hermitian band -> tridiagonal reduction (BANDR1-style).

In-order queue, Uplo::Lower only. (d,e) are real; for complex input e_out is the magnitude of the (possibly phased) subdiagonal, and tau_out is set to 0.

Band storage is as for sytrd_sy2sb(). This overload uses one block size for every sweep.

◆ sytrd_band_reduction() [2/2]

template<Backend B, typename T>

Event batchlas::sytrd_band_reduction	(	Queue &	ctx,
		const MatrixView< T, MatrixFormat::Dense > &	ab_in,
		const VectorView< typename base_type< T >::type > &	d_out,
		const VectorView< typename base_type< T >::type > &	e_out,
		const VectorView< T > &	tau_out,
		Uplo	uplo,
		int32_t	kd,
		const Span< std::byte > &	ws,
		SytrdBandReductionParams	params )

sytrd_band_reduction() with an explicit per-sweep schedule.

◆ stedc()

template<Backend B, typename T>

Event batchlas::stedc	(	Queue &	ctx,
		const VectorView< T > &	d,
		const VectorView< T > &	e,
		const VectorView< T > &	eigenvalues,
		const Span< std::byte > &	ws,
		JobType	jobz,
		StedcParams< T >	params,
		const MatrixView< T, MatrixFormat::Dense > &	eigvects,
		Span< int32_t >	info = Span< int32_t >() )

Eigenvalues and eigenvectors of a batch of symmetric tridiagonal matrices by divide and conquer (LAPACK ?stedc).

Splits each matrix recursively down to leaves of recursion_threshold, solves the leaves with steqr(), and merges pairs by solving the secular equation and forming the merged eigenvectors. Eigenvalues are returned ascending.

Parameters

ctx	queue the work is enqueued on
d	diagonal, n entries per batch item
e	off-diagonal, n-1 entries per batch item
eigenvalues	output, n per batch item
ws	at least stedc_buffer_size() bytes
jobz	whether eigvects receives the eigenvectors
params	leaf size, merge driver and tuning overrides
eigvects	n x n eigenvector output per item
info	per-item convergence status, or empty; see docs/cpp-api.md. Raised by a merge whose secular solve hits its iteration cap and by a leaf steqr() that runs out of sweeps.

Returns: event of the last enqueued kernel

See also: STEDC: the divide-and-conquer merge

Enumerations

◆ EigenRangeType

enum class batchlas::EigenRangeType

strong

How stebz() selects a subset of the spectrum.

Enumerator
All	Every eigenvalue.
Index	Eigenvalues il..iu inclusive, 0-based, in ascending order.
Value	Eigenvalues in the half-open interval (vl, vu].

Definition at line 714 of file extensions.hh.

◆ SteqrShiftStrategy

enum class batchlas::SteqrShiftStrategy

strong

Shift used by the CTA STEQR's implicit QR/QL steps.

See also: STEQR: implicit QR/QL on symmetric tridiagonals

Enumerator
Lapack	LAPACK-style implicit shift (the stable dsteqr formulation).
Wilkinson	Wilkinson shift computed from the trailing 2x2 block.

Definition at line 862 of file extensions.hh.

◆ SteqrUpdateScheme

enum class batchlas::SteqrUpdateScheme

strong

Update scheme of the CTA STEQR's implicit QR/QL steps.

The default (SteqrParams::cta_update_scheme) is EXP.

See also: STEQR: implicit QR/QL on symmetric tridiagonals, section "steqr: the CTA update schemes EXP and PG"

Enumerator
PG	Parlett-Gray style scalar recurrence.
EXP	Explicit similarity update mirroring steqr.cc's bulge-chasing math.

Definition at line 873 of file extensions.hh.

◆ StedcSecularSolver

enum class batchlas::StedcSecularSolver

strong

Secular-equation root finder used by stedc()'s merge step.

Enumerator
Rocm	rocSOLVER-style solver (default).
Legacy	Original BatchLAS solver.

Definition at line 1821 of file extensions.hh.

◆ StedcMergeVariant

enum class batchlas::StedcMergeVariant

strong

How the merge step (secular solve + eigenvector formation) is dispatched.

Enumerator
Auto	Use BatchLAS tuning tables for the current problem size.
Baseline	Serial-per-root path (3 separate kernels).
Fused	One kernel: warp-parallel root solve + build/normalize Qprime columns.
FusedCta	CTA-partitioned root solve using tunable threads per root.

Definition at line 1827 of file extensions.hh.

◆ StedcAlgorithm

enum class batchlas::StedcAlgorithm

strong

Which divide-and-conquer driver runs the merge tree.

Enumerator
Auto	Currently: Levels.
Levels	Level-synchronous: every node at a tree level merges in one launch.
Recursive	Depth-first: one node per launch (kept for A/B comparison).

Definition at line 1835 of file extensions.hh.

Variables

◆ stein_all_counts

Span<const int32_t> batchlas::stein_all_counts {}

inlineconstexpr

Sentinel meaning: every batch item has all k eigenvalues valid.

Trap: Spell this rather than a bare {} at counts: {} in a position two overloads both accept has silently selected the wrong one in this codebase before.

Definition at line 819 of file extensions.hh.

Topics
	Tridiagonal and band reduction: lower-level API
	Kernel-level reductions and solvers (CTA, single-step band reduction, latrd panel, Francis sweep) and workspace queries.

Classes
struct	batchlas::StebzParams< T >
	Parameters for stebz() (bisection on a symmetric tridiagonal matrix). More...
struct	batchlas::SteinParams< T >
	Parameters for stein() (inverse iteration on a symmetric tridiagonal). More...
struct	batchlas::SteqrParams< T >
	Parameters for steqr() and steqr_cta(), and for stedc()'s leaf solves. More...
struct	batchlas::SytrdBandReductionParams
	Sweep schedule for sytrd_band_reduction() (successive band reduction). More...
struct	batchlas::StedcParams< T >
	Parameters for stedc(). More...

Overview

Functions

◆ tridiagonal_solver()

◆ stebz()

◆ stein() [1/2]

◆ stein() [2/2]

◆ steqr()

◆ sytrd_blocked()

◆ sytrd_band_reduction() [1/2]

◆ sytrd_band_reduction() [2/2]

◆ stedc()

Enumerations

◆ EigenRangeType

◆ SteqrShiftStrategy

◆ SteqrUpdateScheme

◆ StedcSecularSolver

◆ StedcMergeVariant

◆ StedcAlgorithm

Variables

◆ stein_all_counts

Topics

Classes