NAG Library Manual, Mark 27
Interfaces:  FL   CL   CPP   AD 
F16 (Blast)
Chapter Contents
Chapter Introduction   FL   CL 

NAG CL Interface
F16 (Blast)
NAG Interface to BLAS

NAG Library Manual, Mark 27
Interfaces:  FL   CL   CPP   AD 
F16 (Blast)
Chapter Contents
Chapter Introduction   FL   CL 

▸▿ Contents

© The Numerical Algorithms Group Ltd. 2019

1 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 specifications of the BLAS (Basic Linear Algebra Subprograms) or to the specifications of the BLAST (Basic Linear Algebra Subprograms Technical) Forum. This chapter includes functions conforming to both specifications. Two additional functions for such operations are available in Chapter F06.

2 Background to the Problems

Most of the functions in this chapter meet the specification of the BLAS as described in Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001), Lawson et al. (1979), Dongarra et al. (1988) and Dongarra et al. (1990).
They are called extensively by functions in other chapters of the NAG Library, especially in the linear algebra chapters. They are intended to be useful building-blocks 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):
The terminology reflects the number of operations involved, so for example a Level 2 function involves On2 operations, for vectors and matrices of order n.
In many implementations of the NAG Library, the BLAS functions in this chapter serve as interfaces 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.

2.1 The Use of BLAS Names

Many of the functions in other chapters of the Library call the functions in this chapter, and in particular a number of the BLAS are called. These functions 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 functions. If you are in any doubt about how to avoid this, please consult the NAG Technical Support Service.
The BLAS names are used in order to make use of efficient implementations of the functions 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)).

3 Recommendations on Choice and Use of Available Functions

3.1 Naming Scheme

3.1.1 NAG names

Table 1 shows the naming scheme for the functions in this chapter.
    Level-1 Level-2 Level-3
integer Chapter F16 function f16d_c – –
‘real’ BLAS function – f16p_c f16y_c
‘real’ Chapter F16 function f16f_c f16q_c –
      f16r_c  
‘real’ BLAST function f16e_c f16q_c –
      f16r_c  
‘complex’ BLAS function – f16s_c f16z_c
‘complex’ Chapter F16 function f16h_c f16t_c –
      f16u_c  
‘complex’ BLAST function f16g_c f16t_c –
      f16u_c  
‘mixed type’ BLAS function f16j_c – –
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.

3.2 The Level-1 Vector Functions

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

3.3 The Level-2 Matrix-vector and Matrix Functions

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

3.4 The Level-3 Matrix-matrix Functions

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

3.5 Vector Arguments

Vector arguments 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 incx=2, then the elements of x are in locations x1,x3,…,x2n-1 of the array x and the intermediate locations x2,x4,…,x2n-2 are not referenced.
When incx>0, the vector element xi is in the array element x1+i-1×incx. When incx≤0, the elements are stored in the reverse order so that the vector element xi is in the array element x1-n-i×incx and hence, in particular, the element xn is in x1. The declared length of the array x in the calling function must be at least 1+n-1×incx.
Negative increments are permitted only for:
Zero increments are formally permitted for Level-1 functions with more than one argument (in which case the element x1 is accessed repeatedly), but their use is strongly discouraged since the effect may be implementation-dependent. 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 Level-2 BLAS.

3.6 Matrix Arguments and Storage Schemes

In this chapter the following different storage schemes are used for 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.

3.6.1 Conventional storage

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

3.6.2 Packed storage

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

3.6.3 Rectangular Full Packed (RFP) storage

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

3.6.4 Band storage

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

3.6.5 Unit triangular matrices

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

3.6.6 Real diagonal elements of complex Hermitian matrices

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

3.7 Option Arguments

In addition to the order argument of type Nag_OrderType, most functions in this Chapter have one or more option arguments of various types; only options of the correct type may be supplied.
The following option arguments are used in this chapter:

3.7.1 Matrix norms

The option argument norm specifies different matrix norms whose definitions are given here for reference (for a general m by n matrix A):
If A is symmetric or Hermitian, A1=A∞.
The argument norm can also be used to specify the maximum absolute value maxi,jaij (if norm=Nag_MaxNorm), but this is not a norm in the strict mathematical sense.

3.8 Error Handling

Functions in this chapter use the usual NAG Library error-handling.

4 Functionality Index

