CPPScaLapack Documentation

Important Notice

Keeping the compatibility with old versions, CPPScaLapack had been totally revised in 2004. The packages released in 2003 are all old model versions of CPPScaLapack. The new CPPScaLapack doesn't have forbidden codes anymore. The "const" keyword works as it is expected in the new CPPScaLapack. It is recommended to update to the newest version. Comprex number support of the new CPPScaLapack is comming soon.

Introduction

CPPScaLapack is a c++ class wrapper for BLACS, PBLAS and ScaLAPACK.

CPPScaLapack is still an alpha program so far. It is a shame but there are a lot of bugs and unsupported PBLAS and ScaLAPACK functions. If you are going to use CPPScaLapack, please be aware this situation. Of course, it is very nice if you help us to develop CPPScaLapack.

Special Features

User-friendly interface
[See example codes of vector IO and example codes of matrix IO.]
Hi-speed matrix calculations using PBLAS and ScaLAPACK on MPI system
[See example codes of LAPACK functions.]
Minimized number of copy times of objects using "Smart Temporary" system
[See "description of Smart Temporary system" in the CPPLapack Documentation.]

All of the features are hidden in c++ class library so that programmers are not required to do any special programming.

Where to Get

The official distribution site of CPPScaLapack is here.

How to Install

Actually, you don't need to install CPPScaLapack. CPPScaLapack is a bunch of c++ header files. Just expand the package at somewhere you like, and write a include path in your "Makefile". All you need to include is only "cppscalapack.h" and "cppscalapack_init.h".

But CPPScaLapack needs BLACS, PBLAS and ScaLAPACK installed. Just make sure these libraries are installed and modify "Makefile" to include and link to them.

What BLAS and LAPACK need to link depends on your platform. An examples of "Makefile" for the Score platform is prepared. See typical Makefiles.

Important Specification

The namespace for CPPScaLapack is "CPPSL".
Currently, CPPScaLapack provides the following matrix classes, dgematrix, dcovector, and drovector. In the class list, you see other matrix classes, _dgematrix, _dcovector, and _drovector. However, theses matrix classes are not for project codes. You should not and don't need to use these underscored matrix classes. The underscored classes are called "Smart-Temporary" classes. The detail of "Smart-Temporary" system is explained in the CPPLapack documentation.
The numbering system of the matrix component is NOT 1-based but 0-based. In case of m x n matrix, the element number at the upper left is (0,0), and the element number at the lower right is (m-1,n-1).
The matrix arrays are stored in column-major style. although most of C programmers like to use row-major style. This is because of the conventional Fortran LAPACK style.
The matrix and vector member objects m, n, l, ml, nl, ll, and array are the const reference objects so that they can be used to obtain the data but cannot be overwritten.
For easy debugging, "CPPSL_DEBUG" macro is prepared. When "-DCPPSL_DEBUG" is specified in compilation commands, verbose debugging messages and matrix bounds checking are enabled. We recommend you to enable this macro during the program testing, then recompile codes without this macro for CPPScaLapack's best performance.
It is important not to leave out the returned object. The calculated and returned object must be substituted to an object. For example, A+B; is not good. For another example, when "dcovector f(const dcovector& x){ return 2*x; }", f(x); is also not good. These are because of "Smart-Temporary" system.

Test Programs

Test programs to check the operations are there in "test" directory. They are also easy examples for you to learn how to use CPPScaLapack.

Benchmark Programs

Some programs to estimate the speed of CPPScaLapack are prepared in "benchmark" directory.

The performance of CPPScaLapack is almost the same as the performance of original PBLAS and ScaLAPACK. However, some of arguments of PBLAS and ScaLAPACK functions such as alpha, beta, Transpose, and so on are fixed at certain values. When you want to make the full-use of PBLAS and ScaLAPACK functions, you can call their functions directory in codes of CPPScaLapack as usual.

FAQ

(Q)I found my program using CPPScaLapack consuming the memory larger and larger in a loop. Why does this happen?
(A)Most likely, you leave out some returned matrix or vector object in the loop. Please read "Important Specification" section carefully.

(Q)When I print components of a matrix or vector, I sometimes see "nan" printed. What is the possible reason?
(A)First of all, please make sure that your objects are initialized. The constructor with size arguments such as "CPPSL::dgematrix A(5,10);" does NOT initialize its array components. The "resize" function does NOT initialize, neither. Please initialize objects using substitutions, or use "identity" or "zero" function to initialize them.

(Q)I see a lot of same outputs for each "cout" and "cerr" functions. How can I restrain these annoying outputs?
(A)Use "CPPSL::cout" and "CPPSL::cerr" instead of "std::cout" and "std::cerr". I will see only one output of the 0th node.

License

CPPScaLapack is an open-source, free, and unguaranteed software.

Author and Cooperators

Author: Yuki ONISHI
Cooperator: Masafumi IAI, Toshiyasu SHIMIZU

Bug Report

Please send bug reports to yuki.onishi@nifty.com. I also welcome any kind of comments.