Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?gghd3

Reduces a pair of matrices to generalized upper Hessenberg form.

Syntax

lapack_int
LAPACKE_sgghd3
(
int
matrix_layout
,
char
compq
,
char
compz
,
lapack_int
n
,
lapack_int
ilo
,
lapack_int
ihi
,
float
*
a
,
lapack_int
lda
,
float
*
b
,
lapack_int
ldb
,
float
*
q
,
lapack_int
ldq
,
float
*
z
,
lapack_int
ldz
);
lapack_int
LAPACKE_dgghd3
(
int
matrix_layout
,
char
compq
,
char
compz
,
lapack_int
n
,
lapack_int
ilo
,
lapack_int
ihi
,
double
*
a
,
lapack_int
lda
,
double
*
b
,
lapack_int
ldb
,
double
*
q
,
lapack_int
ldq
,
double
*
z
,
lapack_int
ldz
);
lapack_int
LAPACKE_cgghd3
(
int
matrix_layout
,
char
compq
,
char
compz
,
lapack_int
n
,
lapack_int
ilo
,
lapack_int
ihi
,
lapack_complex_float
*
a
,
lapack_int
lda
,
lapack_complex_float
*
b
,
lapack_int
ldb
,
lapack_complex_float
*
q
,
lapack_int
ldq
,
lapack_complex_float
*
z
,
lapack_int
ldz
);
lapack_int
LAPACKE_zgghd3
(
int
matrix_layout
,
char
compq
,
char
compz
,
lapack_int
n
,
lapack_int
ilo
,
lapack_int
ihi
,
lapack_complex_double
*
a
,
lapack_int
lda
,
lapack_complex_double
*
b
,
lapack_int
ldb
,
lapack_complex_double
*
q
,
lapack_int
ldq
,
lapack_complex_double
*
z
,
lapack_int
ldz
);
Include Files
  • mkl.h
Description
?gghd3
 reduces a pair of real or complex matrices (
A
,
B
) to generalized upper Hessenberg form using orthogonal/unitary transformations, where
A
 is a general matrix and
B
 is upper triangular. The form of the generalized eigenvalue problem is
A
*
x
 =
λ
*
B
*
x
,
and
B
 is typically made upper triangular by computing its QR factorization and moving the orthogonal/unitary matrix
Q
 to the left side of the equation.
This subroutine simultaneously reduces
A
 to a Hessenberg matrix
H
:
Q
T
*
A
*
Z
 =
H
 for real flavors
or
Q
T
*
A
*
Z
 =
H
 for complex flavors
and transforms
B
 to another upper triangular matrix
T
:
Q
T
*
B
*
Z
 =
T
 for real flavors
or
Q
T
*
B
*
Z
 =
T
 for complex flavors
in order to reduce the problem to its standard form
H
*
y
 =
λ
*
T
*
y
where
y
 =
Z
T
*
x
 for real flavors
or
y
 =
Z
T
*
x
 for complex flavors.
The orthogonal/unitary matrices
Q
 and
Z
 are determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices
Q
1
 and
Z
1
, so that
for real flavors:
Q
1
 *
A
 *
Z
1
T
 = (
Q
1
*
Q
) *
H
 * (
Z
1
*
Z
)
T
Q
1
 *
B
 *
Z
1
T
 = (
Q
1
*
Q
) *
T
 * (
Z
1
*
Z
)
T
for complex flavors:
Q
1
 *
A
 *
Z
1
H
 = (
Q
1
*
Q
) *
H
 * (
Z
1
*
Z
)
T
Q
1
 *
B
 *
Z
1
T
 = (
Q
1
*
Q
) *
T
 * (
Z
1
*
Z
)
T
If
Q
1
 is the orthogonal/unitary matrix from the QR factorization of
B
 in the original equation
A
*
x
 =
λ
*
B
*
x
, then
?gghd3
 reduces the original problem to generalized Hessenberg form.
This is a blocked variant of
?gghrd
, using matrix-matrix multiplications for parts of the computation to enhance performance.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
compq
= 'N': do not compute
q
;
= 'I':
q
 is initialized to the unit matrix, and the orthogonal/unitary matrix
Q
 is returned;
= 'V':
q
 must contain an orthogonal/unitary matrix
Q
1
 on entry, and the product
Q
1
*
q
 is returned.
compz
= 'N': do not compute
z
;
= 'I':
z
 is initialized to the unit matrix, and the orthogonal/unitary matrix
Z
 is returned;
= 'V':
z
 must contain an orthogonal/unitary matrix
Z
1
 on entry, and the product
Z
1
*
z
 is returned.
n
The order of the matrices
A
 and
B
.
n
≥
 0.
ilo
,
ihi
ilo
 and
ihi
 mark the rows and columns of
a
 which are to be reduced. It is assumed that
a
 is already upper triangular in rows and columns 1:
ilo
 - 1 and
ihi
 + 1:
n
.
ilo
 and
ihi
 are normally set by a previous call to
?ggbal
; otherwise they should be set to 1 and
n
, respectively.
1
≤
ilo
≤
ihi
≤
n
, if
n
 > 0;
ilo
=1 and
ihi
=0, if
n
=0.
a
Array, size
(
lda
*
n
)
.
On entry, the
n
-by-
n
 general matrix to be reduced.
lda
The leading dimension of the array
a
.
lda
≥
 max(1,
n
).
b
Array,
(
ldb
*
n
)
.
On entry, the
n
-by-
n
 upper triangular matrix
B
.
ldb
The leading dimension of the array
b
.
ldb
≥
 max(1,
n
).
q
Array, size
(
ldq
*
n
)
.
On entry, if
compq
 = 'V', the orthogonal/unitary matrix
Q
1
, typically from the QR factorization of
b
.
ldq
The leading dimension of the array
q
.
ldq
≥
n
 if
compq
='V' or 'I';
ldq
≥
 1 otherwise.
z
Array, size
(
ldz
*
n
)
.
On entry, if
compz
 = 'V', the orthogonal/unitary matrix
Z
1
.
Not referenced if
compz
='N'.
ldz
The leading dimension of the array
z
.
ldz
≥
n
 if
compz
='V' or 'I';
ldz
≥
 1 otherwise.
Output Parameters
a
On exit, the upper triangle and the first subdiagonal of
a
 are overwritten with the upper Hessenberg matrix
H
, and the rest is set to zero.
b
On exit, the upper triangular matrix
T
 =
Q
T
B
Z
 for real flavors or
T
 =
Q
H
B
Z
 for complex flavors. The elements below the diagonal are set to zero.
q
On exit, if
compq
='I', the orthogonal/unitary matrix
Q
, and if
compq
 = 'V', the product
Q
1
*
Q
.
Not referenced if
compq
='N'.
z
On exit, if
compz
='I', the orthogonal/unitary matrix
Z
, and if
compz
 = 'V', the product
Z
1
*
Z
.
Not referenced if
compz
='N'.
Return Values
This function returns a value
info
.
= 0: successful exit.
< 0: if
info
 = -
i
, the
i
-th argument had an illegal value.
Application Notes
This routine reduces
A
 to Hessenberg form and maintains
B
 in using a blocked variant of Moler and Stewart's original algorithm, as described by Kagstrom, Kressner, Quintana-Orti, and Quintana-Orti (BIT 2008).

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.