/ 
Math-BLAS-1.02
River stage one • 1 direct dependent • 1 total dependent
/ Math::BLAS

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 built-in 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 left-hand side vector operand.

  • Third argument y is the right-hand 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 non-standard 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.

one-norm

r ← ∑ |x|

two-norm

r² ← ∑ x²

infinity-norm

r ← max |x|

The norm function computes either the one-norm, two-norm (that is Euclidean norm), or infinity-norm 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 non-standard property names together with their meaning.

    norm

    The type of vector norm. Value is either BLAS_ONE_NORM, BLAS_TWO_NORM (or BLAS_FROBENIUS_NORM), or BLAS_INF_NORM. Default is to compute the one-norm.

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. The amin_val function finds the smallest element of a vector with respect to the absolute value. The max_val function finds the largest element of a vector. The amax_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 non-standard 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_scale (n, x, ...)

Scale.

  • x ← α x

The scale function multiplies the elements of the vector x by the real scalar α. This is a convenience function since you can perform the same operation with the axpby function, too.

  • 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 non-standard property names together with their meaning.

    alpha

    The 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_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 non-zero.

  • 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 non-standard 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 non-standard 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 non-standard 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 non-standard property names together with their meaning.

    a_op

    The transpose flag for the matrix A. Value is either BLAS_NO_TRANS or BLAS_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 left-hand side matrix operand.

  • Fifth argument b is the right-hand 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 non-standard property names together with their meaning.

    a_op

    The transpose flag for the matrix A. Value is either BLAS_NO_TRANS or BLAS_TRANS. Default is to not transpose the matrix A.

    b_op

    The transpose flag for the matrix B. Value is either BLAS_NO_TRANS or BLAS_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

http://www.netlib.org/blas/blast-forum/

AUTHOR

Ralph Schleicher <rs@ralph-schleicher.de>