NAME
Math::BLAS  basic linear algebra subroutines
SYNOPSIS
use Math::BLAS;
DESCRIPTION
General Conventions
Notation
The following notation is used in this document.
A, B, and C are matrices
D is a diagonal matrix
P is a permutation matrix
op(A) denotes A or A'
A' is the transpose matrix of A
u, v, w, x, y, and z are vectors
r, s, and t are scalars
α and β are constants
← denotes assignment
Subroutine Arguments
 Problem Size

The problem size is specified by the integral numbers m and n. For vector operations, argument n is the number of vector elements. For matrix operations, m is the number of matrix rows and n is the number of matrix columns. For square matrix operations, n is the number of matrix rows and matrix columns.
Size arguments which are not integral numbers are truncated to the next integral number using Perl's builtin procedure
int
.  Scalar Operands

A scalar operand is a Perl scalar value. Scalar operands are specified as properties with appropriate default values.
 Vector Operands

A vector operand x is specified by three arguments. Required argument x is a Perl array reference. The corresponding array index property x_ind specifies the Perl array index of the first vector element. The default value for the array index property is zero. Vectors are permitted to have spacing between elements. This spacing is specified by the Perl array index increment property x_incr. The default value for the array index increment property is one.
 Matrix Operands

A matrix operand A is specified by three arguments. Required argument a is a Perl array reference. The corresponding array index property a_ind specifies the Perl array index of the first matrix element. The default value for the array index property is zero. Matrices are permitted to have more rows and/or columns than specified by the problem size. The actual number of columns is specified by the Perl array index increment property a_incr. The default value for the array index increment property is derived from the problem size.
Reduction Operations
blas_dot
(n, x, y, ...)
Dot product.
r ← α x'·y + β r
The
dot
function adds the scaled dot product of two vectors x and y into a scaled scalar r.First argument n is the number of vector elements.
Second argument x is the lefthand side vector operand.
Third argument y is the righthand side vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind, x_incr, y_ind, and y_incr. The following table lists the nonstandard property names together with their meaning.
 alpha

The scale factor for the dot product. Default value is one.
 beta

The scale factor for the scalar operand. Default value is zero.
 r

The scalar operand. Value is either a scalar value or an array reference. Default value is zero.
 r_ind

The Perl array index of the array element for the array r. This property is only evaluated if r is an array reference. Default value is zero.
Arguments x and y are only evaluated if alpha is not equal to zero and if n is greater than zero. Argument r is only evaluated if beta is not equal to zero.
Return value is the result of the form. If n is less than zero, the function returns immediately with a return value of
undef
. blas_norm
(n, x, ...)
Vector norms.
The
norm
function computes either the onenorm, twonorm (that is Euclidean norm), or infinitynorm of a vector x.First argument n is the number of vector elements.
Second argument x is the vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind and x_incr. The following table lists the nonstandard property names together with their meaning.
 norm

The type of vector norm. Value is either
BLAS_ONE_NORM
,BLAS_TWO_NORM
(orBLAS_FROBENIUS_NORM
), orBLAS_INF_NORM
. Default is to compute the onenorm.
Argument x is only evaluated if n is greater than zero.
Return value is the vector norm. If n is less than or equal to zero, the function returns immediately with a return value of zero.
blas_sum
(n, x, ...)
Sum of vector elements.
r ← ∑ x
The
sum
function computes the sum of the elements of a vector x.First argument n is the number of vector elements.
Second argument x is the vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind and x_incr.
Argument x is only evaluated if n is greater than zero.
Return value is the result of the form. If n is less than or equal to zero, the function returns immediately with a return value of zero.
blas_min_val
(n, x, ...)blas_amin_val
(n, x, ...)blas_max_val
(n, x, ...)blas_amax_val
(n, x, ...)
Minimum/maximum value and location.
 minimum value

k, r ← min x
 minimum absolute value

k, r ← min x
 maximum value

k, r ← max x
 maximum absolute value

k, r ← max x
The
min_val
function finds the smallest element of a vector. Theamin_val
function finds the smallest element of a vector with respect to the absolute value. Themax_val
function finds the largest element of a vector. Theamax_val
function finds the largest element of a vector with respect to the absolute value.First argument n is the number of vector elements.
Second argument x is the vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind and x_incr.
Argument x is only evaluated if n is greater than zero.
Return value is a list with two elements. First element is the index offset of the vector element. Second element is the value of the corresponding vector element. If argument n is less than or equal to zero, the function returns immediately with an index offset of
undef
and an element value of zero.If you are only interested in one of the return values, either assign the unwanted return value to
undef
or directly subscribe the returned list. Say, for example(undef, $val) = blas_min_val ($n, $x);
or
$val = (blas_min_val ($n, $x))[1];
blas_sumsq
(n, x, ...)
Sum of squares.
s·t² ← s·t² + ∑ x²
The
sumsq
function computes the scaled sum of squares s and the scale factor t.First argument n is the number of vector elements.
Second argument x is the vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind and x_incr. The following table lists the nonstandard property names together with their meaning.
 sumsq

The start value for the scaled sum of squares. Default value is zero.
 scale

The start value for the scale factor. Default value is one.
Arguments x, sumsq, and scale are only evaluated if n is greater than zero.
Return value is a list with two elements. First element is the scaled sum of squares. Second element is the scale factor. If n is less than or equal to zero, the function returns immediately with the unchanged values of sumsq and scale.
Vector Operations
blas_rscale
(n, x, ...)
Reciprocal scale.
x ← x/α
The
rscale
function divides the elements of the vector x by the real scalar α. The scalar α is expected to be nonzero.First argument n is the number of vector elements.
Second argument x is the vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind and x_incr. The following table lists the nonstandard property names together with their meaning.
 alpha

