LAPACK++ V. 1.

1
High Performance Linear Algebra Class Reference Guide April 1996
Jack Dongarra Roldan Pozo David Walker
National Institute of Standards and Technology Oak Ridge National Laboratory University of Tennessee, Knoxville

Contents
Vector : : : : : : : : LaGenMat : : : : : : LaIndex : : : : : : : LaColVector : : : : : LaRowVector : : : : LaSymmMat : : : : LaUpperTriangMat : Utilities : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 1 4 8 9 10 11 14 17

Vector

Matrix++ Library VectorDouble |- lightweight vector class

Vector

Name Description

One-dimensional storage class with minimal overhead. It is one step above a C array, only in that utilizes share-semantics (similar to C++ string classes) for optimizing memory usage. Not intended for mathematical denotations, but rather used as building block for other LAPACK++ matrix classes. only a container class, no mathematical operations de ned share semantics and reference counting scheme for dynamic garbage collection unit stride (elements are in contiguous memory locations) xed 0-based o set A(i) declared inline for e ciency auto conversion to basic pointer type e.g. double*

Declaration

#include hlafnames.hi #include VECTOR DOUBLE H Construct a vector of length n, (n 0). A vector of length zero is perfectly legal and usually termed a null vector. Vector elements are UNITIALIZED. Construct a vector of length n and initialize all elements to the scalar value s. Construct a n-length vector as a view (share semantics) of an existing C/C++ array. Further changes to elements of x will be re ected in VectorDouble. Create a new n-length vector as a view (share semantics) of an existing VectorDouble. Further changes to V will be be re ected in VectorDouble. Reclaim vector memory space if this the only structure using it.

VectorDouble ( int n = 0 )

VectorDouble ( int n , double s )

VectorDouble ( double * x , int n )

VectorDouble ( const VectorDouble& V ) VectorDouble ( )

Assignments

VectorDouble& operator= ( const VectorDouble& V ) Release left-hand side (reclaiming memory space if possible) and construct a new view of V. Further changes to V will be re ected in left-hand side. Return reference to new view. VectorDouble& operator= ( double s ) Set elements of left-hand size to the scalar value s. 1

Version 1.0

May 10, 1996

Vector

Matrix++ Library

Vector

VectorDouble& inject ( const VectorDouble& V ) Copy elements of V into the memory space referenced by the left-hand side, without rst releasing it. The e ect is that if other vectors share memory with left-hand side, they too will be a ected. Note that the length of V must be same be the same as that of the left-hand side vector. VectorDouble& copy ( VectorDouble& V ) Release left-hand side and copy elements of V. Unlike VectorDouble::inject() it does not require conformity, and previous references of left-hand side are una ected. int resize ( int n ) Resize to a new vector of length n. The element values are UNINITALIZED, even if n is less than the current vector length.

Access Functions

double& operator ( )(inti) Return ith element of vector, with zero-based o set. Optional runtime bounds checking (0 i n) set by compile time macro VECTOR DOUBLE BOUNDS CHECK. double& operator ] ( int i ) Identical to VectorDouble::operator() above. Included only for compatibility to C/C++ ] syntax. int size ( ) Return the length, n, of the vector. int ref count ( ) Return the number of the data objects to utilize the same (or portions of the same) memory space used by this vector. int null ( ) Shorthand to test if zero-length vector. Identical to return size()==0;. operator double * ( ) Return address of rst element; equilavent to &V(0). Used to mimic use of C arrays, (e.g. as in parameters to functions).

Information Functions

Conversions Macros

VECTOR DOUBLE BOUNDS CHECK

