nag_zgbbrd (f08lsc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_zgbbrd (f08lsc)

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_zgbbrd (f08lsc) reduces a complex m by n band matrix to real upper bidiagonal form.

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_zgbbrd (Nag_OrderType order, Nag_VectType vect, Integer m, Integer n, Integer ncc, Integer kl, Integer ku, Complex ab[], Integer pdab, double d[], double e[], Complex q[], Integer pdq, Complex pt[], Integer pdpt, Complex c[], Integer pdc, NagError *fail)

3  Description

nag_zgbbrd (f08lsc) reduces a complex m by n band matrix to real upper bidiagonal form B by a unitary transformation: A=QBPH. The unitary matrices Q and PH, of order m and n respectively, are determined as a product of Givens rotation matrices, and may be formed explicitly by the function if required. A matrix C may also be updated to give C~=QHC.
The function uses a vectorizable form of the reduction.

4  References

None.

5  Arguments

1:     order Nag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by order=Nag_RowMajor. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     vect Nag_VectTypeInput
On entry: indicates whether the matrices Q and/or PH are generated.
vect=Nag_DoNotForm
Neither Q nor PH is generated.
vect=Nag_FormQ
Q is generated.
vect=Nag_FormP
PH is generated.
vect=Nag_FormBoth
Both Q and PH are generated.
Constraint: vect=Nag_DoNotForm, Nag_FormQ, Nag_FormP or Nag_FormBoth.
3:     m IntegerInput
On entry: m, the number of rows of the matrix A.
Constraint: m0.
4:     n IntegerInput
On entry: n, the number of columns of the matrix A.
Constraint: n0.
5:     ncc IntegerInput
On entry: nC, the number of columns of the matrix C.
Constraint: ncc0.
6:     kl IntegerInput
On entry: the number of subdiagonals, kl, within the band of A.
Constraint: kl0.
7:     ku IntegerInput
On entry: the number of superdiagonals, ku, within the band of A.
Constraint: ku0.
8:     ab[dim] ComplexInput/Output
Note: the dimension, dim, of the array ab must be at least
  • max1,pdab×n when order=Nag_ColMajor;
  • max1,m×pdab when order=Nag_RowMajor.
On entry: the original m by n band matrix A.
This is stored as a notional two-dimensional array with row elements or column elements stored contiguously. The storage of elements Aij, for row i=1,,m and column j=max1,i-kl,,minn,i+ku, depends on the order argument as follows:
  • if order=Nag_ColMajor, Aij is stored as ab[j-1×pdab+ku+i-j];
  • if order=Nag_RowMajor, Aij is stored as ab[i-1×pdab+kl+j-i].
On exit: ab is overwritten by values generated during the reduction.
9:     pdab IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) of the matrix A in the array ab.
Constraint: pdabkl+ku+1.
10:   d[minm,n] doubleOutput
On exit: the diagonal elements of the bidiagonal matrix B.
11:   e[minm,n-1] doubleOutput
On exit: the superdiagonal elements of the bidiagonal matrix B.
12:   q[dim] ComplexOutput
Note: the dimension, dim, of the array q must be at least
  • max1,pdq×m when vect=Nag_FormQ or Nag_FormBoth;
  • 1 otherwise.
The i,jth element of the matrix Q is stored in
  • q[j-1×pdq+i-1] when order=Nag_ColMajor;
  • q[i-1×pdq+j-1] when order=Nag_RowMajor.
On exit: if vect=Nag_FormQ or Nag_FormBoth, contains the m by m unitary matrix Q.
If vect=Nag_DoNotForm or Nag_FormP, q is not referenced.
13:   pdq IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
  • if vect=Nag_FormQ or Nag_FormBoth, pdq max1,m ;
  • otherwise pdq1.
14:   pt[dim] ComplexOutput
Note: the dimension, dim, of the array pt must be at least
  • max1,pdpt×n when vect=Nag_FormP or Nag_FormBoth;
  • 1 otherwise.
The i,jth element of the matrix is stored in
  • pt[j-1×pdpt+i-1] when order=Nag_ColMajor;
  • pt[i-1×pdpt+j-1] when order=Nag_RowMajor.
