Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 3/31/2023
Public

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

Document Table of Contents

?orbdb/?unbdb

Simultaneously bidiagonalizes the blocks of a partitioned orthogonal/unitary matrix.

Syntax

call sorbdb( trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, phi, taup1, taup2, tauq1, tauq2, work, lwork, info )

call dorbdb( trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, phi, taup1, taup2, tauq1, tauq2, work, lwork, info )

call cunbdb( trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, phi, taup1, taup2, tauq1, tauq2, work, lwork, info )

call zunbdb( trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, phi, taup1, taup2, tauq1, tauq2, work, lwork, info )

call orbdb( x11,x12,x21,x22,theta,phi,taup1,taup2,tauq1,tauq2[,trans][,signs][,info] )

call unbdb( x11,x12,x21,x22,theta,phi,taup1,taup2,tauq1,tauq2[,trans][,signs][,info] )

Include Files
  • mkl.fi, lapack.f90
Description

The routines ?orbdb/?unbdb simultaneously bidiagonalizes the blocks of an m-by-m partitioned orthogonal matrix X:

Equation

or unitary matrix:

Equation

x11 is p-by-q. q must not be larger than p, m-p, or m-q. Otherwise, x must be transposed and/or permuted in constant time using the trans and signs options.

The orthogonal/unitary matrices p1, p2, q1, and q2 are p-by-p, (m-p)-by-(m-p), q-by-q, (m-q)-by-(m-q), respectively. They are represented implicitly by Housholder vectors.

The bidiagonal matrices b11, b12, b21, and b22 are q-by-q bidiagonal matrices represented implicitly by angles theta(1), ..., theta(q) and phi(1), ..., phi(q-1). b11 and b12 are upper bidiagonal, while b21 and b22 are lower bidiagonal. Every entry in each bidiagonal band is a product of a sine or cosine of theta with a sine or cosine of phi. See [Sutton09] for details.

p1, p2, q1, and q2 are represented as products of elementary reflectors. .

Input Parameters
trans

CHARACTER

= 'T':
x, u1, u2, v1t, v2t are stored in row-major order.
otherwise
x, u1, u2, v1t, v2t are stored in column-major order.
signs

CHARACTER

= 'O':
The lower-left block is made nonpositive (the "other" convention).
otherwise
The upper-right block is made nonpositive (the "default" convention).
m

INTEGER. The number of rows and columns of the matrix X.

p

INTEGER. The number of rows in x11 and x12. 0 pm.

q

INTEGER. The number of columns in x11 and x21. 0 q min(p,m-p,m-q).

x11

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (ldx11,*) .

On entry, the top-left block of the orthogonal/unitary matrix to be reduced.

ldx11

INTEGER. The leading dimension of the array X11. If trans = 'T', ldx11p. Otherwise, ldx11q.

x12

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (ldx12,m-q).

On entry, the top-right block of the orthogonal/unitary matrix to be reduced.

ldx12

INTEGER. The leading dimension of the array X12. If trans = 'N', ldx12p. Otherwise, ldx12m-q.

x21

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (ldx21,q).

On entry, the bottom-left block of the orthogonal/unitary matrix to be reduced.

ldx21

INTEGER. The leading dimension of the array X21. If trans = 'N', ldx21m-p. Otherwise, ldx21q.

x22

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (ldx22,m-q).

On entry, the bottom-right block of the orthogonal/unitary matrix to be reduced.

ldx22

INTEGER. The leading dimension of the array X21. If trans = 'N', ldx22m-p. Otherwise, ldx22m-q.

work

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Workspace array, size (lwork).

lwork

INTEGER. The size of the work array. lworkm-q

If lwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla.

Output Parameters
x11

On exit, the form depends on trans:

If trans='N',
the columns of the lower triangle of x11 specify reflectors for p1, the rows of the upper triangle of x11(1:q - 1, q:q - 1) specify reflectors for q1
otherwise trans='T',
the rows of the upper triangle of x11 specify reflectors for p1, the columns of the lower triangle of x11(1:q - 1, q:q - 1) specify reflectors for q1

x12

On exit, the form depends on trans:

If trans='N',
the columns of the upper triangle of x12 specify the first p reflectors for q2
otherwise trans='T',
the columns of the lower triangle of x12 specify the first p reflectors for q2

x21

On exit, the form depends on trans:

If trans='N',
the columns of the lower triangle of x21 specify the reflectors for p2
otherwise trans='T',
the columns of the upper triangle of x21 specify the reflectors for p2

x22

On exit, the form depends on trans:

If trans='N',
the rows of the upper triangle of x22(q+1:m-p,p+1:m-q) specify the last m-p-q reflectors for q2
otherwise trans='T',
the columns of the lower triangle of x22(p+1:m-q,q+1:m-p) specify the last m-p-q reflectors for p2

theta

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (q). The entries of bidiagonal blocks b11, b12, b21, and b22 can be computed from the angles theta and phi. See the Description section for details.

phi

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (q-1). The entries of bidiagonal blocks b11, b12, b21, and b22 can be computed from the angles theta and phi. See the Description section for details.

taup1

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (p).

Scalar factors of the elementary reflectors that define p1.
taup2

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (m-p).

Scalar factors of the elementary reflectors that define p2.
tauq1

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (q).

Scalar factors of the elementary reflectors that define q1.
tauq2

REAL for sorbdb

DOUBLE PRECISION for dorbdb

COMPLEX for cunbdb

DOUBLE COMPLEX for zunbdb

Array, size (m-q).

Scalar factors of the elementary reflectors that define q2.
info

INTEGER.

= 0: successful exit

< 0: if info = -i, the i-th argument has an illegal value.

Fortran 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or reconstructible arguments, see Fortran 95 Interface Conventions.

Specific details for the routine ?orbdb/?unbdb interface are as follows:

x11

Holds the block of matrix X of size (p, q).

x12

Holds the block of matrix X of size (p, m-q).

x21

Holds the block of matrix X of size (m-p, q).

x22

Holds the block of matrix X of size (m-p, m-q).

theta

Holds the vector of length q.

phi

Holds the vector of length q-1.

taup1

Holds the vector of length p.

taup2

Holds the vector of length m-p.

tauq1

Holds the vector of length q.

taupq2

Holds the vector of length m-q.

trans

Must be 'N' or 'T'.

signs

Must be 'O' or 'D'.