f07 Chapter Contents
f07 Chapter Introduction
NAG C Library Manual

NAG Library Function Documentnag_dgbsv (f07bac)

1  Purpose

nag_dgbsv (f07bac) computes the solution to a real system of linear equations
 $AX=B ,$
where $A$ is an $n$ by $n$ band matrix, with ${k}_{l}$ subdiagonals and ${k}_{u}$ superdiagonals, and $X$ and $B$ are $n$ by $r$ matrices.

2  Specification

 #include #include
 void nag_dgbsv (Nag_OrderType order, Integer n, Integer kl, Integer ku, Integer nrhs, double ab[], Integer pdab, Integer ipiv[], double b[], Integer pdb, NagError *fail)

3  Description

nag_dgbsv (f07bac) uses the $LU$ decomposition with partial pivoting and row interchanges to factor $A$ as $A=PLU$, where $P$ is a permutation matrix, $L$ is a product of permutation and unit lower triangular matrices with ${k}_{l}$ subdiagonals, and $U$ is upper triangular with $\left({k}_{l}+{k}_{u}\right)$ superdiagonals. The factored form of $A$ is then used to solve the system of equations $AX=B$.

4  References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

5  Arguments

1:     orderNag_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 ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     nIntegerInput
On entry: $n$, the number of linear equations, i.e., the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
3:     klIntegerInput
On entry: ${k}_{l}$, the number of subdiagonals within the band of the matrix $A$.
Constraint: ${\mathbf{kl}}\ge 0$.
4:     kuIntegerInput
On entry: ${k}_{u}$, the number of superdiagonals within the band of the matrix $A$.
Constraint: ${\mathbf{ku}}\ge 0$.
5:     nrhsIntegerInput
On entry: $r$, the number of right-hand sides, i.e., the number of columns of the matrix $B$.
Constraint: ${\mathbf{nrhs}}\ge 0$.
6:     ab[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array ab must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdab}}×{\mathbf{n}}\right)$.
On entry: the $n$ by $n$ coefficient matrix $A$.
This is stored as a notional two-dimensional array with row elements or column elements stored contiguously. The storage of elements ${A}_{ij}$, for row $i=1,\dots ,n$ and column $j=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,i-{k}_{l}\right),\dots ,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,i+{k}_{u}\right)$, depends on the order argument as follows:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${A}_{ij}$ is stored as ${\mathbf{ab}}\left[\left(j-1\right)×{\mathbf{pdab}}+{\mathbf{kl}}+{\mathbf{ku}}+i-j\right]$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${A}_{ij}$ is stored as ${\mathbf{ab}}\left[\left(i-1\right)×{\mathbf{pdab}}+{\mathbf{kl}}+j-i\right]$.
See Section 8 for further details.
On exit: ab is overwritten by details of the factorization.
The elements, ${u}_{ij}$, of the upper triangular band factor $U$ with ${k}_{l}+{k}_{u}$ super-diagonals, and the multipliers, ${l}_{ij}$, used to form the lower triangular factor $L$ are stored. The elements ${u}_{ij}$, for $i=1,\dots ,n$ and $j=i,\dots ,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,i+{k}_{l}+{k}_{u}\right)$, and ${l}_{ij}$, for $i=1,\dots ,n$ and $j=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,i-{k}_{l}\right),\dots ,i$, are stored where ${A}_{ij}$ is stored on entry.
7:     pdabIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) of the matrix $A$ in the array ab.
Constraint: ${\mathbf{pdab}}\ge 2×{\mathbf{kl}}+{\mathbf{ku}}+1$.
8:     ipiv[n]IntegerOutput
On exit: if no constraints are violated, the pivot indices that define the permutation matrix $P$; at the $i$th step row $i$ of the matrix was interchanged with row ${\mathbf{ipiv}}\left[i-1\right]$. ${\mathbf{ipiv}}\left[i-1\right]=i$ indicates a row interchange was not required.
9:     b[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array b must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdb}}×{\mathbf{nrhs}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\mathbf{pdb}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $B$ is stored in
• ${\mathbf{b}}\left[\left(j-1\right)×{\mathbf{pdb}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{pdb}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $n$ by $r$ right-hand side matrix $B$.
On exit: if NE_NOERROR, the $n$ by $r$ solution matrix $X$.
10:   pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs}}\right)$.
11:   failNagError *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.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{kl}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{kl}}\ge 0$.
On entry, ${\mathbf{ku}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ku}}\ge 0$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{nrhs}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nrhs}}\ge 0$.
On entry, ${\mathbf{pdab}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdab}}>0$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}>0$.
NE_INT_2
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$ and ${\mathbf{nrhs}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs}}\right)$.
NE_INT_3
On entry, ${\mathbf{pdab}}=〈\mathit{\text{value}}〉$, ${\mathbf{kl}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ku}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdab}}\ge 2×{\mathbf{kl}}+{\mathbf{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.
NE_SINGULAR
$U\left(〈\mathit{\text{value}}〉,〈\mathit{\text{value}}〉\right)$ is exactly zero. The factorization has been completed, but the factor $U$ is exactly singular, so the solution could not be computed.

7  Accuracy

The computed solution for a single right-hand side, $\stackrel{^}{x}$, satisfies an equation of the form
 $A+E x^ = b ,$
where
 $E1 = Oε A1$
and $\epsilon$ is the machine precision. An approximate error bound for the computed solution is given by
 $x^-x 1 x1 ≤ κA E1 A1 ,$
where $\kappa \left(A\right)={‖{A}^{-1}‖}_{1}{‖A‖}_{1}$, the condition number of $A$ with respect to the solution of the linear equations. See Section 4.4 of Anderson et al. (1999) for further details.
Following the use of nag_dgbsv (f07bac), nag_dgbcon (f07bgc) can be used to estimate the condition number of $A$ and nag_dgbrfs (f07bhc) can be used to obtain approximate error bounds. Alternatives to nag_dgbsv (f07bac), which return condition and error estimates directly are nag_real_band_lin_solve (f04bbc) and nag_dgbsvx (f07bbc).

The band storage scheme for the array ab is illustrated by the following example, when $n=6$, ${k}_{l}=1$, and ${k}_{u}=2$. Storage of the band matrix $A$ in the array ab:
 $order=Nag_ColMajor * * * + + + * * a13 a24 a35 a46 * a12 a23 a34 a45 a56 a11 a22 a33 a44 a55 a66 a21 a32 a43 a54 a65 * order=Nag_RowMajor * a11 a12 a13 + a21 a22 a23 a24 + a32 a33 a34 a35 + a43 a44 a45 a46 * a54 a55 a56 * * a65 a66 * * *$
Array elements marked $*$ need not be set and are not referenced by the function. Array elements marked $+$ need not be set, but are defined on exit from the function and contain the elements ${u}_{14}$, ${u}_{25}$ and ${u}_{36}$.
The total number of floating point operations required to solve the equations $AX=B$ depends upon the pivoting required, but if $n\gg {k}_{l}+{k}_{u}$ then it is approximately bounded by $\mathit{O}\left(n{k}_{l}\left({k}_{l}+{k}_{u}\right)\right)$ for the factorization and $\mathit{O}\left(n\left(2{k}_{l}+{k}_{u}\right)r\right)$ for the solution following the factorization.
The complex analogue of this function is nag_zgbsv (f07bnc).

9  Example

This example solves the equations
 $Ax=b ,$
where $A$ is the band matrix
 $A = -0.23 2.54 -3.66 0.00 -6.98 2.46 -2.73 -2.13 0.00 2.56 2.46 4.07 0.00 0.00 -4.78 -3.82 and b = 4.42 27.13 -6.14 10.50 .$
Details of the $LU$ factorization of $A$ are also output.

9.1  Program Text

Program Text (f07bace.c)

9.2  Program Data

Program Data (f07bace.d)

9.3  Program Results

Program Results (f07bace.r)