f16 Chapter Contents

f16 Chapter Introduction (PDF version)

NAG Library Manual

NAG Library Chapter Introduction

f16 – NAG Interface to BLAS

▸▿ Contents

1 Scope of the Chapter

▸▿ 2 Background to the Problems

2.1 The Use of BLAS Names

▸▿ 3 Recommendations on Choice and Use of Available Functions

▸▿ 3.1 Naming Scheme

3.1.1 NAG names

3.2 The Level-1 Vector Functions

3.3 The Level-2 Matrix-vector and Matrix Functions

3.4 The Level-3 Matrix-matrix Functions

3.5 Vector Arguments

▸▿ 3.6 Matrix Arguments and Storage Schemes

3.6.1 Conventional storage

3.6.2 Packed storage

3.6.3 Rectangular Full Packed (RFP) storage

3.6.4 Band storage

3.6.5 Unit triangular matrices

3.6.6 Real diagonal elements of complex Hermitian matrices

▸▿ 3.7 Option Arguments

3.7.1 Matrix norms

3.8 Error Handling

4 Functionality Index

5 Auxiliary Functions Associated with Library Function Arguments

6 Functions Withdrawn or Scheduled for Withdrawal

7 References

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 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 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 speciﬁcation 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 C 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

O (n^{2})

operations, for vectors and matrices of order

n

.

In many implementations of the NAG C 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 C 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

x (1), x (3), \dots, x (2 n - 1)

of the array x and the intermediate locations

x (2), x (4), \dots, x (2 n - 2)

are not referenced.

When

incx > 0

, the vector element

x_{i}

is in the array element

x (1 + (i - 1) \times incx)

. When

incx \leq 0

, the elements are stored in the reverse order so that the vector element

x_{i}

is in the array element

x (1 - (n - i) \times incx)

and hence, in particular, the element

x_{n}

is in

x (1)

. The declared length of the array x in the calling function must be at least

(1 + (n - 1) \times |incx|)

.

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

x (1)

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:

– 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.1 Conventional storage

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

3.6.2 Packed storage

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

3.6.3 Rectangular Full Packed (RFP) storage

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

3.6.4 Band storage

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

3.6.5 Unit triangular matrices

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

3.6.6 Real diagonal elements of complex Hermitian matrices

Please see Section 3.3.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:

If $trans = NoTranspose$ , operate with the matrix (Not transposed);
if $trans = Transpose$ , operate with the Transpose of the matrix;
if $trans = ConjugateTranspose$ , operate with the Conjugate transpose of the matrix.

If $uplo = Nag_Upper$ , upper triangle or trapezoid of matrix;
if $uplo = Nag_Lower$ , lower triangle or trapezoid of matrix.

If $diag = Nag_UnitDiag$ , unit triangular;
if $diag = NotUnitTriangular$ , nonunit triangular.

If $side = LeftSide$ , operate from the left-hand side;
if $side = RightSide$ , operate from the right-hand side.

If $norm = Nag_OneNorm$ , $1$ -norm of a matrix;
if $norm = Nag_InfNorm$ , $\infty$ -norm of a matrix;
if $norm = Nag_FrobeniusNorm$ , Frobenius or Euclidean norm of a matrix;
if $norm = Nag_MaxNorm$ , maximum absolute value of the elements of a matrix (not strictly a norm).

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

):

