Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

mkl_?geqrf_compact

Computes the QR factorization of a set of general m x n, matrices, stored in Compact format (see Compact Format for details).

Syntax

void mkl_sgeqrf_compact (MKL_LAYOUT layout, MKL_INT m, MKL_INT n, float * ap, MKL_INT ldap, float * taup, float * work, MKL_INT lwork, MKL_INT * info, MKL_COMPACT_PACK format, MKL_INT nm);

void mkl_cgeqrf_compact (MKL_LAYOUT layout, MKL_INT m, MKL_INT n, float * ap, MKL_INT ldap, float * taup, float * work, MKL_INT lwork, MKL_INT * info, MKL_COMPACT_PACK format, MKL_INT nm);

void mkl_dgeqrf_compact (MKL_LAYOUT layout, MKL_INT m, MKL_INT n, double * ap, MKL_INT ldap, double * taup, double * work, MKL_INT lwork, MKL_INT * info, MKL_COMPACT_PACK format, MKL_INT nm);

void mkl_zgeqrf_compact (MKL_LAYOUT layout, MKL_INT m, MKL_INT n, double * ap, MKL_INT ldap, double * taup, double * work, MKL_INT lwork, MKL_INT * info, MKL_COMPACT_PACK format, MKL_INT nm);

Description

The routine forms the QR factorization of a set of general, m x n matrices A, stored in Compact format. The routine does not form the Q factors explicitly. Instead, Q is represented as a product of min(m,n) elementary reflectors. The factorization (output) data will also be stored in Compact format.

NOTE:

Compact routines have some limitations; see Numerical Limitations.

Input Parameters

layout

Specifies whether two-dimensional array storage is row-major (MKL_ROW_MAJOR) or column-major (MKL_COL_MAJOR).

m
The number of rows of Ac; m≥ 0.
n
The number of columns of Ac; n≥ 0.
ap
Points to the beginning of the nm Ac matrices. On entry, ap contains either the upper or the lower triangular part of Ac (see uplo).
ldap
Column stride (column-major layout) or row stride (row-major layout) of Ac.
work
Points to the beginning of the workspace array.
lwork
The size of the work array. If lwork = -1, a workspace query is assumed; the routine only calculates the optimal size of the work array and returns this value as the first entry of the work array.
format
Specifies the format of the compact matrices. See Compact Format or mkl_get_format_compact for details.
nm
Total number of matrices stored in Compact format.

Application Notes:

The compact array that will store the elementary reflectors needs to be allocated before the routine is called and unpacked after. First, the routine mkl_?get_size_compact should be called, to determine the size of taup, and memory for taup should be allocated. After calling mkl_?geqrf_compact, taup stores the elementary reflectors in compact form, so should be unpacked using mkl_?geunpack_compact. See Compact Format for more details, or reference the example below. (Note: the following example is meant to demonstrate the calling sequence to allocate memory and unpack taup. All other parameters are assumed to be already set up before the sequence below is executed.)

MKL_R_TYPE *tau_array[nm];
// ...
tau_buffer_size = mkl_?get_size_compact(min(m, n), 1, format, nm);
MKL_R_TYPE *tau_compact = (MKL_R_TYPE *)mkl_malloc(tau_buffer_size, 128);
mkl_?geqrf_compact(layout, m, n, a_compact, ldap, tau_compact, work, lwork, &info, format, nm);
// Note that here MKL_COL_MAJOR is used because tau is a 1-d array
mkl_?geunpack_compact(MKL_COL_MAJOR, min(m, n), 1, tau_array, min(m, n), tau_compact, min(m, n), format, nm);

Output Parameters

ap
On exit, A c is overwritten by its factorization data. ap points to the beginning of nm factorizations of A c , stored in Compact format. The factorization data is stored as follows: The elements on and above the diagonal contain the min( m , n )-by- n upper trapezoidal matrix R c ( R c is upper triangular if m ≥ n ); the elements below the diagonal, with tau , present the orthogonal matrix Q c as a product of min( m , n ) elementary reflectors (see Orthogonal Factorizations: LAPACK Computational Routines). See Compact Format for more details.
taup

Points to the beginning of a set of the tauc arrays, each of which has size min(m,n), stored in Compact format. tauc contains scalars that define elementary reflectors for Qc in its decomposition in a product of elementary reflectors. taup needs to be allocated by the user before calling this routine. See the application notes (below the description) for more details.

work[0]
On exit contains the minimum value of lwork required for optimum performance. Use this lwork for subsequent runs.
info
The parameter is not currently used in this routine. It is reserved for the future use.