NAG Library Function Document

nag_dgbbrd (f08lec)

 Contents

    1  Purpose
    7  Accuracy

1
Purpose

nag_dgbbrd (f08lec) reduces a real m by n band matrix to upper bidiagonal form.

2
Specification

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

3
Description

nag_dgbbrd (f08lec) reduces a real m by n band matrix to upper bidiagonal form B by an orthogonal transformation: A=QBPT. The orthogonal matrices Q and PT, 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~=QTC.
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.3.1.3 in How to Use the NAG Library and its Documentation 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 PT are generated.
vect=Nag_DoNotForm
Neither Q nor PT is generated.
vect=Nag_FormQ
Q is generated.
vect=Nag_FormP
PT is generated.
vect=Nag_FormBoth
Both Q and PT 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] doubleInput/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] doubleOutput
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 orthogonal 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] doubleOutput
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 orthogonal matrix PT, 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] doubleInput/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 QTC. 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.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation 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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

7
Accuracy

The computed bidiagonal form B satisfies QBPT=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 orthogonal matrix by a matrix F such that
F2 = Oε .  
A similar statement holds for the computed matrix PT.

8
Parallelism and Performance

nag_dgbbrd (f08lec) 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 complex analogue of this function is nag_zgbbrd (f08lsc).

10
Example

This example reduces the matrix A to upper bidiagonal form, where
A = -0.57 -1.28 0.00 0.00 -1.93 1.08 -0.31 0.00 2.30 0.24 0.40 -0.35 0.00 0.64 -0.66 0.08 0.00 0.00 0.15 -2.13 -0.00 0.00 0.00 0.50 .  

10.1
Program Text

Program Text (f08lece.c)

10.2
Program Data

Program Data (f08lece.d)

10.3
Program Results

Program Results (f08lece.r)

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