Compile time macro, either de ned or unde ned to perform bounds checking (0 i n) in a n-length vector. The default is NOT to perform this check (this is consistent with C/C++); however, it is highly recommended to utilize this check { particularly during initial phases of development, testing, and debugging. There is a performance penalty for this, (essentially a boolean test at each element reference), so it can turned o for production runs where performance may be critical. 2
May 10, 1996

Version 1.0

Vector

Matrix++ Library

Vector

Debugging

int debug ( int d ) Set global debug ag to value speci ed by d. If d is nonzero, then all entry and exit points of methods and operators of LaGenMatDouble are traced. int debug ( ) Read the global debug ag.

I/O Functions See also

friend ostream& operator < < ( ostream& s , const VectorDouble& V ) Print vector (on one line), with elements separated by white space. LaGenMatDouble, LaVectorDouble

Version 1.0

May 10, 1996

LaGenMat

Matrix++ Library LaGenMatDouble |- general dense matrix, a two-dimensional array Basic LAPACK++ matrix:

LaGenMat

Name Description

uses (deep) copy semantics optimizes assignment of temporaries via shallow assignments indexing via A(i,j) where i; j are either integers or LaIndex indices. non-unit strides in both directions utilizes VectorDouble container class has basic BLAS++ math functionality cout << A.info() prints out internal states of A optimized to avoid memory copies when returning temporary LaGenMatDouble results by value from functions auto conversion to basic pointer type e.g. double*

Declaration

#include hlafnames.hi #include LA GEN MAT DOUBLE H

LaGenMatDouble ( )

Construct a null 0 0 matrix.

Construct a column-major matrix of size m n, (m; n 0). Matrix elements are UNITIALIZED. Construct a column-major matrix of size m n, (m; n 0), and initialize matrix elments to the scalar s. Construct an m n matrix by copying the values from a one-dimensional C/C++ array of length mn.

LaGenMatDouble ( int m , int n )

LaGenMatDouble ( int m , int n , double s )

LaGenMatDouble ( double * v , int m , int n )

LaGenMatDouble ( const LaGenMatDouble& V )

Create a new matrix from an existing one by copying.

int resize ( int m , int n ) Resize to a new matrix of size m n. The element values are UNINITALIZED, even if resizing to a smaller matrix. Destroy matrix and reclaim vector memory space if this the only structure using it.
Version 1.0

LaGenMatDouble ( )

May 10, 1996

LaGenMat

Matrix++ Library

LaGenMat

Assignments

LaGenMatDouble& operator= ( const LaGenMatDouble& V ) Release left-hand side (reclaiming memory space if possible) and construct a new copy of V. Return reference to new copy. LaGenMatDouble& operator= ( double s ) Set elements of left-hand size to the scalar value s. No new matrix is created, so that if there other matrices that reference this memory space, they will also be a ected. LaGenMatDouble& inject ( const LaGenMatDouble& V ) Copy elements of V into the memory space referenced by the left-hand side, without rst releasing it. The e ect is that if other matrices share memory with left-hand side, they too will be a ected. Note that the size of V must be same be the same as that of the left-hand side matrix. LaGenMatDouble& copy ( LaGenMatDouble& V ) Release left-hand side and copy elements of V. Unlike LaGenMatDouble::inject() it does not require conformity, and previous references of left-hand side are unaffected. LaGenMatDouble& shallow assign ( ) This is an optimization for returning temporary matrices from functions, without copying. Consider the following function
LaGenMatDouble foo(LaGenMatDouble &A, LaGenMatDouble &B) { return A B; }

A temporary matrix is constructed by the compiler to hold the result of A+B and the result is returned from the function call by the X::X(&X) copy constructor. This may cause unnecessary copying, depending on the degree of optimization employed by the particular compiler implementation. By adjusting this by hand, as in
return (A B).shallow_assign();

one can avoid typical data copying. The shallow assign() function essentially sets an internal ag which instructs the X::X(&X) copy constructor to avoid the copying.

Access Functions

double& operator ( int i , int j ) Return (i; j)th element of vector, with zero-based o set. Optional runtime bounds checking (0 i m), (0 j n), set by compile time macro LA BOUNDS CHECK.

Version 1.0

May 10, 1996

LaGenMat

Matrix++ Library

LaGenMat

double& operator ( LaIndex I , LaIndex J ) Return submatrix view speci ed by indices I and J. (See LaIndex class.) These indices specify start, increment, and ending o sets, similar to triplet notation of Matlab or Fortran 90. For example, if B is a 10 10 matrix, I is (0 : 2 : 2) and J is (3: 1: 4), then B(I,J) denotes the 2 2 matrix b0 3 b2 3 b0 4 b4 4 .
; ; ; ;

Information Functions

double * addr ( ) Returns the memory address of the rst element of the matrix. G.addr() is equivalent to &G(0,0). int size ( int d ) Return the length, n, of the dth dimension, i.e. for an M returns M and size(1) returns N. N matrix size(0)

int inc ( int d ) Return the distance between memory locations (in terms of # of elements) between consecutive elements along dimension d. For example, if inc(d) returns 1, then elements along the dth dimension are contiguous in memory. int gdim ( int d ) Return the global dimensions of the (possibly larger) matrix owning this space. This will only di er from size(d) if the current matrix is actually a submatrix view of some larger matrix. int start ( int d ) If the memory space used by this matrix is viewed as a linear array, start(d) returns the starting o set of the rst element in dimension d. (See LaIndex class.) int end ( int d ) If the memory space used by this matrix is viewed as a linear array, start(d) return the starting o set of the last element in dimension d. (See LaIndex class.) int ref count ( ) Returns the number of data objects which utilize the same (or portions of the same) memory space used by this matrix. LaGenMatDouble& info ( ) Used in conjunction with an ostream to print diagnostics about the matrix. For example, if A is a 10 10 matrix that does not share its space with any other matrix, then cout << A.info(); could produce 6

Version 1.0

May 10, 1996

LaGenMat

Matrix++ Library
(10x10) Indices: (0,9) (0,9) #ref: 1 shallow:0

LaGenMat

This indicates a 10 10 matrix with 0-based o set, a reference count of 1, and the shallow ag turned o .

Conversions Macros

operator double * ( ) Returns the address of the rst element; equivalent to &V(0,0). Used to mimic use of C arrays, (e.g. as parameters passed to functions).

LA BOUNDS CHECK

Compile time macro, either de ned or unde ned to perform bounds checking on matrix indexing operations. The default is NOT to perform this check (this is consistent with C/C++); however, it is highly recommended to utilize this check { particularly during initial phases of development, testing, and debugging. There is a performance penalty for this, (essentially a boolean test at each element reference) so it can turned o for production runs, where performance may be critical. friend ostream& operator < < ( ostream& s , const LaGenMatDouble& V ) Print vector (on one line), with elements separated by white space. LaVectorDouble, VectorDouble

I/O Functions See also

Version 1.0

May 10, 1996

LaIndex

Matrix++ Library LaIndex |- indexing into vectors and matrices

LaIndex

LaIndex

Name Description

is an integer triplet denoting the start, increment, and ending indices of a vector view. For example, if B = f0:0; 0:1;0:2; 0:3;0:4; 0:5;0:6g

then sets B to and is equivalent to

B(LaIndex(1,2,5)) = 9.9

B = f0:0; 0:1; 9:9;0:3; 9:9;0:4; 9:9;0:6g < +=

2)

for (i=1; i =5, i B(i) = 9.9;

Declaration

#include hlafnames.hi #include LA INDEX H

LaIndex ( )

Construct a null index (start=inc=end=0). This special value of LaIndex defaults to the complete vector size. For example,
B(Index()) = A;

will set all elements of B to those of A. This is equivalent to writing

B(LaIndex(0,B.size()-1) = A;

or
for (int i=0; i N; i B(i) = A(i);

<

++)

Version 1.0

May 10, 1996

LaColVector

Matrix++ Library LaColVectorDouble { a column vector, i.e. an n 1 matrix.

LaColVector

Name Description Declaration

LaColVectorDouble represents a column vector. It is identical to an n 1 LaGenMatDouble, except that it can be indexed by a single integer.

#include hlafnames.hi #include LA COL VECTOR DOUBLE H Construct a null 0 1 matrix. Construct a column-major matrix of size n 1, (n UNITIALIZED.

LaColVectorDouble ( )

LaColVectorDouble ( int n )

0). Vector elements are 0), and initalize matrix

LaColVectorDouble ( int n , double s )

Construct a column-major matrix of size n 1, (n elements to the scalar s.

Construct an n 1 matrix by copying the values from a one-dimensional C/C++ array of length n.

LaColVectorDouble ( double * v , int n )

LaColVectorDouble ( const LaColVectorDouble& V ) LaColVectorDouble ( )

Create a new column vector from an existing one by copying.

Destroy column vector and reclaim memory space if this the only structure using it.

Version 1.0

May 10, 1996

LaRowVector

Matrix++ Library LaRowVectorDouble { a row vector, i.e. an 1 n matrix.

LaRowVector

Name Description Declaration

LaRowVectorDouble represents a row vector. It is identical to an 1 n LaGenMatDouble, except that it can be indexed by a single integer.

#include hlafnames.hi #include LA COL VECTOR DOUBLE H Construct a null 1 0 matrix. Construct a row-major matrix of size 1 n, (n TIALIZED.

LaRowVectorDouble ( )

LaRowVectorDouble ( int n )

0). Vector elements are UNI-

Construct a row-major matrix of size 1 n, (n 0), and initialize matrix elements to the scalar s. Construct an row vector by copying the values from a one-dimensional C/C++ array of length n.

LaRowVectorDouble ( int n , double s )

LaRowVectorDouble ( double * v , int n )

LaRowVectorDouble ( const LaRowVectorDouble& V )

Create a new row vector from an existing one by copying. Destroy row vector and reclaim memory space if this the only structure using it.

LaRowVectorDouble ( )

Version 1.0

10

May 10, 1996

LaSymmMat

Matrix++ Library LaSymmMatDouble |- square symmetric matrix uses (deep) copy semantics optimizes assignment of temporaries via shallow assignments non-unit strides in both directions utilizes VectorDouble container class has basic BLAS++ math functionality cout << A.info() prints out internal states of A

LaSymmMat

Name Description

Declaration

#include hlafnames.hi #include LA SYMM MAT DOUBLE H LaSymmMatDouble ( ) Construct a null 0 0 matrix. LaSymmMatDouble ( int m , int n ) Construct a column-major matrix of size m n, (m; n 0). Matrix elements are UNITIALIZED. LaSymmMatDouble ( int m , int n , double s ) Construct a column-major matrix of size m n, (m; n 0), and initialize matrix elments to the scalar s. LaSymmMatDouble ( double * v , int m , int n ) Construct an m n (m = n) symmetric matrix by copying the values from a one-dimensional C/C++ array of length mn. LaSymmMatDouble ( const LaSymmMatDouble& V ) Create a new symmetric matrix from an existing one by copying. int resize ( int m , int n ) Resize to a new matrix of size m n. The element values are UNINITALIZED, even if resizing to a smaller matrix. LaSymmMatDouble ( ) Destroy matrix and reclaim vector memory space if this the only structure using it. LaSymmMatDouble& operator= ( const LaSymmMatDouble& V ) Release left-hand side (reclaiming memory space if possible) and construct a new copy of V. Return reference to new copy. LaSymmMatDouble& operator= ( double s ) Set elements of left-hand size to the scalar value s. No new matrix is created, so that if there other matrices that reference this memory space, they will also be a ected. 11
May 10, 1996

Assignments

Version 1.0

LaSymmMat

Matrix++ Library

LaSymmMat

LaSymmMatDouble& copy ( LaSymmMatDouble& V ) Release left-hand side and copy elements of V. Unlike LaSymmMatDouble::inject() it does not require conformity, and previous references of left-hand side are unaffected.

Access Functions Information Functions

double& operator ( int i , int j ) Return (i; j)th element of vector, with zero-based o set. Optional runtime bounds checking (0 i m), (0 j n), set by compile time macro LA BOUNDS CHECK. double * addr ( ) Returns the memory address of the rst element of the matrix. G.addr() is equivalent to &G(0,0). int size ( int d ) Return the length, n, of the dth dimension, i.e. for an M N matrix size(0) returns M and size(1) returns N. int inc ( int d ) Return the distance between memory locations (in terms of # of elements) between consecutive elements along dimension d. For example, if inc(d) returns 1, then elements along the dth dimension are contiguous in memory. int gdim ( int d ) Return the global dimensions of the (possibly larger) matrix owning this space. This will only di er from size(d) if the current matrix is actually a submatrix view of some larger matrix. int ref count ( ) Returns the number of data objects which utilize the same (or portions of the same) memory space used by this matrix. LaSymmMatDouble& info ( ) Used in conjunction with an ostream to print diagnostics about the matrix. For example, if A is a 10 10 matrix that does not share its space with any other matrix, then cout << A.info(); could produce
(10x10) Indices: (0,9) (0,9) #ref: 1 shallow:0

This indicates a 10 10 matrix with 0-based o set, a reference count of 1, and the shallow ag turned o .

Conversions

operator double * ( ) Returns the address of the rst element; equivalent to &V(0,0). Used to mimic use of C arrays, (e.g. as parameters passed to functions). 12
May 10, 1996

Version 1.0

LaSymmMat

Matrix++ Library

LaSymmMat

I/O Functions See also

friend ostream& operator < < ( ostream& s , const LaSymmMatDouble& V ) Print vector (on one line), with elements separated by white space. LaGenMat, LaVector, Vector

Version 1.0

13

May 10, 1996

LaUpperTriangMat

Matrix++ Library

LaUpperTriangMat

Name Description

LaUpperTriangMatDouble |- upper triangular matrix uses (deep) copy semantics optimizes assignment of temporaries via shallow assignments non-unit strides in both directions utilizes VectorDouble container class has basic BLAS++ math functionality cout << A.info() prints out internal states of A #include hlafnames.hi #include LA UPPER TRIANG MAT DOUBLE H

Declaration

LaUpperTriangMatDouble ( )
Construct a null 0 0 matrix.

LaUpperTriangMatDouble ( int m , int n )

Construct an upper triangular matrix of size m n, (m; n 0). Matrix elements are UNITIALIZED.

LaUpperTriangMatDouble ( int m , int n , double s )

Construct an upper triangular matrix of size m n, (m; n 0), and initialize matrix elments to the scalar s. Construct an m n (m = n) upper triangular matrix by copying the values from a one-dimensional C/C++ array of length mn.

LaUpperTriangMatDouble ( double * v , int m , int n )

LaUpperTriangMatDouble ( const LaUpperTriangMatDouble& V )

Create a new upper triangular matrix from an existing one by copying. int resize ( int m , int n ) Resize to a new matrix of size m n. The element values are UNINITALIZED, even if resizing to a smaller matrix. Destroy matrix and reclaim vector memory space if this the only structure using it.

LaUpperTriangMatDouble ( )

Assignments

LaUpperTriangMatDouble& operator= (

const LaUpperTriangMatDouble& V ) Release left-hand side (reclaiming memory space if possible) and construct a new copy of V. Return reference to new copy.

Version 1.0

14

May 10, 1996

LaUpperTriangMat

Matrix++ Library

LaUpperTriangMat

LaUpperTriangMatDouble& operator= ( double s ) Set elements of left-hand size to the scalar value s. No new matrix is created, so that if there other matrices that reference this memory space, they will also be a ected. LaUpperTriangMatDouble& copy ( LaUpperTriangMatDouble& V ) Release left-hand side and copy elements of V. Unlike LaUpperTriangMatDouble::inject() it does not require conformity, and previous references of left-hand side are unaffected.

Access Functions Information Functions

double& operator ( int i , int j ) Return (i; j)th element of vector, with zero-based o set. Optional runtime bounds checking (0 i m), (0 j n), set by compile time macro LA BOUNDS CHECK. double * addr ( ) Returns the memory address of the rst element of the matrix. G.addr() is equivalent to &G(0,0). int size ( int d ) Return the length, n, of the dth dimension, i.e. for an M N matrix size(0) returns M and size(1) returns N. int inc ( int d ) Return the distance between memory locations (in terms of # of elements) between consecutive elements along dimension d. For example, if inc(d) returns 1, then elements along the dth dimension are contiguous in memory. int gdim ( int d ) Return the global dimensions of the (possibly larger) matrix owning this space. This will only di er from size(d) if the current matrix is actually a submatrix view of some larger matrix. int ref count ( ) Returns the number of data objects which utilize the same (or portions of the same) memory space used by this matrix. LaUpperTriangMatDouble& info ( ) Used in conjunction with an ostream to print diagnostics about the matrix. For example, if A is a 10 10 matrix that does not share its space with any other matrix, then cout << A.info(); could produce
(10x10) Indices: (0,9) (0,9) #ref: 1 shallow:0

This indicates a 10 10 matrix with 0-based o set, a reference count of 1, and the shallow ag turned o .
Version 1.0

15

May 10, 1996

LaUpperTriangMat

Matrix++ Library

LaUpperTriangMat

Conversions I/O Functions See also

operator double * ( ) Returns the address of the rst element; equivalent to &V(0,0). Used to mimic use of C arrays, (e.g. as parameters passed to functions). friend ostream& operator < < ( ostream& s , const LaUpperTriangMatDouble& V ) Print vector (on one line), with elements separated by white space. LaGenMat, LaVector, Vector

Version 1.0

16

May 10, 1996

Utilities

Lapack++ Library lautil.h { various Lapack++ utilities

Utilities

Name Description

Contains various support functions for Lapack++. Some of these are internal to the Lapack++/Lapack interface. LaEnvBlockSize(), for example, is used to determine the size of temporary workspace required for some Lapack routines. int LaEnvBlockSize ( char * fname , LaGenMatDouble A ) Returns the block size used by Lapack for given subroutine name fname. (This string corresponds to the f77 name as documented in the Lapack Users' Guide.) int LaEnvBlockSize ( char * fname , LaSymmMatDouble A ) Returns the block size used by Lapack for given subroutine name fname. (This string corresponds to the f77 name as documented in the Lapack Users' Guide.) double Mach eps double ( ) Returns machine epsilon for double precision oating point format. (On most machines this should be in the range of 10^ 14 or so.) void LaSwap ( LaGenMatDouble &A, LaVectorLongInt &ipiv ) Swaps rows of matrix A according to pivot vector ipiv.

Version 1.0

17

May 10, 1996