Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

?ungbr

Generates the complex unitary matrix Q or PH determined by ?gebrd.

Syntax

lapack_int LAPACKE_cungbr (int matrix_layout, char vect, lapack_int m, lapack_int n, lapack_int k, lapack_complex_float* a, lapack_int lda, const lapack_complex_float* tau);

lapack_int LAPACKE_zungbr (int matrix_layout, char vect, lapack_int m, lapack_int n, lapack_int k, lapack_complex_double* a, lapack_int lda, const lapack_complex_double* tau);

Include Files

  • mkl.h

Description

The routine generates the whole or part of the unitary matrices Q and PH formed by the routines gebrd. Use this routine after a call to cgebrd/zgebrd. All valid combinations of arguments are described in Input Parameters; in most cases you need the following:

To compute the whole m-by-m matrix Q, use:

LAPACKE_?ungbr(matrix_layout, 'Q', m, m, n, a, lda, tau)

(note that the arraya must have at least m columns).

To form the n leading columns of Q if m > n, use:

LAPACKE_?ungbr(matrix_layout, 'Q', m, n, n, a, lda, tau)

To compute the whole n-by-n matrix PH, use:

LAPACKE_?ungbr(matrix_layout, 'P', n, n, m, a, lda, tau)

(note that the array a must have at least n rows).

To form the m leading rows of PH if m < n, use:

LAPACKE_?ungbr(matrix_layout, 'P', m, m, n, a, lda, tau)

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

vect

Must be 'Q' or 'P'.

If vect = 'Q', the routine generates the matrix Q.

If vect = 'P', the routine generates the matrix PH.

m

The number of required rows of Q or PH.

n

The number of required columns of Q or PH.

k

One of the dimensions of A in ?gebrd:

If vect = 'Q', the number of columns in A;

If vect = 'P', the number of rows in A.

Constraints: m 0, n 0, k 0.

For vect = 'Q': knm if m > k, or m = n if mk.

For vect = 'P': kmn if n > k, or m = n if nk.

a

Arrays:

a, size at least lda*n for column major layout and lda*m for row major layout, is the array a as returned by ?gebrd.

lda

The leading dimension of a; at least max(1, m)for column major layout and max(1, n) for row major layout.

tau

For vect = 'Q', the array tauq as returned by ?gebrd. For vect = 'P', the array taup as returned by ?gebrd.

The dimension of tau must be at least max(1, min(m, k)) for vect = 'Q', or max(1, min(m, k)) for vect = 'P'.

Output Parameters

a

Overwritten by the orthogonal matrix Q or PT (or the leading rows or columns thereof) as specified by vect, m, and n.

Return Values

This function returns a value info.

If info=0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

Application Notes

The computed matrix Q differs from an exactly orthogonal matrix by a matrix E such that ||E||2 = O(ε).

The approximate numbers of possible floating-point operations are listed below:

To compute the whole matrix Q:

(16/3)n(3m2 - 3m*n + n2) if m > n;

(16/3)m3 if mn.

To form the n leading columns of Q when m > n:

(8/3)n2(3m - n2).

To compute the whole matrix PH:

(16/3)n3 if mn;

(16/3)m(3n2 - 3m*n + m2) if m < n.

To form the m leading columns of PH when m < n:

(8/3)n2(3m - n2) if m > n.

The real counterpart of this routine is orgbr.