The reciprocal scale factor for the vector operand. Default value is one.
Argument x is only evaluated if alpha is not equal to one.
The procedure returns immediately if n is less than or equal to zero.
blas_axpby
(n, x, y, ...)
Scaled vector accumulation.
y ← α x + β y
The
axpby
function adds the scaled vector x into the scaled vector y.First argument n is the number of vector elements.
Second argument x is the first vector operand.
Third argument y is the second vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind, x_incr, y_ind, and y_incr. The following table lists the nonstandard property names together with their meaning.
 alpha

The scale factor for the first vector operand. Default value is one.
 beta

The scale factor for the second vector operand. Default value is one.
Argument x is only evaluated if alpha is not equal to zero.
The procedure returns immediately if n is less than or equal to zero.
blas_waxpby
(n, x, y, w, ...)
Scaled vector addition.
w ← α x + β y
The
waxpby
function adds two scaled vectors x and y and stores the result in the vector w.First argument n is the number of vector elements.
Second argument x is the first vector operand.
Third argument y is the second vector operand.
Fourth argument w is the result vector.
The rest of the arguments form a property list. Applicable standard properties are x_ind, x_incr, y_ind, y_incr, w_ind, and w_incr. The following table lists the nonstandard property names together with their meaning.
 alpha

The scale factor for the first vector operand. Default value is one.
 beta

The scale factor for the second vector operand. Default value is one.
Argument x is only evaluated if alpha is not equal to zero. Argument y is only evaluated if beta is not equal to zero.
The procedure returns immediately if n is less than or equal to zero.
Data Movement with Vectors
blas_copy
(n, x, y, ...)
Copy vector elements.
y ← x
The
copy
function assigns the elements of the vector x to the elements of the vector y.First argument n is the number of vector elements.
Second argument x is the source vector.
Third argument y is the destination vector.
The rest of the arguments form a property list. Applicable standard properties are x_ind, x_incr, y_ind, and y_incr.
The procedure returns immediately if n is less than or equal to zero.
blas_swap
(n, x, y, ...)
Interchange vector elements.
y ↔ x
The
swap
function interchanges the elements of the vector x with the elements of the vector y.First argument n is the number of vector elements.
Second argument x is the first vector operand.
Third argument y is the second vector operand.
The rest of the arguments form a property list. Applicable standard properties are x_ind, x_incr, y_ind, and y_incr.
The procedure returns immediately if n is less than or equal to zero.
Matrix/Vector Operations
blas_gemv
(m, n, a, x, y, ...)
General matrix/vector multiplication.
y ← α op(A)·x + β y
The
gemv
function multiplies the matrix A with the vector x and adds the scaled product into the scaled vector y. If op(A) = A, A is a (m, n) matrix. If op(A) = A', A is a (n, m) matrix. Operand x is a vector with n elements and y is a vector with m elements.First argument m is the number of matrix rows.
Second argument n is the number of matrix columns.
Third argument a is the matrix operand.
Fourth argument x is the vector operand.
Fifth argument y is the result vector.
The rest of the arguments form a property list. Applicable standard properties are a_ind, a_incr, x_ind, x_incr, y_ind, and y_incr. The following table lists the nonstandard property names together with their meaning.
 a_op

The transpose flag for the matrix A. Value is either
BLAS_NO_TRANS
orBLAS_TRANS
. Default is to not transpose the matrix A.  alpha

The scale factor for the matrix/vector product. Default value is one.
 beta

The scale factor for the result vector. Default value is zero.
The procedure returns immediately if m or n is less than or equal to zero.
Matrix/Matrix Operations
blas_gemm
(m, n, k, a, b, c, ...)
General matrix/matrix multiplication.
C ← α op(A)·op(B) + β C
The
gemm
function multiplies the matrix A with the matrix B and adds the scaled product into the scaled (m, n) matrix C. If op(A) = A, A is a (m, k) matrix. If op(A) = A', A is a (k, m) matrix. If op(B) = B, B is a (k, n) matrix. If op(B) = B', B is a (n, k) matrix.First argument m is the number of matrix rows.
Second argument n is the number of matrix columns.
Third argument k is the number of vector elements for the matrix/matrix product.
Fourth argument a is the lefthand side matrix operand.
Fifth argument b is the righthand side matrix operand.
Sixth argument c is the result matrix.
The rest of the arguments form a property list. Applicable standard properties are a_ind, a_incr, b_ind, b_incr, c_ind, and c_incr. The following table lists the nonstandard property names together with their meaning.
 a_op

The transpose flag for the matrix A. Value is either
BLAS_NO_TRANS
orBLAS_TRANS
. Default is to not transpose the matrix A.  b_op

The transpose flag for the matrix B. Value is either
BLAS_NO_TRANS
orBLAS_TRANS
. Default is to not transpose the matrix B.  alpha

The scale factor for the matrix/matrix product. Default value is one.
 beta

The scale factor for the result matrix. Default value is zero.
The procedure returns immediately if m or n is less than or equal to zero.
SEE ALSO
Math::BLAS::Enum, Math::BLAS::Legacy
External Links
http://www.netlib.org/blas/blastforum/
AUTHOR
Ralph Schleicher <rs@ralphschleicher.de>