# NAG CL InterfaceF16 (Blast)NAG Interface to BLAS

## 1Scope 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.

## 2Background 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):
• Level 1: vector operations;
• Level 2: matrix-vector operations and matrix operations which includes single matrix operations;
• Level 3: matrix-matrix 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$.
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.1The 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)).

## 3Recommendations on Choice and Use of Available Functions

### 3.1Naming Scheme

#### 3.1.1NAG 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.2The Level-1 Vector Functions

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

### 3.3The 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.4The Level-3 Matrix-matrix Functions

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

### 3.5Vector 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 ${\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 function must be at least $\left(1+\left({\mathbf{n}}-1\right)×\left|{\mathbf{incx}}\right|\right)$.
Negative increments are permitted only for:
• Level-1 functions which have more than one vector argument;
• Level-2 BLAS functions (but not for other Level-2 functions)
Zero increments are formally permitted for Level-1 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 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.6Matrix 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;
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.1Conventional storage

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

#### 3.6.2Packed storage

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

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

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

#### 3.6.4Band storage

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

#### 3.6.5Unit triangular matrices

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

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

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

### 3.7Option 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:
• If ${\mathbf{trans}}=\mathrm{NoTranspose}$, operate with the matrix (Not transposed);
• if ${\mathbf{trans}}=\mathrm{Transpose}$, operate with the Transpose of the matrix;
• if ${\mathbf{trans}}=\mathrm{ConjugateTranspose}$, operate with the Conjugate transpose of the matrix.
• If ${\mathbf{uplo}}=\mathrm{UpperTriangle}$, upper triangle or trapezoid of matrix;
• if ${\mathbf{uplo}}=\mathrm{LowerTriangle}$, lower triangle or trapezoid of matrix.
• If ${\mathbf{diag}}=\mathrm{UnitTriangular}$, unit triangular;
• if ${\mathbf{diag}}=\mathrm{NotUnitTriangular}$, nonunit triangular.
• If ${\mathbf{side}}=\mathrm{LeftSide}$, operate from the left-hand side;
• if ${\mathbf{side}}=\mathrm{RightSide}$, operate from the right-hand side.
• If ${\mathbf{norm}}=\mathrm{Nag_OneNorm}$, $1$-norm of a matrix;
• if ${\mathbf{norm}}=\mathrm{Nag_InfNorm}$, $\infty$-norm of a matrix;
• if ${\mathbf{norm}}=\mathrm{Nag_FrobeniusNorm}$, Frobenius or Euclidean norm of a matrix;
• if ${\mathbf{norm}}=\mathrm{Nag_MaxNorm}$, maximum absolute value of the elements of a matrix (not strictly a norm).

#### 3.7.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}}=\mathrm{Nag_OneNorm}$):
 $A1=maxj∑i=1maij;$
• Infinity-norm (${\mathbf{norm}}=\mathrm{Nag_InfNorm}$):
 $A∞=maxi∑j=1naij;$
• Frobenius or Euclidean norm (${\mathbf{norm}}=\mathrm{Nag_FrobeniusNorm}$):
 $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}}=\mathrm{Nag_MaxNorm}$), but this is not a norm in the strict mathematical sense.

### 3.8Error Handling

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

## 4Functionality 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

None.

## 6 Withdrawn or Deprecated Functions

None.
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