NAG CL Interface
f08lec (dgbbrd)

Settings help

CL Name Style:


1 Purpose

f08lec reduces a real m×n band matrix to upper bidiagonal form.

2 Specification

#include <nag.h>
void  f08lec (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)
The function may be called by the names: f08lec, nag_lapackeig_dgbbrd or nag_dgbbrd.

3 Description

f08lec reduces a real m×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_OrderType Input
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.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2: vect Nag_VectType Input
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 Integer Input
On entry: m, the number of rows of the matrix A.
Constraint: m0.
4: n Integer Input
On entry: n, the number of columns of the matrix A.
Constraint: n0.
5: ncc Integer Input
On entry: nC, the number of columns of the matrix C.
Constraint: ncc0.
6: kl Integer Input
On entry: the number of subdiagonals, kl, within the band of A.
Constraint: kl0.
7: ku Integer Input
On entry: the number of superdiagonals, ku, within the band of A.
Constraint: ku0.
8: ab[dim] double Input/Output
Note: the dimension, dim, of the array ab must be at least
  • max(1,pdab×n) when order=Nag_ColMajor;
  • max(1,m×pdab) when order=Nag_RowMajor.
On entry: the original m×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=max(1,i-kl),,min(n,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 Integer Input
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[min(m,n)] double Output
On exit: the diagonal elements of the bidiagonal matrix B.
11: e[min(m,n)-1] double Output
On exit: the superdiagonal elements of the bidiagonal matrix B.
12: q[dim] double Output
Note: the dimension, dim, of the array q must be at least
  • max(1,pdq×m) when vect=Nag_FormQ or Nag_FormBoth;
  • 1 otherwise.
The (i,j)th 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×m orthogonal matrix Q.
If vect=Nag_DoNotForm or Nag_FormP, q is not referenced.
13: pdq Integer Input
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 max(1,m) ;
  • otherwise pdq1.
14: pt[dim] double Output
Note: the dimension, dim, of the array pt must be at least
  • max(1,pdpt×n) when vect=Nag_FormP or Nag_FormBoth;
  • 1 otherwise.
The (i,j)th 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×n orthogonal matrix PT, if vect=Nag_FormP or Nag_FormBoth. If vect=Nag_DoNotForm or Nag_FormQ, pt is not referenced.
15: pdpt Integer Input
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 max(1,n) ;
  • otherwise pdpt1.
16: c[dim] double Input/Output
Note: the dimension, dim, of the array c must be at least
  • max(1,pdc×ncc) when order=Nag_ColMajor;
  • max(1,m×pdc) when order=Nag_RowMajor.
The (i,j)th 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×nC matrix C.
On exit: c is overwritten by QTC. If ncc=0, c is not referenced.
17: pdc Integer Input
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 max(1,m) ;
    • if ncc=0, pdc1;
  • if order=Nag_RowMajor, pdcmax(1,ncc).
18: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface 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 max(1,n) ;
otherwise pdpt1.
On entry, vect=value, pdq=value and m=value.
Constraint: if vect=Nag_FormQ or Nag_FormBoth, pdq max(1,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: pdcmax(1,ncc).
NE_INT_3
On entry, ncc=value, pdc=value and m=value.
Constraint: if ncc>0, pdc max(1,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 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

7 Accuracy

The computed bidiagonal form B satisfies QBPT=A+E, where
E2 c (n) ε A2 ,  
c(n) 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

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 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)