# NAG Library Chapter Introduction

## 1Scope of the Chapter

This chapter is concerned with basic linear algebra routines which perform elementary algebraic operations involving scalars, vectors and matrices. It includes routines which conform to the specifications of the BLAS (Basic Linear Algebra Subprograms).

## 2Background to the Problems

A number of the routines in this chapter meet the specification of the Basic Linear Algebra Subprograms (BLAS) as described in Lawson et al. (1979), Dodson et al. (1991), Dongarra et al. (1988) and Dongarra et al. (1990). The first reference describes a set of routines concerned with operations on scalars and vectors: these will be referred to here as the Level-0 and the Level-1 BLAS; the second reference describes a set of routines concerned with operations on sparse vectors: these will be referred to here as the Level-1 Sparse BLAS; the third reference describes a set of routines concerned with matrix-vector operations: these will be referred to here as the Level-2 BLAS; and the fourth reference describes a set of routines concerned with matrix-matrix operations: these will be referred to here as the Level-3 BLAS.
More generally we refer to the scalar routines in the chapter as Level-0 routines, to the vector routines as Level-1 routines, to the matrix-vector and matrix routines as Level-2 routines, and to the matrix-matrix routines as Level-3 routines. The terminology reflects the number of operations involved. For example, a Level-2 routine involves $\mathit{O}\left({n}^{2}\right)$ operations for an $n×n$ matrix.

### 2.1The Use of BLAS Names

Many of the routines in other chapters of the Library call the routines in this chapter, and in particular a number of the BLAS are called. These routines are usually called by the BLAS name and so, for correct operation of the Library, it is essential that you do not attempt to link your own versions of these routines. If you are in any doubt about how to avoid this, please consult your computer centre or the NAG Response Centre.
The BLAS names are used in order to make use of efficient implementations of the routines when these exist. Such implementations are stringently tested before being used, to ensure that they correctly meet the specification of the BLAS, and that they return the desired accuracy (see, for example, Dodson et al. (1991), Dongarra et al. (1988) and Dongarra et al. (1990)).

### 2.2Background Information

Most of the routines in this chapter implement straightforward scalar, vector and matrix operations that need no further explanation beyond a statement of the purpose of the routine. In this section we give some additional background information to those few cases where additional explanation may be necessary. A sub-section is devoted to each topic.

#### 2.2.1Real plane rotations

There are a number of routines in the chapter concerned with setting up and applying plane rotations. This section discusses the real case and the next section looks at the complex case. For further background information see Golub and Van Loan (1996).
A plane rotation matrix for the $\left(i,j\right)$ plane, ${R}_{ij}$, is an orthogonal matrix that is different from the unit matrix only in the elements ${r}_{ii}$, ${r}_{jj}$, ${r}_{ij}$ and ${r}_{ji}$. If we put
 $R= rii rij rji rjj ,$ (1)
then, in the real case, it is usual to choose ${R}_{ij}$ so that
 $R= -c s -s c , c=cos⁡θ, s=sin⁡θ.$
An exception is routine f06fpf which applies the so-called symmetric rotation for which
 $R= c -s s -c .$ (2)
The application of plane rotations is straightforward and needs no further elaboration, so further comment is made only on the construction of plane rotations.
The most common use of plane rotations is to choose $c$ and $s$ so that for given $a$ and $b$,
 $-c s -s c a b = d 0 .$ (3)
In such an application the matrix $R$ is often termed a Givens rotation matrix. There are two approaches to the construction of real Givens rotations in Chapter F06.
The BLAS routine f06aaf (drotg), see Lawson et al. (1979) and Dodson and Grimes (1982), computes $c$, $s$ and $d$ as
 $d=σa2+b21/2,$
 $c= a/d, d≠0, 1, d=0, s= b/d, d≠0, 0, d=0,$ (4)
