PDF version (NAG web site
, 64bit version, 64bit version)
NAG Toolbox Chapter Introduction
F16 — further linear algebra support routines
Scope of the Chapter
This chapter is concerned with basic linear algebra functions which perform elementary algebraic operations involving scalars, vectors and matrices. Most functions for such operations conform either to the speciﬁcations of the BLAS (Basic Linear Algebra Subprograms) or to the specifications of the BLAST (Basic Linear Algebra Subprograms Technical) Forum. This chapter includes functions from the BLAST specifications. Most (BLAS) functions for such operations are available in .
Background to the Problems
Most of the functions in this chapter meet the specification of
Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001).
They are called extensively by functions in other chapters of the NAG Toolbox, especially in the linear algebra chapters. They are intended to be useful buildingblocks for users of the Library who are developing their own applications. The functions fall into four main groups (following the definitions introduced by the BLAS):
 Level 0: scalar operations;
 Level 1: vector operations;
 Level 2: matrixvector operations and matrix operations which includes single matrix operations;
 Level 3: matrixmatrix operations.
The terminology reflects the number of operations involved, so for example a Level 2 function involves $\mathit{O}\left({n}^{2}\right)$ operations, for vectors and matrices of order $n$.
Because of the overlap of functionality with , only a subset of BLAST functions are implemented in this chapter. A full descripion of the
Recommendations on Choice and Use of Available Functions
Naming Scheme
NAG names
Table 1 shows the naming scheme for the functions in this chapter which follows the naming scheme used in .