One-norm ( $norm = Nag_OneNorm$ ):
${‖A‖}_{1} = \max_{j} \sum_{i = 1}^{m} |a_{i j}|;$
Infinity-norm ( $norm = Nag_InfNorm$ ):
${‖A‖}_{\infty} = \max_{i} \sum_{j = 1}^{n} |a_{i j}|;$
Frobenius or Euclidean norm ( $norm = Nag_FrobeniusNorm$ ):
${‖A‖}_{F} = {(\sum_{i = 1}^{m} \sum_{j = 1}^{n} {|a_{i j}|}^{2})}^{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

\max_{i, j} |a_{i j}|

(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 C Library error-handling.

4 Functionality Index

Matrix operations,

complex matrices,

matrix copy,

rectangular matrix

nag_zge_copy (f16tfc)

triangular matrix

nag_ztr_copy (f16tec)

matrix initialization,

rectangular matrix

nag_zge_load (f16thc)

triangular matrix

nag_ztr_load (f16tgc)

matrix-matrix product,

one matrix Hermitian

nag_zhemm (f16zcc)

one matrix symmetric

nag_zsymm (f16ztc)

one matrix triangular

nag_ztrmm (f16zfc)

rectangular matrices

nag_zgemm (f16zac)

rank-2k update,

of a Hermitian matrix

nag_zher2k (f16zrc)

of a symmetric matrix

nag_zsyr2k (f16zwc)

rank-k update,

of a Hermitian matrix

nag_zherk (f16zpc)

of a Hermitian matrix, RFP format

nag_zhfrk (f16zqc)

of a symmetric matrix

nag_zsyrk (f16zuc)

solution of triangular systems of equations

nag_ztrsm (f16zjc)

solution of triangular systems of equations, RFP format

nag_ztfsm (f16zlc)

real matrices,

matrix copy,

rectangular matrix

nag_dge_copy (f16qfc)

triangular matrix

nag_dtr_copy (f16qec)

matrix initialization,

rectangular matrix

nag_dge_load (f16qhc)

triangular matrix

nag_dtr_load (f16qgc)

matrix-matrix product,

one matrix symmetric

nag_dsymm (f16ycc)

one matrix triangular

nag_dtrmm (f16yfc)

rectangular matrices

nag_dgemm (f16yac)

rank-2k update of a symmetric matrix

nag_dsyr2k (f16yrc)

rank-k update,

of a symmetric matrix

nag_dsyrk (f16ypc)

of a symmetric matrix, RFP format

nag_dsfrk (f16yqc)

solution of triangular systems of equations

nag_dtrsm (f16yjc)

solution of triangular systems of equations, RFP format

nag_dtfsm (f16ylc)

Matrix-vector operations,

complex matrix and vector(s),

compute a norm or the element of largest absolute value,

band matrix

nag_zgb_norm (f16ubc)

general matrix

nag_zge_norm (f16uac)

Hermitian band matrix

nag_zhb_norm (f16uec)

Hermitian matrix

nag_zhe_norm (f16ucc)

Hermitian matrix, RFP format

nag_zhf_norm (f16ukc)

Hermitian packed matrix

nag_zhp_norm (f16udc)

symmetric matrix

nag_zsy_norm (f16ufc)

symmetric packed matrix

nag_zsp_norm (f16ugc)

matrix-vector product,

Hermitian band matrix

nag_zhbmv (f16sdc)

Hermitian matrix

nag_zhemv (f16scc)

Hermitian packed matrix

nag_zhpmv (f16sec)

rectangular band matrix

nag_zgbmv (f16sbc)

rectangular matrix

nag_zgemv (f16sac)

symmetric matrix

nag_zsymv (f16tac)

symmetric packed matrix

nag_zspmv (f16tcc)

triangular band matrix

nag_ztbmv (f16sgc)

triangular matrix

nag_ztrmv (f16sfc)

triangular packed matrix

nag_ztpmv (f16shc)

rank-1 update,

Hermitian matrix

nag_zher (f16spc)

Hermitian packed matrix

nag_zhpr (f16sqc)

rectangular matrix, unconjugated vector

nag_zger (f16smc)

rank-2 update,

Hermitian matrix

nag_zher2 (f16src)

Hermitian packed matrix

nag_zhpr2 (f16ssc)

solution of a system of equations,

triangular band matrix

nag_ztbsv (f16skc)

triangular matrix

nag_ztrsv (f16sjc)

triangular packed matrix

nag_ztpsv (f16slc)

real matrix and vector(s),

compute a norm or the element of largest absolute value,

band matrix

nag_dgb_norm (f16rbc)

general matrix

nag_dge_norm (f16rac)

symmetric band matrix

nag_dsb_norm (f16rec)

symmetric matrix

nag_dsy_norm (f16rcc)

symmetric matrix, RFP format

nag_dsf_norm (f16rkc)

symmetric packed matrix

nag_dsp_norm (f16rdc)

matrix-vector product,

rectangular band matrix

nag_dgbmv (f16pbc)

rectangular matrix

nag_dgemv (f16pac)

symmetric band matrix

nag_dsbmv (f16pdc)

symmetric matrix

nag_dsymv (f16pcc)

symmetric packed matrix

nag_dspmv (f16pec)

triangular band matrix

nag_dtbmv (f16pgc)

triangular matrix

nag_dtrmv (f16pfc)

triangular packed matrix

nag_dtpmv (f16phc)

rank-1 update,

rectangular matrix

nag_dger (f16pmc)

symmetric matrix

nag_dsyr (f16ppc)

symmetric packed matrix

nag_dspr (f16pqc)

rank-2 update,

symmetric matrix

nag_dsyr2 (f16prc)

symmetric packed matrix

nag_dspr2 (f16psc)

solution of a system of equations,

triangular band matrix

nag_dtbsv (f16pkc)

triangular matrix

nag_dtrsv (f16pjc)

triangular packed matrix

nag_dtpsv (f16plc)

Scalar and vector operations,

complex vector(s),

broadcast a scalar into a vector

nag_zload (f16hbc)

maximum absolute value and location

nag_zamax_val (f16jsc)

minimum absolute value and location

nag_zamin_val (f16jtc)

sum of elements

nag_zsum (f16glc)

sum of two scaled vectors

nag_zaxpby (f16gcc)

sum of two scaled vectors preserving input

nag_zwaxpby (f16ghc)

integer vector(s),

broadcast a scalar into a vector

nag_iload (f16dbc)

maximum absolute value and location

nag_iamax_val (f16dqc)

maximum value and location

nag_imax_val (f16dnc)

minimum absolute value and location

nag_iamin_val (f16drc)

minimum value and location

nag_imin_val (f16dpc)

sum of elements

nag_isum (f16dlc)

real vector(s),

broadcast a scalar into a vector

nag_dload (f16fbc)

dot product of two vectors with optional scaling and accumulation

nag_ddot (f16eac)

maximum absolute value and location

nag_damax_val (f16jqc)

maximum value and location

nag_dmax_val (f16jnc)

minimum absolute value and location

nag_damin_val (f16jrc)

minimum value and location

nag_dmin_val (f16jpc)

sum of elements

nag_dsum (f16elc)

sum of two scaled vectors

nag_daxpby (f16ecc)

sum of two scaled vectors preserving input

nag_dwaxpby (f16ehc)

5 Auxiliary Functions Associated with Library Function Arguments

None.

6 Functions Withdrawn or Scheduled for Withdrawal

None.

7 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/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

f16 Chapter Contents

f16 Chapter Introduction (PDF version)

NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015