where $\sigma =\left\{\begin{array}{cc}\mathrm{sign}a\text{,}& \left|a\right|>\left|b\right|\\ \mathrm{sign}b\text{,}& \left|a\right|\le \left|b\right|\end{array}\right\\text{.}$
The value $z$ defined as
 $z= s, s (5)
is also computed and this enables $c$ and $s$ to be reconstructed from the single value $z$ as
 $c= 0, z=1 1-z21/2, z<1 1/z, z>1 s= 1, z=1 z, z<1 1-c21/2, z>1 .$
The other Chapter F06 routines for constructing Givens rotations are based on the computation of the tangent, $t=\mathrm{tan}\theta$. $t$ is computed as
 $t= 0, b=0 b/a, b≤a.flmax,b≠0 signb/a.flmax, b>a.flmax signb.flmax, b≠0,a=0$ (6)
where $\mathit{flmax}=1/\mathit{flmin}$ and $\mathit{flmin}$ is the small positive value returned by x02amf. The values of $c$ and $s$ are then computed or reconstructed via $t$ as
 $c= 1/1+t21/2, eps≤t≤1/eps 1, t1/eps s= c.t, eps≤t≤1/eps t, t1/eps$ (7)
where $\mathrm{eps}$ is the machine precision. Note that $c$ is always non-negative in this scheme and that the same expressions are used in the initial computation of $c$ and $s$ from $a$ and $b$ as in any subsequent recovery of $c$ and $s$ via $t$. This is the approach used by many of the NAG Library routines that require plane rotations. $d$ is computed simply as
 $d=c.a+s.b.$
You need not be too concerned with the above detail, since routines are provided for setting up, recovering and applying such rotations.
Another use of plane rotations is to choose $c$ and $s$ so that for given $x$, $y$ and $z$
 $-c s -s c x y y z c -s s -c = a 0 0 b .$ (8)
In such an application the matrix $R$ is often termed a Jacobi rotation matrix. The routine that generates a Jacobi rotation (f06bef) first computes the tangent $t$ and then computes $c$ and $s$ via $t$ as described above for the Givens rotation.

#### 2.2.2Complex plane rotations

In the complex case a plane rotation matrix for the $\left(i,j\right)$ plane, ${R}_{ij}$ is a unitary matrix and, analogously to the real case, it is usual to choose ${R}_{ij}$ so that
 $R= -c- s- -s c , c2+s2=1,$ (9)
where $\stackrel{-}{a}$ denotes the complex conjugate of $a$.
The BLAS (see Lawson et al. (1979)) do not contain a routine for the generation of complex rotations, and so the routines in Chapter F06 are all based upon computing $c$ and $s$ via $t=b/a$ in an analogous manner to the real case. $R$ can be chosen to have either $c$ real, or $s$ real and there are routines for both cases.
When $c$ is real then it is non-negative and the transformation
 $-c s- -s c a b = d 0$ (10)
is such that if $a$ is real then $d$ is also real.
When $s$ is real then the transformation
 $-c- s -s c a b = d 0$ (11)
is such that if $b$ is real then $d$ is also real.

#### 2.2.3Elementary real (Householder) reflections

There are a number of routines in the chapter concerned with setting up and applying Householder transformations. This section discusses the real case and the next section looks at the complex case. For further background information see Golub and Van Loan (1996).
A real elementary reflector, $P$, is a matrix of the form
 $P=I-μuuT, μuTu=2,$ (12)
where $\mu$ is a scalar and $u$ is a vector, and $P$ is both symmetric and orthogonal. In the routines in Chapter F06, $u$ is expressed in the form
 $u= ζ z , ζ​ a scalar$ (13)
because in many applications $\zeta$ and $z$ are not contiguous elements. The usual use of elementary reflectors is to choose $\mu$ and $u$ so that for given $\alpha$ and $x$
 $P α x = β 0 , α​ and ​β​ scalars.$ (14)
Such a transformation is often termed a Householder transformation. There are two choices of $\mu$ and $u$ available in Chapter F06.
The first form of the Householder transformation is compatible with that used by LINPACK (see Dongarra et al. (1979)) and has
 $μ=1/ζ.$ (15)
This choice makes $\zeta$ satisfy
 $1≤ζ≤2.$
The second form, and the form used by many of the NAG Library routines, has
 $μ=1$ (16)
which makes
 $1≤ζ≤2.$
In both cases the special setting
 $ζ=0$ (17)
is used by the routines to flag the case where $P=I$.
Note that while there are routines to apply an elementary reflector to a vector, there are no routines available in Chapter F06 to apply an elementary reflector to a matrix. This is because such transformations can readily and efficiently be achieved by calls to the matrix-vector Level 2 BLAS routines. For example, to form $PA$ for a given matrix
 $PA = I-μuuTA=A-μuuTA = A-μubT, b=ATu,$ (18)
and so we can call a matrix-vector product routine to form $b={A}^{\mathrm{T}}u$ and then call a rank-one update routine to form $\left(A-\mu u{b}^{\mathrm{T}}\right)$. Of course, we must skip the transformation when $\zeta$ has been set to zero.

#### 2.2.4Elementary complex (Householder) reflections

A complex elementary reflector, $P$, is a matrix of the form
 $P=I-μuuH, μuHu=2, μ​ real,$
where ${u}^{\mathrm{H}}$ denotes the complex conjugate of ${u}^{\mathrm{T}}$, and $P$ is both Hermitian and unitary. For convenience in a number of applications this definition can be generalized slightly by allowing $\mu$ to be complex and so defining the generalized elementary reflector as
 $P=I-μuuH, μ2uHu=μ+μ-$ (19)
for which $P$ is still unitary, but is no longer Hermitian.
The Chapter F06 routines choose $\mu$ and $\zeta$ so that
 $Reμ=1, Imζ=0$ (20)
and this reduces to (12) with the choice (16) when $\mu$ and $u$ are real. This choice is used because $\mu$ and $u$ can now be chosen so that in the Householder transformation (14) we can make
 $Imβ=0$
and, as in the real case,
 $1≤ζ≤2.$
Rather than returning $\mu$ and $\zeta$ as separate arguments the Chapter F06 routines return the single complex value $\theta$ defined as
 $θ=ζ+i.Imμ, i=-1.$
Obviously $\zeta$ and $\mu$ can be recovered as
 $ζ=Reθ, μ=1+i.Imθ.$
The special setting
 $θ=0$
is used to flag the case where $P=I$, and
 $Reθ≤0, Imθ≠0$
is used to flag the case where
 $P= γ 0 0 I , γ​ a scalar$ (21)
and in this case $\theta$ actually contains the value of $\gamma$. Notice that with both (18) and (21) we merely have to supply $\stackrel{-}{\theta }$ rather than $\theta$ in order to represent ${P}^{\mathrm{H}}$.

## 3Recommendations on Choice and Use of Available Routines

### 3.1Naming Scheme

#### 3.1.1NAG names

Table 1 shows the naming scheme for the routines in this chapter.
 Level-0 Level-1 Level-2 Level-3 integer Chapter F06 routine – F06D_F – – ‘real’ BLAS routine F06A_F F06E_F F06P_F F06Y_F ‘real’ Chapter F06 routine F06B_F F06F_F F06Q_F – F06R_F ‘complex’ BLAS routine – F06G_F F06S_F F06Z_F ‘complex’ Chapter F06 routine F06C_F F06H_F F06T_F – F06U_F ‘mixed type’ BLAS routine – F06J_F – – ‘mixed type’ Chapter F06 routine – F06K_F F06V_F – ‘real’ and ‘complex’ LAPACK routines – – F06W_F F06W_F
Table 1
The heading ‘mixed type’ is for routines where a mixture of data types is involved, such as a routine that returns the real Euclidean length of a complex vector. In future marks of the Library, routines may be included in categories that are currently empty and further categories may be introduced.

#### 3.1.2BLAS names

Those routines which conform to the specifications of the BLAS may be called either by their NAG names or by their BLAS names.
In many implementations of the NAG Library, references to BLAS names may be linked to an efficient machine-specific implementation of the BLAS, usually provided by the vendor of the machine. Such implementations are stringently tested before being used with the NAG Library, to ensure that they correctly meet the specifications of the BLAS, and that they return the desired accuracy. Use of BLAS names is recommended for efficiency.
References to NAG routine names (beginning F06-) are always linked to the code provided in the NAG Library and may be significantly slower than the equivalent BLAS routine.
The names of the Level-2 and Level-3 BLAS follow a simple scheme (which is similar to that used for LAPACK routines in Chapters F07 and F08). Each name has the structure XYYZZZ, where the components have the following meanings:
the initial letter X indicates the data type (real or complex) and precision:
 S real, single precision (in Fortran, REAL) D real, double precision (in Fortran, DOUBLE PRECISION) C complex, single precision (in Fortran, COMPLEX) Z complex, double precision (in Fortran, COMPLEX*16 or DOUBLE COMPLEX)
the second and third letters YY indicate the type of the matrix $A$ (and in some cases its storage scheme):
 GE general GB general band SY symmetric SP symmetric (packed storage) SB symmetric band HE (complex) Hermitian HP (complex) Hermitian (packed storage) HB (complex) Hermitian band TR triangular TP triangular (packed storage) TB triangular band
the remaining $1$, $2$ or $3$ letters ZZZ indicate the computation performed:
 MV matrix-vector product MM matrix-matrix product R rank-1 update R2 rank-2 update RK rank-$k$ update R2K rank-$2k$ update SV solve a system of linear equations SM solve a system of linear equations with a matrix of right-hand sides
Thus the routine dgemv performs a matrix-vector product involving a real general matrix in double precision; the corresponding routine for a complex general matrix is zgemv.
The names of the Level-1 BLAS mostly follow the same convention for the initial letter (S-, C-, D- or Z-), except for a few involving data of mixed type, where the first two characters are precision-dependent.

#### 3.1.3LAPACK names

There are some LAPACK routines in this chapter that have BLAS-like functionalty. Four are equivalent to BLAS routines but for matrices stored in Rectangular Full Packed (RFP) format. The naming convention for these is as above with the addition of the matrix types:
 HF (complex) Hermitian (RFP storage) TF triangular (RFP storage) SF symmetric (RFP storage)
There are an additonal two that compute norms of RFP matrices. These have second and third letters LA (signifying LAPACK), fourth letter N (signifying norm), and fifth and sixth letter signifying matrix type as above. For example zlanhf computes the norm of a Hermitian matrix in RFP format.

### 3.2The Level-0 Scalar Routines

The Level-0 routines perform operations on scalars or on vectors or matrices of order $2$.

### 3.3The Level-1 Vector Routines

The Level-1 routines perform operations either on a single vector or on a pair of vectors.

### 3.4The Level-2 Matrix-vector and Matrix Routines

The Level-2 routines perform operations involving either a matrix on its own, or a matrix and one or more vectors.

### 3.5The Level-3 Matrix-matrix Routines

The Level-3 routines perform operations involving matrix-matrix products.

### 3.6Vector Arguments

Vector arguments (except in the Level-1 Sparse BLAS) are represented by a one-dimensional array, immediately followed by an increment argument whose name consists of the three characters INC followed by the name of the array. For example, a vector $x$ is represented by the two arguments x and incx. The length of the vector, $n$ say, is passed as a separate argument, n.
The increment argument is the spacing (stride) in the array between the elements of the vector. For instance, if $\mathbf{incx}=2$, then the elements of $x$ are in locations $x\left(1\right),x\left(3\right),\dots ,x\left(2n-1\right)$ of the array x and the intermediate locations $x\left(2\right),x\left(4\right),\dots ,x\left(2n-2\right)$ are not referenced.
When $\mathbf{incx}>0$, the vector element ${x}_{i}$ is in the array element $\mathbf{x}\left(1+\left(i-1\right)×\mathbf{incx}\right)$. When $\mathbf{incx}\le 0$, the elements are stored in the reverse order so that the vector element ${x}_{i}$ is in the array element $\mathbf{x}\left(1-\left(n-i\right)×\mathbf{incx}\right)$ and hence, in particular, the element ${x}_{n}$ is in $\mathbf{x}\left(1\right)$. The declared length of the array x in the calling subroutine must be at least $\left(1+\left(\mathbf{n}-1\right)×\left|\mathbf{incx}\right|\right)$.
Negative increments are permitted only for:
• Level-1 routines which have more than one vector argument;
• Level-2 BLAS routines (but not for other Level-2 routines)
Zero increments are formally permitted for Level-1 routines with more than one argument (in which case the element $\mathbf{x}\left(1\right)$ is accessed repeatedly), but their use is strongly discouraged since the effect may be implementation-dependent. There is usually an alternative routine in this chapter, with a simplified argument list, to achieve the required purpose. Zero increments are not permitted in the Level-2 BLAS.
In the Level-1 Sparse BLAS, each routine operates on two vectors $x$ and $y$. The vector $x$ is stored as a compressed sparse vector, and is represented by the three arguments nz, x and indx; nz is the number of ‘interesting’ (usually nonzero) elements of $x$, and indx is a one-dimensional index array such that
 $xindxk=xk, k=1,2,…,nz.$
The (mathematical) length of the vector, $n$ say, does not need to be supplied; it is assumed that $1\le \mathbf{indx}\left(k\right)\le n$. For example, the vector
 $x=0,4,0,0,1,0,0,0,6,0$
could be represented with $\mathbf{nz}=3$, $\mathbf{x}=\left(4,1,6\right)$, $\mathbf{indx}=\left(2,5,9\right)$. The second vector $y$ is stored conventionally, and is represented simply by the one-dimensional array y, with ${y}_{i}$ in $Y\left(i\right)$; the increment is assumed to be $1$. Only the elements $Y\left(\mathbf{indx}\left(k\right)\right)$ are referenced.
Non-positive values of nz are permitted, in which case the routines return immediately — except that functions set their value to zero before returning. For those routines where y is an output argument the values in the array indx must be distinct; violating this condition may yield incorrect results.

### 3.7Matrix Arguments and Storage Schemes

In this chapter the following different storage schemes are used for matrices:
• conventional storage in a two-dimensional array;
• packed and RFP storage for symmetric, Hermitian or triangular matrices;
• band storage for band matrices;
• – storage for spiked matrices.
These storage schemes are compatible with those used in Chapters F07 and F08. (Different schemes for packed or band storage are used in a few older routines in Chapters F01, F02, F03 and F04.)
Chapter F01 provides some utility routines for conversion between storage schemes.
In the examples, $*$ indicates an array element which need not be set and is not referenced by the routines. The examples illustrate only the relevant leading rows and columns of the arrays; array arguments may of course have additional rows or columns, according to the usual rules for passing array arguments in Fortran.

#### 3.7.1Conventional storage

Please see Section 3.3.1 in the F07 Chapter Introduction for full details.

#### 3.7.2Packed storage

Please see Section 3.3.2 in the F07 Chapter Introduction for full details.

#### 3.7.3Rectangular Full Packed (RFP) storage

Please see Section 3.3.3 in the F07 Chapter Introduction for full details.

#### 3.7.4Band storage

Please see Section 3.3.4 in the F07 Chapter Introduction for full details.

#### 3.7.5Unit triangular matrices

Please see Section 3.3.5 in the F07 Chapter Introduction for full details.

#### 3.7.6Real diagonal elements of complex Hermitian matrices

Please see Section 3.3.6 in the F07 Chapter Introduction for full details.

#### 3.7.7Spiked matrices

A few routines in this chapter (f06qsf, f06qwf, f06tsf and f06twf) deal with upper spiked matrices. These are upper triangular matrices with an additional nonzero row or column below the diagonal.
The position of the spike is defined by indices ${k}_{1}$ and ${k}_{2}$; it is assumed that ${k}_{1}<{k}_{2}$. A row spike has nonzero elements in the ${k}_{2}$th row, ${a}_{{k}_{2},k}$ for $k={k}_{1},{k}_{1}+1,\dots ,{k}_{2}-1$; a column spike has nonzero elements in the ${k}_{1}$th column, ${a}_{k+1,{k}_{1}}$ for $k={k}_{1},{k}_{1}+1,\dots ,{k}_{2}-1$. For example, when $n=6$, ${k}_{1}=2$ and ${k}_{2}=5$:
 Row spike Column spike $\left(\begin{array}{llllll}{a}_{11}& {a}_{12}& {a}_{13}& {a}_{14}& {a}_{15}& {a}_{16}\\ & {a}_{22}& {a}_{23}& {a}_{24}& {a}_{25}& {a}_{26}\\ & & {a}_{33}& {a}_{34}& {a}_{35}& {a}_{36}\\ & & & {a}_{44}& {a}_{45}& {a}_{46}\\ & {a}_{52}& {a}_{53}& {a}_{54}& {a}_{55}& {a}_{56}\\ & & & & & {a}_{66}\end{array}\right)$ $\left(\begin{array}{llllll}{a}_{11}& {a}_{12}& {a}_{13}& {a}_{14}& {a}_{15}& {a}_{16}\\ & {a}_{22}& {a}_{23}& {a}_{24}& {a}_{25}& {a}_{26}\\ & {a}_{32}& {a}_{33}& {a}_{34}& {a}_{35}& {a}_{36}\\ & {a}_{42}& & {a}_{44}& {a}_{45}& {a}_{46}\\ & {a}_{52}& & & {a}_{55}& {a}_{56}\\ & & & & & {a}_{66}\end{array}\right)$
The storage scheme adopted by the routines in this chapter is for the upper triangular part of the spiked matrix to be stored conventionally in a two-dimensional array a, with the subdiagonal elements of the spike stored in a separate vector.

### 3.8Option Parameters

Many of the routines in this chapter have one or more option arguments, of type CHARACTER. The descriptions in the routine documents refer only to upper-case values (for example $\mathbf{uplo}=\text{'U'}$ or $\mathbf{uplo}=\text{'L'}$); however, in every case, the corresponding lower-case characters may be supplied (with the same meaning). Any other value is illegal.
A longer character string can be passed as the actual argument, making the calling program more readable, but only the first character is significant. (This is a feature of Fortran.) For example:
```Call dtrsv('Upper','Transpose','Non-unit',...)
```
The following option arguments are used in this chapter:
• If $\mathbf{trans}=\text{'N'}$, operate with the matrix (Not transposed);
• if $\mathbf{trans}=\text{'T'}$, operate with the Transpose of the matrix;
• if $\mathbf{trans}=\text{'C'}$, operate with the Conjugate transpose of the matrix.
• If $\mathbf{uplo}=\text{'U'}$, upper triangle or trapezoid of matrix;
• if $\mathbf{uplo}=\text{'L'}$, lower triangle or trapezoid of matrix.
• If $\mathbf{diag}=\text{'U'}$, unit triangular;
• if $\mathbf{diag}=\text{'N'}$, nonunit triangular.
• If $\mathbf{side}=\text{'L'}$, operate from the left-hand side;
• if $\mathbf{side}=\text{'R'}$, operate from the right-hand side.
• If $\mathbf{pivot}=\text{'V'}$, variable pivot (in applying a sequence of plane rotations);
• if $\mathbf{pivot}=\text{'B'}$, bottom pivot;
• if $\mathbf{pivot}=\text{'T'}$, top pivot;
• if $\mathbf{pivot}=\text{'F'}$, fixed pivot.
• If $\mathbf{direct}=\text{'B'}$, backward sequence of plane rotations;
• if $\mathbf{direct}=\text{'F'}$, forward sequence of plane rotations.
• If $\mathbf{norm}=\text{'1'}$ or $\text{'O'}$, $1$-norm of a matrix;
• if $\mathbf{norm}=\text{'I'}$, $\infty$-norm of a matrix;
• if $\mathbf{norm}=\text{'F'}$ or $\text{'E'}$, Frobenius or Euclidean norm of a matrix;
• if $\mathbf{norm}=\text{'M'}$, maximum absolute value of the elements of a matrix (not strictly a norm).
• If $\mathbf{matrix}=\text{'G'}$, general (rectangular or square) matrix;
• if $\mathbf{matrix}=\text{'U'}$, upper trapezoidal or triangular matrix;
• if $\mathbf{matrix}=\text{'L'}$, lower trapezoidal or triangular matrix.
• if $\mathbf{transr}=\text{'N'}$, matrix stored in normal RFP format (Not transposed).
• if $\mathbf{transr}=\text{'T'}$, transpose of the matrix stored in RFP format.
• if $\mathbf{transr}=\text{'C'}$, conjugate transpose of the matrix stored in RFP format.

#### 3.8.1Matrix norms

The option argument norm specifies different matrix norms whose definitions are given here for reference (for a general $m$ by $n$ matrix $A$):
• One-norm ($\mathbf{norm}=\text{'O'}$ or $\text{'1'}$):
 $A1=maxj∑i=1maij;$
• Infinity-norm ($\mathbf{norm}=\text{'I'}$):
 $A∞=maxi∑j=1naij;$
• Frobenius or Euclidean norm ($\mathbf{norm}=\text{'F'}$ or $\text{'E'}$):
 $AF= ∑i=1m∑j=1naij2 1/2.$
If $A$ is symmetric or Hermitian, ${‖A‖}_{1}={‖A‖}_{\infty }$.
The argument norm can also be used to specify the maximum absolute value ${\mathrm{max}}_{i,j}\left|{a}_{ij}\right|$ (if $\mathbf{norm}=\text{'M'}$), but this is not a norm in the strict mathematical sense.

### 3.9Error Handling

Routines in this chapter do not use the usual NAG Library error-handling mechanism, involving the argument IFAIL.
If one of the Level-2 or Level-3 BLAS routines is called with an invalid value of one of its arguments, then an error message is output on the error message unit (see x04aaf), giving the name of the routine and the number of the first invalid argument, and execution of the program is terminated. The following values of arguments are invalid:
• – any value of the character arguments trans, transa, transb, uplo, side or diag, whose meaning is not specified;
• – a negative value of any of the arguments m, n, k, kl or ku;
• – too small a value for any of the leading dimension arguments;
• – a zero value for the increment arguments incx and incy.
Zero values for the matrix dimensions m, n or k are considered valid.
The other routines in this chapter do not report any errors in their arguments. Normally, if called, for example, with an unspecified value for one of the option arguments, or with a negative value of one of the problem dimensions m or n, they simply do nothing and return immediately.

## 4Functionality Index

 Level 0 (Scalar) operations,
 complex numbers,
 apply similarity rotation to 2 by 2 Hermitian matrix f06chf
 generate a plane rotation, storing the tangent, real cosine f06caf
 generate a plane rotation, storing the tangent, real sine f06cbf
 quotient of two numbers, with overflow flag f06clf
 recover cosine and sine from given tangent, real cosine f06ccf
 recover cosine and sine from given tangent, real sine f06cdf
 real numbers,
 apply similarity rotation to 2 by 2 symmetric matrix f06bhf
 compute (a2 + b2)1 / 2 f06bnf
 compute Euclidean norm from scaled form f06bmf
 eigenvalue of 2 by 2 symmetric matrix f06bpf
 generate a Jacobi plane rotation f06bef
 generate a plane rotation f06aaf (drotg)
 generate a plane rotation storing the tangent f06baf
 quotient of two numbers, with overflow flag f06blf
 recover cosine and sine from given tangent f06bcf
 Level 1 (Vector) operations,
 complex vector(s),
 add scalar times a vector to another vector f06gcf (zaxpy)
 apply a complex plane rotation f06hpf
 apply an elementary reflection to a vector f06htf
 apply a real plane rotation f06kpf (zdrot)
 broadcast a scalar into a vector f06hbf
 copy a real vector to a complex vector f06kff
 copy a vector f06gff (zcopy)
 dot product of two vectors, conjugated f06gbf (zdotc)
 dot product of two vectors, unconjugated f06gaf (zdotu)
 Euclidean norm of a vector f06jjf (dznrm2)
 generate an elementary reflection f06hrf
 generate a sequence of plane rotations f06hqf
 index of element of largest absolute value f06jmf (izamax)
 multiply vector by a complex scalar f06gdf (zscal)
 multiply vector by a complex scalar, preserving input vector f06hdf
 multiply vector by a real scalar f06jdf (zdscal)
 multiply vector by a real scalar, preserving input vector f06kdf
 multiply vector by complex diagonal matrix f06hcf
 multiply vector by real diagonal matrix f06kcf
 multiply vector by reciprocal of a real scalar f06kef
 negate a vector f06hgf
 sum of absolute values of vector-elements f06jkf (dzasum)
 swap two vectors f06ggf (zswap)
 update Euclidean norm in scaled form f06kjf
 Complex vector(s),
 apply plane rotation,
 real cosine, complex sine f06hmf (zrot)
 integer vector(s),
 broadcast a scalar into a vector f06dbf
 copy a vector f06dff
 real vector(s),
 add scalar times a vector to another vector f06ecf (daxpy)
 apply an elementary reflection to a vector (Linpack style) f06fuf
 apply an elementary reflection to a vector (NAG style) f06ftf
 apply a symmetric plane rotation to two vectors f06fpf
 apply plane rotation f06epf (drot)
 broadcast a scalar into a vector f06fbf
 copy a vector f06eff (dcopy)
 cosine of angle between two vectors f06faf
 dot product of two vectors f06eaf (ddot)
 elements of largest and smallest absolute value f06flf
 Euclidean norm of a vector f06ejf (dnrm2)
 generate an elementary reflection (Linpack style) f06fsf
 generate an elementary reflection (NAG style) f06frf
 generate a sequence of plane rotations f06fqf
 index of element of largest absolute value f06jlf (idamax)
 index of last non-negligible element f06klf
 multiply vector by a scalar f06edf (dscal)
 multiply vector by a scalar, preserving input vector f06fdf
 multiply vector by diagonal matrix f06fcf
 multiply vector by reciprocal of a scalar f06fef
 negate a vector f06fgf
 sum of absolute values of vector-elements f06ekf (dasum)
 swap two vectors f06egf (dswap)
 update Euclidean norm in scaled form f06fjf
 weighted Euclidean norm of a vector f06fkf
 Level 2 (Matrix-vector and matrix) operations,
 complex matrix and vector(s),
 apply sequence of plane rotations to a rectangular matrix,
 complex cosine, real sine f06tyf
 real cosine, complex sine f06txf
 real cosine and sine f06vxf
 compute a norm or the element of largest absolute value,
 band matrix f06ubf
 general matrix f06uaf
 Hermitian band matrix f06uef
 Hermitian matrix f06ucf
 Hermitian matrix, packed form f06udf
 Hermitian matrix, RFP format f06wnf (zlanhf)
 Hermitian tridiagonal matrix f06upf
 Hessenberg matrix f06umf
 symmetric band matrix f06uhf
 symmetric matrix f06uff
 symmetric matrix, packed form f06ugf
 trapezoidal matrix f06ujf
 triangular band matrix f06ulf
 triangular matrix, packed form f06ukf
 tridiagonal matrix f06unf
 compute upper Hessenberg matrix by applying sequence of plane rotations to an upper triangular matrix f06tvf
 compute upper spiked matrix by applying sequence of plane rotations to an upper triangular matrix f06twf
 matrix initialization f06thf
 matrix-vector product,
 Hermitian band matrix f06sdf (zhbmv)
 Hermitian matrix f06scf (zhemv)
 Hermitian packed matrix f06sef (zhpmv)
 rectangular band matrix f06sbf (zgbmv)
 rectangular matrix f06saf (zgemv)
 symmetric matrix f06taf
 symmetric packed matrix f06tcf
 triangular band matrix f06sgf (ztbmv)
 triangular matrix f06sff (ztrmv)
 triangular packed matrix f06shf (ztpmv)
 permute rows or columns of a matrix,
 permutations represented by an integer array f06vjf
 permutations represented by a real array f06vkf
 QR factorization by sequence of plane rotations,
 of rank-1 update of upper triangular matrix f06tpf
 of upper triangular matrix augmented by a full row f06tqf
 QR factorization of UZ or RQ factorization of ZU, where U is upper triangular and Z is a sequence of plane rotations f06ttf
 QR or RQ factorization by sequence of plane rotations,
 of upper Hessenberg matrix f06trf
 of upper spiked matrix f06tsf
 rank-1 update,
 Hermitian matrix f06spf (zher)
 Hermitian packed matrix f06sqf (zhpr)
 rectangular matrix, conjugated vector f06snf (zgerc)
 rectangular matrix, unconjugated vector f06smf (zgeru)
 symmetric matrix f06tbf
 symmetric packed matrix f06tdf
 rank-2 update,
 Hermitian matrix f06srf (zher2)
 Hermitian packed matrix f06ssf (zhpr2)
 matrix copy, rectangular or trapezoidal f06tff
 solution of a system of equations,
 triangular band matrix f06skf (ztbsv)
 triangular matrix f06sjf (ztrsv)
 triangular packed matrix f06slf (ztpsv)
 unitary similarity transformation of a Hermitian matrix,
 as sequence of plane rotations f06tmf
 real matrix and vector(s),
 apply sequence of plane rotations to a rectangular matrix f06qxf
 compute a norm or the element of largest absolute value,
 band matrix f06rbf
 general matrix f06raf
 Hessenberg matrix f06rmf
 matrix initialization f06qhf
 symmetric band matrix f06ref
 symmetric matrix f06rcf
 symmetric matrix, packed form f06rdf
 symmetric matrix, RFP format f06waf (dlansf)
 symmetric tridiagonal matrix f06rpf
 trapezoidal matrix f06rjf
 triangular band matrix f06rlf
 triangular matrix, packed form f06rkf
 tridiagonal matrix f06rnf
 compute upper Hessenberg matrix by applying sequence of plane rotations to an upper triangular matrix f06qvf
 compute upper spiked matrix by applying sequence of plane rotations to an upper triangular matrix f06qwf
 matrix-vector product,
 rectangular band matrix f06pbf (dgbmv)
 rectangular matrix f06paf (dgemv)
 symmetric band matrix f06pdf (dsbmv)
 symmetric matrix f06pcf (dsymv)
 symmetric packed matrix f06pef (dspmv)
 triangular band matrix f06pgf (dtbmv)
 triangular matrix f06pff (dtrmv)
 triangular packed matrix f06phf (dtpmv)
 orthogonal similarity transformation of a symmetric matrix,
 as sequence of plane rotations f06qmf
 permute rows or columns of a matrix,
 permutations represented by an integer array f06qjf
 permutations represented by a real array f06qkf
 QR factorization by sequence of plane rotations,
 of rank-1 update of upper triangular matrix f06qpf
 of upper triangular matrix augmented by a full row f06qqf
 QR factorization of UZ or RQ factorization of ZU, where U is upper triangular and Z is a sequence of plane rotations f06qtf
 QR or RQ factorization by sequence of plane rotations,
 of upper Hessenberg matrix f06qrf
 of upper spiked matrix f06qsf
 rank-1 update,
 rectangular matrix f06pmf (dger)
 symmetric matrix f06ppf (dsyr)
 symmetric packed matrix f06pqf (dspr)
 rank-2 update,
 matrix copy, rectangular or trapezoidal f06qff
 symmetric matrix f06prf (dsyr2)
 symmetric packed matrix f06psf (dspr2)
 solution of a system of equations,
 triangular band matrix f06pkf (dtbsv)
 triangular matrix f06pjf (dtrsv)
 triangular packed matrix f06plf (dtpsv)
 Level 3 (Matrix-matrix) operations,
 complex matrices,
 matrix-matrix product,
 one matrix Hermitian f06zcf (zhemm)
 one matrix symmetric f06ztf (zsymm)
 one matrix triangular f06zff (ztrmm)
 two rectangular matrices f06zaf (zgemm)
 rank-2k update,
 of a Hermitian matrix f06zrf (zher2k)
 of a symmetric matrix f06zwf (zsyr2k)
 rank-k update,
 of a Hermitian matrix f06zpf (zherk)
 of a Hermitian matrix, RFP format f06wqf (zhfrk)
 of a symmetric matrix f06zuf (zsyrk)
 solution of triangular systems of equations f06zjf (ztrsm)
 solution of triangular systems of equations, RFP format f06wpf (ztfsm)
 real matrices,
 matrix-matrix product,
 one matrix symmetric f06ycf (dsymm)
 one matrix triangular f06yff (dtrmm)
 rectangular matrices f06yaf (dgemm)
 rank-2k update of a symmetric matrix f06yrf (dsyr2k)
 rank-k update,
 of a symmetric matrix f06ypf (dsyrk)
 of a symmetric matrix, RFP format f06wcf (dsfrk)
 solution of triangular systems of equations f06yjf (dtrsm)
 solution of triangular systems of equations, RFP format f06wbf (dtfsm)
 Sparse level 1 (vector) operations,
 complex vector(s),
 add scalar times sparse vector to a full vector f06gtf (zaxpyi)
 dot product of a sparse and a full vector (conjugated) f06gsf (zdotci)
 dot product of a sparse and a full vector (unconjugated) f06grf (zdotui)
 gather and set to zero a sparse vector f06gvf (zgthrz)
 gather sparse vector f06guf (zgthr)
 scatter sparse vector f06gwf (zsctr)
 real vector(s),
 add scalar times sparse vector to a full vector f06etf (daxpyi)
 apply plane rotation to a sparse and a full vector f06exf (droti)
 dot product of a sparse and a full vector f06erf (ddoti)
 gather and set to zero a sparse vector f06evf (dgthrz)
 gather sparse vector f06euf (dgthr)
 scatter sparse vector f06ewf (dsctr)
BLAS Routines
 Real Matrices single precision double precision NAG ISAMAX idamax f06jlf (idamax) SASUM dasum f06ekf (dasum) SAXPY daxpy f06ecf (daxpy) SAXPYI daxpyi f06etf (daxpyi) SCASUM dzasum f06jkf (dzasum) SCNRM2 dznrm2 f06jjf (dznrm2) SCOPY dcopy f06eff (dcopy) SDOT ddot f06eaf (ddot) SDOTI ddoti f06erf (ddoti) SGBMV dgbmv f06pbf (dgbmv) SGEMM dgemm f06yaf (dgemm) SGEMV dgemv f06paf (dgemv) SGER dger f06pmf (dger) SGTHR dgthr f06euf (dgthr) SGTHRZ dgthrz f06evf (dgthrz) SNRM2 dnrm2 f06ejf (dnrm2) SROT drot f06epf (drot) SROTG drotg f06aaf (drotg) SROTI droti f06exf (droti) SSBMV dsbmv f06pdf (dsbmv) SSCAL dscal f06edf (dscal) SSCTR dsctr f06ewf (dsctr) SSPMV dspmv f06pef (dspmv) SSPR dspr f06pqf (dspr) SSPR2 dspr2 f06psf (dspr2) SSWAP dswap f06egf (dswap) SSYMM dsymm f06ycf (dsymm) SSYMV dsymv f06pcf (dsymv) SSYR dsyr f06ppf (dsyr) SSYR2 dsyr2 f06prf (dsyr2) SSYR2K dsyr2k f06yrf (dsyr2k) SSYRK dsyrk f06ypf (dsyrk) STBMV dtbmv f06pgf (dtbmv) STBSV dtbsv f06pkf (dtbsv) STPMV dtpmv f06phf (dtpmv) STPSV dtpsv f06plf (dtpsv) STRMM dtrmm f06yff (dtrmm) STRMV dtrmv f06pff (dtrmv) STRSM dtrsm f06yjf (dtrsm) STRSV dtrsv f06pjf (dtrsv) SLANSF dlansf f06waf (dlansf) STFSM dtfsm f06wbf (dtfsm) SSFRK dsfrk f06wcf (dsfrk)
 Complex Matrices single precision double precision NAG ICAMAX izamax f06jmf (izamax) CAXPY zaxpy f06gcf (zaxpy) CAXPYI zaxpyi f06gtf (zaxpyi) CCOPY zcopy f06gff (zcopy) CDOTC zdotc f06gbf (zdotc) CDOTCI zdotci f06gsf (zdotci) CDOTU zdotu f06gaf (zdotu) CDOTUI zdotui f06grf (zdotui) CGBMV zgbmv f06sbf (zgbmv) CGEMM zgemm f06zaf (zgemm) CGEMV zgemv f06saf (zgemv) CGERC zgerc f06snf (zgerc) CGERU zgeru f06smf (zgeru) CGTHR zgthr f06guf (zgthr) CGTHRZ zgthrz f06gvf (zgthrz) CHBMV zhbmv f06sdf (zhbmv) CHEMM zhemm f06zcf (zhemm) CHEMV zhemv f06scf (zhemv) CHER zher f06spf (zher) CHER2 zher2 f06srf (zher2) CHER2K zher2k f06zrf (zher2k) CHERK zherk f06zpf (zherk) CHPMV zhpmv f06sef (zhpmv) CHPR zhpr f06sqf (zhpr) CHPR2 zhpr2 f06ssf (zhpr2) CSCAL zscal f06gdf (zscal) CSCTR zsctr f06gwf (zsctr) CSSCAL zdscal f06jdf (zdscal) CSWAP zswap f06ggf (zswap) CSYMM zsymm f06ztf (zsymm) CSYR2K zsyr2k f06zwf (zsyr2k) CSYRK zsyrk f06zuf (zsyrk) CTBMV ztbmv f06sgf (ztbmv) CTBSV ztbsv f06skf (ztbsv) CTPMV ztpmv f06shf (ztpmv) CTPSV ztpsv f06slf (ztpsv) CTRMM ztrmm f06zff (ztrmm) CTRMV ztrmv f06sff (ztrmv) CTRSM ztrsm f06zjf (ztrsm) CTRSV ztrsv f06sjf (ztrsv) CLANHF zlanhf f06wnf (zlanhf) CHFRK zhfrk f06wqf (zhfrk) CTFSM ztfsm f06wpf (ztfsm)

None.

## 6Routines Withdrawn or Scheduled for Withdrawal

None.
Dodson D S and Grimes R G (1982) Remark on Algorithm 539 ACM Trans. Math. Software 8 403–404
Dodson D S, Grimes R G and Lewis J G (1991) Sparse extensions to the Fortran basic linear algebra subprograms ACM Trans. Math. Software 17 253–263
Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A set of Level 3 basic linear algebra subprograms ACM Trans. Math. Software 16 1–28
Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An extended set of FORTRAN basic linear algebra subprograms ACM Trans. Math. Software 14 1–32
Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide SIAM, Philadelphia
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325