syev and its tiers, selected-range syevx, and the iterative eigensolvers.
Lower-level functions (algorithm-specific variants, workspace queries, validation and helpers): Eigensolvers: lower-level API.
| Event batchlas::syevx |
( |
Queue & | ctx, |
|
|
const MatrixView< T, MFormat > & | A, |
|
|
Span< typename base_type< T >::type > | W, |
|
|
size_t | neigs, |
|
|
Span< std::byte > | workspace, |
|
|
JobType | jobz = JobType::NoEigenVectors, |
|
|
const MatrixView< T, MatrixFormat::Dense > & | V = MatrixView< T, MatrixFormat::Dense >(), |
|
|
const SyevxParams< T > & | params = SyevxParams< T >(), |
|
|
Span< int32_t > | info = Span< int32_t >() ) |
Selected eigenpairs of a batch of symmetric/Hermitian matrices, dense or CSR.
Computes \( A v = \lambda v \) for the part of the spectrum that params.select names: the neigs largest or smallest eigenpairs (Extremal, with SyevxParams::find_largest) or an index block (Index). A value interval (Value) has a data-dependent count and needs the overload that reports m.
The algorithm comes from syevx_select_algorithm(): Direct (full syev() on a private copy, then selection), DirectSubset (two-stage reduction plus stebz()/stein()), LOBPCG or Filtered (Chebyshev subspace iteration). A is never modified; the direct paths read its lower triangle. Asynchronous: returns once the work is enqueued.
- Template Parameters
-
- Parameters
-
| ctx | queue the work is enqueued on |
| A | batch of n x n symmetric/Hermitian matrices, dense or CSR |
| W | eigenvalue output (real type), neigs entries per batch item |
| neigs | CAPACITY of W and of V's columns per item, not the number produced |
| workspace | at least syevx_buffer_size() bytes |
| jobz | whether eigenvectors are written to V |
| V | n x neigs eigenvector output per item; used only for EigenVectors |
| params | selection range and algorithm parameters |
| info | per-item convergence status (0 = converged, > 0 LAPACK-like), or an empty span to not request it; see docs/cpp-api.md |
- Returns
- event of the last enqueued kernel
- Exceptions
-
| batchlas::invalid_argument | for SyevxSelect::Value (use the m-taking overload); an Index block outside [0, n) or with neigs != iu - il + 1; a non-extremal range with CSR input or an explicit LOBPCG/Filtered method; an ILU(k) or Jacobi preconditioner with find_largest, or conflicting preconditioner fields. |
- See also
- SYEVX, syevx range selection: design record
| Event batchlas::syevx |
( |
Queue & | ctx, |
|
|
const MatrixView< T, MFormat > & | A, |
|
|
Span< typename base_type< T >::type > | W, |
|
|
Span< int32_t > | m, |
|
|
size_t | neigs, |
|
|
Span< std::byte > | workspace, |
|
|
JobType | jobz = JobType::NoEigenVectors, |
|
|
const MatrixView< T, MatrixFormat::Dense > & | V = MatrixView< T, MatrixFormat::Dense >(), |
|
|
const SyevxParams< T > & | params = SyevxParams< T >(), |
|
|
Span< int32_t > | info = Span< int32_t >() ) |
syevx() with a per-batch-item count of eigenpairs actually found.
Required for SyevxSelect::Value.
Item b gets min(m[b], neigs) eigenpairs (the lowest ones, when truncating), the rest of its W is left untouched, the remaining columns of its V are written as EXACTLY ZERO so the back-transform can run over a uniform column count, and m[b] reports the TRUE count, so m[b] > neigs is the caller's overflow signal. Other parameters as for the m-less form.
- Parameters
-
| m | Per-item count, at least A.batch_size() entries. Device-writable. |
- Trap
- Unambiguous against the m-less forms only because Span's scalar constructor is explicit; a bare {} in positions 4-6 matches both and is ambiguous.
Eigenvalues, and optionally eigenvectors, of a batch of symmetric/Hermitian matrices (LAPACK ?syev / ?heev).
Computes \( A = Q \Lambda Q^H \) for every batch item from its uplo triangle. The kernel family is the first entry of the nearest row of the device's tuned table (tuned/syev.<device>.txt) that can run the call: on a GPU queue a native tier (the n <= 32 sub-group solvers cta, cta_fused and jacobi, which need sub-group size 32; blocked or two_stage at any n), otherwise vendor, the solver library. Pin a family with BATCHLAS_SYEV_ROUTE (e.g. two_stage, vendor). Asynchronous: returns once the work is enqueued.
- Template Parameters
-
| B | backend (NETLIB always runs the vendor LAPACKE path) |
| T | float, double, std::complex<float> or std::complex<double> |
- Parameters
-
| ctx | queue the work is enqueued on |
| descrA | batch of n x n matrices; with JobType::EigenVectors overwritten by the orthonormal eigenvectors (column j pairs with eigenvalue j), otherwise its contents are destroyed |
| eigenvalues | n real eigenvalues per batch item, packed, ascending |
| jobtype | EigenVectors or NoEigenVectors |
| uplo | which triangle of descrA holds the matrix |
| workspace | at least syev_buffer_size() bytes for the same arguments |
| info | per-item convergence status: 0 converged, > 0 LAPACK-like (the number of off-diagonals that failed to converge, or 1 where the tier only tracks failure). An EMPTY span means "not requested" and costs nothing; syev_buffer_size() is the same either way. |
- Returns
- event of the last enqueued kernel
- Exceptions
-
| batchlas::invalid_argument | if descrA is not square |
| batchlas::workspace_error | if the workspace span is smaller than the chosen kernel needs |
| batchlas::NoRouteError | when no native kernel can run (e.g. a CPU queue) in a build without the solver library |
| std::invalid_argument | if BATCHLAS_SYEV_ROUTE names a family that is not compiled or cannot run this call (the words native and vendor instead fall back to the tuned choice with a warning) |
- See also
- Kernel selection tables (which family ranks first where), SYEV, docs/cpp-api.md (convergence status)
1.18.0