On exit: the n by n unitary matrix PH, if vect=Nag_FormP or Nag_FormBoth. If vect=Nag_DoNotForm or Nag_FormQ, pt is not referenced.
15:   pdpt IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array pt.
Constraints:
  • if vect=Nag_FormP or Nag_FormBoth, pdpt max1,n ;
  • otherwise pdpt1.
16:   c[dim] ComplexInput/Output
Note: the dimension, dim, of the array c must be at least
  • max1,pdc×ncc when order=Nag_ColMajor;
  • max1,m×pdc when order=Nag_RowMajor.
The i,jth element of the matrix C is stored in
  • c[j-1×pdc+i-1] when order=Nag_ColMajor;
  • c[i-1×pdc+j-1] when order=Nag_RowMajor.
On entry: an m by nC matrix C.
On exit: c is overwritten by QHC. If ncc=0, c is not referenced.
17:   pdc IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array c.
Constraints:
  • if order=Nag_ColMajor,
    • if ncc>0, pdc max1,m ;
    • if ncc=0, pdc1;
  • if order=Nag_RowMajor, pdcmax1,ncc.
18:   fail NagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.2.1.2 in the Essential Introduction for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_ENUM_INT_2
On entry, vect=value, pdpt=value and n=value.
Constraint: if vect=Nag_FormP or Nag_FormBoth, pdpt max1,n ;
otherwise pdpt1.
On entry, vect=value, pdq=value and m=value.
Constraint: if vect=Nag_FormQ or Nag_FormBoth, pdq max1,m ;
otherwise pdq1.
NE_INT
On entry, kl=value.
Constraint: kl0.
On entry, ku=value.
Constraint: ku0.
On entry, m=value.
Constraint: m0.
On entry, n=value.
Constraint: n0.
On entry, ncc=value.
Constraint: ncc0.
On entry, pdab=value.
Constraint: pdab>0.
On entry, pdc=value.
Constraint: pdc>0.
On entry, pdpt=value.
Constraint: pdpt>0.
On entry, pdq=value.
Constraint: pdq>0.
NE_INT_2
On entry, pdc=value and ncc=value.
Constraint: pdcmax1,ncc.
NE_INT_3
On entry, ncc=value, pdc=value and m=value.
Constraint: if ncc>0, pdc max1,m ;
if ncc=0, pdc1.
On entry, pdab=value, kl=value and ku=value.
Constraint: pdabkl+ku+1.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

7  Accuracy

The computed bidiagonal form B satisfies QBPH=A+E, where
E2 c n ε A2 ,  
cn is a modestly increasing function of n, and ε is the machine precision.
The elements of B themselves may be sensitive to small perturbations in A or to rounding errors in the computation, but this does not affect the stability of the singular values and vectors.
The computed matrix Q differs from an exactly unitary matrix by a matrix F such that
F2 = Oε .  
A similar statement holds for the computed matrix PH.

8  Parallelism and Performance

nag_zgbbrd (f08lsc) is not threaded by NAG in any implementation.
nag_zgbbrd (f08lsc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

The total number of real floating-point operations is approximately the sum of: where k=kl+ku, assuming nk. For this section we assume that m=n.
The real analogue of this function is nag_dgbbrd (f08lec).

10  Example

This example reduces the matrix A to upper bidiagonal form, where
A = 0.96-0.81i -0.03+0.96i 0.00+0.00i 0.00+0.00i -0.98+1.98i -1.20+0.19i -0.66+0.42i 0.00+0.00i 0.62-0.46i 1.01+0.02i 0.63-0.17i -1.11+0.60i 0.00+0.00i 0.19-0.54i -0.98-0.36i 0.22-0.20i 0.00+0.00i 0.00+0.00i -0.17-0.46i 1.47+1.59i 0.00+0.00i 0.00+0.00i 0.00+0.00i 0.26+0.26i .  

10.1  Program Text

Program Text (f08lsce.c)

10.2  Program Data

Program Data (f08lsce.d)

10.3  Program Results

Program Results (f08lsce.r)


nag_zgbbrd (f08lsc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015