Level0 
Level1 
Level2 
Level3 
integer 
– 
F16D_F 
– 
– 
‘real’ 
– 
F16E_F 
– 
– 
‘real’ 
– 
– 
F16R_F 
– 
‘complex’ 
– 
F16G_F 
– 
– 
‘complex’ 
– 
– 
F16U_F 
– 
‘mixed type’ 
– 
F16J_F 
– 
– 
Table 1
The heading ‘mixed type’ is for functions where a mixture of data types is involved, such as a function that returns the real norm of a complex vector. In future marks of the Library, functions may be included in categories that are currently empty and further categories may be introduced.
BLAS names
Those functions 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 Toolbox, references to BLAS names may be linked to an efficient machinespecific implementation of the BLAS, usually provided by the vendor of the machine;
Chapter F16 BLAS functions are unlikely to be provide by a vendor. Such implementations are stringently tested before being used with the NAG Toolbox, 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 function names (beginning F06 or F16) are always linked to the code provided in the NAG Toolbox and may be significantly slower (in the case of functions) than the equivalent BLAS function.
The names of the Level2 and Level3 BLAS follow a simple scheme (which is similar to that used for LAPACK functions 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 
matrixvector product 
MM 
matrixmatrix product 
R 
rank1 update 
R2 
rank2 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 righthand sides 

Thus the function
nag_blast_daxpby (f16ec) performs a sum of two real, scaled vectors in double precision;
the corresponding function for complex scalars and vectors is
nag_blast_zaxpby (f16gc).
The names of the Level1 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 precisiondependent.
The Level0 Scalar Functions
The Level0 functions perform operations on scalars or on vectors or matrices of order $2$.
The Level1 Vector Functions
The Level1 functions perform operations either on a single vector or on a pair of vectors.
The Level2 Matrixvector and Matrix Functions
The Level2 functions perform operations involving either a matrix on its own, or a matrix and one or more vectors.
The Level3 Matrixmatrix Functions
The Level3 functions perform operations involving matrixmatrix products.
Vector Arguments
Vector arguments (except in the Level1 Sparse BLAS) are represented by a onedimensional 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(2n1\right)$ of the array
x
and the intermediate locations $x\left(2\right),x\left(4\right),\dots ,x\left(2n2\right)$ are not referenced.
When $\mathbf{incx}>0$, the vector element ${x}_{i}$ is in the array element $\mathbf{x}\left(1+\left(i1\right)\times \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(ni\right)\times \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 function must be at least $\left(1+\left(\mathbf{n}1\right)\times \left\mathbf{incx}\right\right)$.
Negative increments are permitted only for:
 Level1 functions which have more than one vector argument;
 Level2 BLAS functions (but not for other Level2 functions)
Zero increments are formally permitted for Level1 functions 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 implementationdependent. There is usually an alternative function in this chapter, with a simplified argument list, to achieve the required purpose. Zero increments are not permitted in the Level2 BLAS.
Matrix Arguments and Storage Schemes
In this chapter the following different storage schemes are used for matrices:
 – conventional storage in a twodimensional 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 functions in
Chapters F01,
F02,
F03 and
F04.)
Chapter F01 provides some utility functions for conversion between storage schemes.
In the examples, $*$ indicates an array element which need not be set and is not referenced by the functions. 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.
Conventional storage
Please see
Conventional storage in the F07 Chapter Introduction for full details.
Packed storage
Please see
Packed storage in the F07 Chapter Introduction for full details.
Rectangular Full Packed (RFP) storage
Please see
Rectangular Full Packed (RFP) Storage in the F07 Chapter Introduction for full details.
Band storage
Please see
Band storage in the F07 Chapter Introduction for full details.
Unit triangular matrices
Please see
Unit triangular matrices in the F07 Chapter Introduction for full details.
Real diagonal elements of complex Hermitian matrices
Please see
Real diagonal elements of complex matrices in the F07 Chapter Introduction for full details.
Option Arguments
Many of the functions in this chapter have one or more option arguments, of type CHARACTER. The descriptions in the function documents refer only to uppercase values (for example
$\mathbf{uplo}=\text{'U'}$ or
$\mathbf{uplo}=\text{'L'}$); however, in every case, the corresponding lowercase characters may be supplied (with the same meaning). Any other value is illegal.
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 lefthand side;
 if $\mathbf{side}=\text{'R'}$, operate from the righthand side.
 If $\mathbf{norm\_p}=\text{'1'}$ or $\text{'O'}$, $1$norm of a matrix;
 if $\mathbf{norm\_p}=\text{'I'}$, $\infty $norm of a matrix;
 if $\mathbf{norm\_p}=\text{'F'}$ or $\text{'E'}$, Frobenius or Euclidean norm of a matrix;
 if $\mathbf{norm\_p}=\text{'M'}$, maximum absolute value of the elements of a matrix (not strictly a norm).
Matrix norms
The option argument
norm_p
specifies different matrix norms whose definitions are given here for reference (for a general
$m$ by
$n$ matrix
$A$):
 Onenorm ($\mathbf{norm\_p}=\text{'O'}$ or $\text{'1'}$):
 Infinitynorm ($\mathbf{norm\_p}=\text{'I'}$):
 Frobenius or Euclidean norm ($\mathbf{norm\_p}=\text{'F'}$ or $\text{'E'}$):
If $A$ is symmetric or Hermitian, ${\Vert A\Vert}_{1}={\Vert A\Vert}_{\infty}$.
The argument
norm_p
can also be used to specify the maximum absolute value ${\mathrm{max}}_{i,j}\left{a}_{ij}\right$ (if
$\mathbf{norm\_p}=\text{'M'}$),
but this is not a norm in the strict mathematical sense.
Error Handling
Functions in this chapter do not use the usual NAG Toolbox errorhandling mechanism, involving the argument IFAIL.
If one of the Level2 or Level3 BLAS functions is called with an invalid value of one of its arguments, then an error message is output on the error message unit (see
nag_file_set_unit_error (x04aa)), giving the name of the function 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 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 functions 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.
Functionality Index
Matrixvector operations,   
complex matrix and vector(s),   
compute a norm or the element of largest absolute value,   
real matrix and vector(s),   
compute a norm or the element of largest absolute value,   
Scalar and vector operations,   
References
Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001)
Basic Linear Algebra Subprograms Technical (BLAST) Forum Standard University of Tennessee, Knoxville, Tennessee
http://www.netlib.org/blas/blastforum/blasreport.pdf
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
PDF version (NAG web site
, 64bit version, 64bit version)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015