Matrix operations,  
complex matrices,  
matrix copy,  
rectangular matrix   f16tfc
triangular matrix   f16tec
matrix initialization,  
rectangular matrix   f16thc
triangular matrix   f16tgc
matrix-matrix product,  
one matrix Hermitian   f16zcc
one matrix symmetric   f16ztc
one matrix triangular   f16zfc
rectangular matrices   f16zac
rank-2k update,  
of a Hermitian matrix   f16zrc
of a symmetric matrix   f16zwc
rank-k update,  
of a Hermitian matrix   f16zpc
of a Hermitian matrix, RFP format   f16zqc
of a symmetric matrix   f16zuc
solution of triangular systems of equations   f16zjc
solution of triangular systems of equations, RFP format   f16zlc
real matrices,  
matrix copy,  
rectangular matrix   f16qfc
triangular matrix   f16qec
matrix initialization,  
rectangular matrix   f16qhc
triangular matrix   f16qgc
matrix-matrix product,  
one matrix symmetric   f16ycc
one matrix triangular   f16yfc
rectangular matrices   f16yac
rank-2k update of a symmetric matrix   f16yrc
rank-k update,  
of a symmetric matrix   f16ypc
of a symmetric matrix, RFP format   f16yqc
solution of triangular systems of equations   f16yjc
solution of triangular systems of equations, RFP format   f16ylc
Matrix-vector operations,  
complex matrix and vector(s),  
compute a norm or the element of largest absolute value,  
band matrix   f16ubc
general matrix   f16uac
Hermitian band matrix   f16uec
Hermitian matrix   f16ucc
Hermitian matrix, RFP format   f16ukc
Hermitian packed matrix   f16udc
symmetric matrix   f16ufc
symmetric packed matrix   f16ugc
matrix-vector product,  
Hermitian band matrix   f16sdc
Hermitian matrix   f16scc
Hermitian packed matrix   f16sec
rectangular band matrix   f16sbc
rectangular matrix   f16sac
symmetric matrix   f16tac
symmetric packed matrix   f16tcc
triangular band matrix   f16sgc
triangular matrix   f16sfc
triangular packed matrix   f16shc
rank-1 update,  
Hermitian matrix   f16spc
Hermitian packed matrix   f16sqc
rectangular matrix, unconjugated vector   f16smc
rank-2 update,  
Hermitian matrix   f16src
Hermitian packed matrix   f16ssc
solution of a system of equations,  
triangular band matrix   f16skc
triangular matrix   f16sjc
triangular packed matrix   f16slc
real matrix and vector(s),  
compute a norm or the element of largest absolute value,  
band matrix   f16rbc
general matrix   f16rac
symmetric band matrix   f16rec
symmetric matrix   f16rcc
symmetric matrix, RFP format   f16rkc
symmetric packed matrix   f16rdc
matrix-vector product,  
rectangular band matrix   f16pbc
rectangular matrix   f16pac
symmetric band matrix   f16pdc
symmetric matrix   f16pcc
symmetric packed matrix   f16pec
triangular band matrix   f16pgc
triangular matrix   f16pfc
triangular packed matrix   f16phc
rank-1 update,  
rectangular matrix   f16pmc
symmetric matrix   f16ppc
symmetric packed matrix   f16pqc
rank-2 update,  
symmetric matrix   f16prc
symmetric packed matrix   f16psc
solution of a system of equations,  
triangular band matrix   f16pkc
triangular matrix   f16pjc
triangular packed matrix   f16plc
Scalar and vector operations,  
complex vector(s),  
broadcast a scalar into a vector   f16hbc
maximum absolute value and location   f16jsc
minimum absolute value and location   f16jtc
sum of elements   f16glc
sum of two scaled vectors   f16gcc
sum of two scaled vectors preserving input   f16ghc
integer vector(s),  
broadcast a scalar into a vector   f16dbc
maximum absolute value and location   f16dqc
maximum value and location   f16dnc
minimum absolute value and location   f16drc
minimum value and location   f16dpc
sum of elements   f16dlc
real vector(s),  
broadcast a scalar into a vector   f16fbc
dot product of two vectors with optional scaling and accumulation   f16eac
maximum absolute value and location   f16jqc
maximum value and location   f16jnc
minimum absolute value and location   f16jrc
minimum value and location   f16jpc
sum of elements   f16elc
sum of two scaled vectors   f16ecc
sum of two scaled vectors preserving input   f16ehc

5 Auxiliary Functions Associated with Library Function Arguments

None.

6 Withdrawn or Deprecated Functions

None.

7 References

Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001) Basic Linear Algebra Subprograms Technical (BLAST) Forum Standard University of Tennessee, Knoxville, Tennessee https://www.netlib.org/blas/blast-forum/blas-report.pdf
Dodson D S and Grimes R G (1982) Remark on Algorithm 539 ACM Trans. Math. Software 8 403–404
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
NAG Library Manual, Mark 27
Interfaces:  FL   CL   CPP   AD 
F16 (Blast)
Chapter Contents
Chapter Introduction   FL   CL 
© The Numerical Algorithms Group Ltd. 2019