hegvx (USM Version)#
Computes selected eigenvalues, and optionally, the eigenvectors
of a complex generalized Hermitian positive-definite eigenproblem.
This routine belongs to the oneapi::mkl::lapack
namespace.
Description#
The routine computes selected eigenvalues, and optionally, eigenvectors of a complex generalized Hermitian positive-definite eigenproblem of the form
A*x = λ*B*x
, A*B*x = λ*x
, or B*A*x = λ*x
.
Here A
and B
are assumed to be Hermitian and B
is also
positive definite. Eigenvalues and eigenvectors can be selected
by specifying either a range of values or a range of indices for
the desired eigenvalues.
The routine computes selected eigenvalues with the bisection algorithm.
If the eigenvectors are requested, then this routine uses a combination of modified twisted factorization algorithm based on Inderjit Dhillon and Beresford Parlett’s work and the inverse iteration algorithm followed by Gram-Schmidt orthogonalization.
API#
Syntax#
namespace oneapi::mkl::lapack {
sycl::event hegvx(sycl::queue &queue,
int64_t itype,
mkl::job jobz,
mkl::rangev range,
mkl::uplo uplo,
int64_t n,
T *a,
int64_t lda,
T *b,
int64_t ldb,
RT vl,
RT vu,
int64_t il,
int64_t iu,
RT abstol,
int64_t *m,
RT *w,
T *z,
int64_t ldz,
T *scratchpad,
int64_t scratchpad_size,
const std::vector<sycl::event> &events = {})
}
hegvx
(USM version) supports the following precision and
devices.
T |
RT |
Devices Supported |
---|---|---|
|
|
CPU and GPU* |
|
|
CPU and GPU^ |
*Interface support only; all computations are performed on the CPU.
^Hybrid support; some computations are performed on the CPU.
Input Parameters#
- queue
Device queue where calculations will be performed.
- itype
Must be 1 or 2 or 3. Specifies the problem type to be solved:
if itype
= 1
, the problem type isA*x = lambda*B*x;
if itype
= 2
, the problem type isA*B*x = lambda*x;
if itype
= 3
, the problem type isB*A*x = lambda*x
.- jobz
Must be
job::novec
orjob::vec
.If
jobz = job::novec
, then only eigenvalues are computed.If
jobz = job::vec
, then eigenvalues and eigenvectors are computed.- range
Must be
rangev::all
,rangev::values
orrangev::indices
.If
range = rangev::all
, then all the eigenvalues and eigenvectors (if requested byjobz
parameters) are computed.If
range = rangev::values
, then eigenvalues in the interval(vl, vu]
and corresponding eigenvectors (if requested byjobz
parameters) are computed.If
range = rangev::indices
, then theil
-th throughiu
-th eigenvalues and corresponding eigenvectors (if requested byjobz
parameters) are computed.- uplo
Must be
uplo::upper
oruplo::lower
.If
uplo = uplo::upper
, a stores the upper triangular part ofA
.If
uplo = uplo::lower
, a stores the lower triangular part ofA
.- n
The order of the matrices
A
andB
(0 ≤ n
).- a
Pointer to the array of size
a(lda,*)
containing the upper or lower triangle of the Hermitian matrixA
, as specified by uplo.The second dimension of a must be at least
max(1, n)
.- lda
The leading dimension of a. Must be at least
max(1,n)
.- b
Pointer to the array of size
b(ldb,*)
containing the upper or lower triangle of the Hermitian matrixB
, as specified by uplo.The second dimension of b must be at least
max(1, n)
.- ldb
The leading dimension of b; at least
max(1,n)
.- vl
If
range = rangev::values
, the lower bound of the interval to be searched for eigenvalues.vl
must be less thanvu
. Not referenced ifrange = rangev::all
orrange = rangev::indices
.- vu
If
range = rangev::values
, the upper bound of the interval to be searched for eigenvalues.vl
must be less thanvu
. Not referenced ifrange = rangev::all
orrange = rangev::indices
.- il
If
range = rangev::indices
, the one-based index of the smallest eigenvalue to be returned. Must be1 ≤ il ≤ iu ≤ n
ifn > 0
andil = 1
andiu = 0
ifn = 0
. Not referenced ifrange = rangev::all
orrange = rangev::values
.- iu
If
range = rangev::indices
, the one-based index of the largest eigenvalue to be returned. Must be1 ≤ il ≤ iu ≤ n
ifn > 0
andil = 1
andiu = 0
ifn = 0
. Not referenced ifrange = rangev::all
orrange = rangev::values
.- abstol
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval
[a,b]
of width less than or equal toabstol + eps * max( |a|,|b| )
, whereeps
is the machine precision. Ifabstol
is less than or equal to zero, theneps*|T|
will be used in its place, where|T|
is the 1-norm of the tridiagonal matrix obtained by reducing A to tridiagonal form.- ldz
The leading dimension of z. Must be at least
max(1,n)
.- scratchpad
Pointer to scratchpad memory to be used by the routine for storing intermediate results.
- scratchpad_size
Size of scratchpad memory as a number of floating point elements of type
T
. Size should not be less than the value returned by the hegvx_scratchpad_size function.- events
List of events to wait for before starting computation. Defaults to empty list.
Output Parameters#
- a
On exit the upper triangle (if
uplo = uplo::upper
) or the lower triangle (ifuplo = uplo::lower
) ofA
, including the diagonal, is destroyed.- b
On normal exit, the part of b containing the matrix is overwritten by the triangular factor
U
orL
from the Cholesky factorizationB
=U
T*U
orB = L*L
T.- m
The total number of eigenvalues found,
0 ≤ m ≤ n
.- w
Pointer to array of size at least n. On normal exit, the first m elements contain the selected eigenvalues of the matrix
A
in ascending order.- z
If
jobz = job::vec
, then on normal exit the first m columns of Z contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with thei
-th column of Z holding the eigenvector associated withw(i)
. Ifjobz = job::novec
, then Z is not referenced. Note: the user must ensure that at leastmax(1, m)
columns are supplied in the array Z; ifrange = rangev::values
, the exact value of m is not known in advance and an upper bound must be used.
Exceptions#
Exception |
Description |
---|---|
|
This exception is thrown when problems occur during calculations. You can obtain the info code of the problem using the info() method of the exception object: If If If If |
Return Values#
Output event to wait on to ensure computation is complete.