MainPage.html

Go to the documentation of this file.

/*! 
\mainpage
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr><hr>
<h2>Important Notice</h2>
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.
<hr><hr>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Introduction</h2>
<p>
CPPScaLapack is a c++ class wrapper for BLACS, PBLAS and ScaLAPACK.
</p>

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

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Special Features</h2>
<ul>
<li>
User-friendly interface<br>
[See \ref pg-dco_io "example codes of vector IO" 
and \ref pg-dge_io "example codes of matrix IO".]
</li>
<li>
Hi-speed matrix calculations using PBLAS and ScaLAPACK on MPI system<br>
[See \ref pg-dge_lapack "example codes of LAPACK functions".]
</li>
<li>
Minimized number of copy times of objects using "Smart Temporary" system<br>
[See "description of Smart Temporary system" in the CPPLapack Documentation.]
</li>
</ul>
All of the features are hidden in c++ class library 
so that programmers are not required to do any special programming.

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Where to Get</h2>
<p>
The official distribution site of CPPScaLapack is
<a href="http://sourceforge.net/projects/cppscalapack/">here</a>.
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>How to Install</h2>
<p>
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".
</p>

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

<p>
What BLAS and LAPACK need to link depends on your platform.
An examples of "Makefile" for the Score platform is prepared.
See \ref pg-makefile "typical Makefiles".
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Important Specification</h2>
<ul>
<li>
The namespace for CPPScaLapack is "CPPSL".
</li>

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

<li>
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).
</li>

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

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

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

<li>
It is important not to leave out the returned object. 
The calculated and returned object must be substituted to an object. 
For example, <code>A+B;</code> is not good. 
For another example, when 
<code>"dcovector f(const dcovector&amp; x){ return 2*x; }"</code>,
<code>f(x);</code> is also not good. 
These are because of "Smart-Temporary" system. 
</li>

</ul>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Test Programs</h2>
Test programs to check the operations are there in "test" directory.
They are also easy examples for you to learn how to use CPPScaLapack.

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Benchmark Programs</h2>
<p>
Some programs to estimate the speed of CPPScaLapack are prepared 
in "benchmark" directory.
</p>

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

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


<p>
(Q)When I print components of a matrix or vector, 
I sometimes see "nan" printed. What is the possible reason?
<br>
(A)First of all, please make sure that your objects are initialized.
The constructor with size arguments such as 
<code>"CPPSL::dgematrix A(5,10);"</code>
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.
</p>

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

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>License</h2>
CPPScaLapack is an open-source, free, and unguaranteed software.

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Author and Cooperators</h2>
Author: &nbsp;
Yuki ONISHI<br>
Cooperator: &nbsp;
Masafumi IAI, &nbsp;
Toshiyasu SHIMIZU

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Bug Report</h2>
Please send bug reports to 
<a href="mailto:yuki.onishi@nifty.com">yuki.onishi@nifty.com</a>.
I also welcome any kind of comments.

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<h2>Links</h2>
The sister project of CPPScaLapack:
<ul>
<li><a target="out" href="http://sourceforge.net/projects/cpplapack/">
CPPLapack</a></li>
</ul>

CPPScaLapack is based on and thanks to:
<ul>
<li><a target="out" href="http://netlib.caspur.it/blacs/">
BLACS</a></li>
<li><a target="out" href="http://www.netlib.org/scalapack/">
PBLAS and ScaLapack</a></li>
<br>
<li><a target="out" href="http://www.mpack.com/">
NEC MathKeisan Library (MPACK)</a></li>
<br>
<li><a target="out" href="http://www.a.mei.titech.ac.jp/">
Tokyo Institute of Technology Kenji Amaya's Lab</a></li>
<li><a target="out" href="http://www.gsic.titech.ac.jp/English/index.html">
Tokyo Institute of Technology 
Global Scientific Information and Computing Center</a></li>
</ul>
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<center><h3>Have fun.</h3></center>

*/

---