MainPage.html

Go to the documentation of this file.

/*!
\mainpage
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr><hr>
<h2>What's new?</h2>
<p>
[May 11th 2015]
"cpplapack-2015.05.11" has been released.
This release is only for the users who don't like to use svn.
(We still highly recommend users to use the latest svn code!!)
Not only "tar.gz", "rpm" and "deb" (made by alien) packages were prepared.
There are some major modifications in this release, and thus users may need to modify the following points in your codes:
<ul>
  <li>
    The BLAS/LAPACK fictions are put in CPPL namespace.
    Put "CPPL::" at the head of each direct call of BLAS/LAPACK fictions.
  </li>
  <li>
    The argument style of the BLAS/LAPACK fictions is changed to FORTRAN style.
    Not only array objects but also non-array objects must be passed as the addresses of the objects.
    Put "&amp;" at the head of each non-array argument of directly-called BLAS/LAPACK fictions.
  </li>
  <li>
    The default type of an integer is revised to "CPPL_INT" from "long".
    "CPPL_INT" denotes "MKL_INT" on Intel/MKL and "int" on g++ etc..
    Note that "long" is no longer valid.
  </li>
</ul>
e.g.)<br>
Old code:<br>
<code>
&nbsp;&nbsp; long NRHS(mat.n), LDA(n), *IPIV(new long[n]), LDB(mat.m), INFO(1);<br>
&nbsp;&nbsp; dgesv_(n, NRHS, array, LDA, IPIV, mat.array, LDB, INFO);<br>
</code>
New code:<br>
<code>
  &nbsp;&nbsp; CPPL_INT NRHS(mat.n), LDA(n), *IPIV(new CPPL_INT[n]), LDB(mat.m), INFO(1);<br>
  &nbsp;&nbsp; CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);<br>
</code>
or<br>
<code>
  &nbsp;&nbsp; int NRHS(mat.n), LDA(n), *IPIV(new int[n]), LDB(mat.m), INFO(1);<br>
  &nbsp;&nbsp; CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);<br>
</code>
(It is OK to use "int" instead of "CPPL_INT" on most platforms.)
</p>

<p>
[Feb. 8th 2014]
"cpplapack-2014.02.08" has been released.
This release is only for the users who don't like to use svn.
(We still highly recommend users to use the latest svn code!!)
Not only "tar.gz", "rpm" and "deb" (made by alien) packages were prepared.
See the logs of svn to get the "ChangeLog".
</p>

<p>
[Mar. 27th 2010]
"cpplapack-2010.03.27" has been released.
This release is only for the users who don't like to use svn.
(We still recommend users to use svn.:))
Not only "tar.gz" but also "rpm" and "deb" packages were prepared.
See the logs of svn to get the "ChangeLog".
</p>

<p>
[Sep. 25th 2006]
"cpplapack-2006_09_25" has been released.
The general sparse matrix(dgsmatrix, zgsmatrix) and symmetric or hermitial sparse matrix(dssmatrix,zhsmatrix) were formally added. 
This release also contains some bug fixes.
See "ChangeLog" for the detail.
</p>

<p>
[Mar. 25th 2005]
"cpplapack-2005_03_25" has been released.
This release contains some bug fixes and modification.
See "ChangeLog" for the detail.
It also contains the alpha version of sparse matrix classes (dssmatrix and zssmatrix).
These classes are still so buggy, but it is OK as long as you don't use these classes in your code.
</p>

<p>
[Oct. 15th 2004]
Mr. Ueshima wrote a tutorial of CPPLapack in Japanese.
"cpplapack-2004_04_24" has been released.
It is very useful for beginners of CPPLapack.
The HTML version is available at 
<a href="http://cpplapack.sourceforge.net/tutorial/japanese/index.html">
http://cpplapack.sourceforge.net/tutorial/japanese/index.html</a>,
and the PDF version is available at 
<a href="http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf">http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf</a>
</p>

<p>
[Apr. 24th 2004]
"cpplapack-2004_04_24" has been released.
OpenMP macros (<code>\#pragma omp parallel for private(j,k)</code>) 
are added to all triple for-loops. 
The search engine for this documentation is added.
This search engine is case-sensitive.
</p>

<p>
[Apr. 1st 2004]
"cpplapack-2004_04_01" has been released.
The complex double-precision matrix and vector classes 
(zgematrix, zgbmatrix, zhematrix, zcovector, zrovector)
are newly added.
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr><hr>
<h2>Introduction</h2>
<p>
CPPLapack is a C++ class wrapper for BLAS, LAPACK and PARDISO.
</p>

<p>
The interfaces of Fortran BLAS, LAPACK, CBLAS, and CLAPACK are not user-friendly, and induce a lot of coding mistakes not only for LAPACK beginners but also experienced programmers. 
Because of its difficult interface, BLAS functions are not widely used for simple matrix calculations such as "+", "-", "*", and so on even though these calculations are frequently required.
If there is a user-friendly library using BLAS and LAPACK in the background, it is really useful to minimize the program development time and computational time at the same time.
Existing matrix libraries, however, are not sufficient as far as we know.
</p>

<p>
CPPLapack has a very user-friendly interface 
as same as ordinary C++ matrix libraries.
Moreover, CPPLapack uses BLAS and LAPACK functions in the background though programmers just need to write simple codes such as <code>"A=B*C;"</code>, <code>"A.dgesv(y);"</code>, and so on.
</p>

<p>
The advantage of using CPPLapack are not only user-friendly interface and fast computational speed but also saving memory space.
In case of large-size matrix calculation, the number of copy times of objects affects required memory space and computational time materially.
CPPLapack has a mechanism called "Smart-Temporary" system to minimize the number of copy times.
The "Smart-Temporary" system is also hidden in CPPLapack library so that programmers don't need to pay any attention for this system.
(CPPLapack used to employed "to_return" system.
Now CPPLapack uses this system to realize the same purpose with keeping the compatibility with old versions.)
</p>

<p>
This program is designed for large matrix calculation.
If you don't have mind to handle large matrices, 
to use another matrix library is recommended.
</p>

<p>
CPPLapack is still a beta program so far.
It is a shame but there are a few bugs and unsupported BLAS and LAPACK functions.
If you are going to use CPPLapack, please be aware this situation.
Of course, it is very nice if you help us to develop CPPLapack.
</p>


<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>Special Features</h2>
<ul>
<li>
User-friendly interface<br>
</li>
<li>
Hi-speed matrix calculations using BLAS, LAPACK and PARDISO<br>
</li>
<li>
Minimized number of copy times of objects using "Smart-Temporary" system<br>
</li>
</ul>
All of the features are hidden in C++ class library 
so that programmers are not required to do any special programming.


<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>Where to Get</h2>
<p>
The official distribution site of CPPLapack is
<a href="http://sourceforge.net/projects/cpplapack/">here</a>.
It is highly recommended to use the latest svn code on the linked page.
</p>


<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>How to Install</h2>
<p>
Actually, you don't need to install CPPLapack.
CPPLapack 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 "cpplapack.h".
</p>

<p>
But CPPLapack needs BLAS and LAPACK written in Fortran installed. 
Just make sure these two libraries are installed and modify "Makefile" to include and link to them. 
In stead of original BLAS and LAPACK packages, bender-supplied libraries such as Intel math kernel library (MKL) are also acceptable.
Note that Intel MKL is necessary to use PARDISO for sparse matrices.
</p>

<p>
What BLAS and LAPACK need to link depends on your platform. 
Some examples of "Makefile" are prepared. 
See \ref pg-makefile.
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>Important Specification</h2>
<ul>
<li>
The namespace for CPPLapack is "CPPL".
</li>
<li>
You should not and don't need to use underscored matrix classes. 
These classes are not for project codes. 
The underscored classes are called "Smart-Temporary" classes.
The detail of "Smart-Temporary" system is explained in \ref pg-nt.
</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).
See \ref pg-bandmatrix for information of a band matrix.
</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, and array are the const reference objects so that they can be used to obtain the data but cannot be overwritten.
</li>
<li>
LAPACK member functions implemented in CPPLapack, such as A.dgesv(y), overwrite the matrix A.
When you need to keep the original matrix A, you have to make a copy of the matrix A before using LAPACK member functions.
</li>
<li>
For easy debugging, "CPPL_VERBOSE" and "CPPL_DEBUG" macros are prepared. 
When "-DCPPL_VERBOSE" is specified in compilation commands, every called function outputs its function name to stderr.
When "-DCPPL_DEBUG" is specified in compilation commands, matrix bounds checking are enabled. 
We recommend you to enable these macros during the program testing, then recompile codes without these macros for CPPLapack'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, 
<code>"dcovector f(const dcovector&amp; x){ return 2*x; }"</code>,
<code>f(x);</code> is also not good. 
These are because of the "Smart-Temporary" system. 
See \ref pg-nt. 
</li>
</ul>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<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 CPPLapack.

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

<p>
The performance of CPPLapack is almost the same as the performance of original BLAS and LAPACK.
However, some of arguments of BLAS and LAPACK functions such as ALPHA, BETA, TRANS, and so on are fixed at certain values.
When you want to make the full-use of BLAS and LAPACK functions, you can call their functions directory in codes of CPPLapack as usual.
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>FAQ</h2>
<p>
(Q)I found my program using CPPLapack 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>"CPPL::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)All the member variables are in "public".
Why don't you set "private" for capsulation?
<br>
(A)Matrix programings are frequently required to be custom-made.
Choosing "public" or "private" was a tough choice, and we chose "public" so that users could make custom-made functions without modifying CPPLapack itself.
</p>

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>License</h2>
CPPLapack is a GPL software without any guarantee.

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

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

<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>Links</h2>
CPPLapack Documents in Japanese:
<ul>
<li><a target="_blank" href="../main_page/Japanese.html">
CPPLapack Document in Japanese</a></li>
<li><a target="_blank" href="http://cpplapack.sourceforge.net/tutorial/japanese/index.html">
CPPLapack Tutorial in Japanese</a></li>
<li><a href="http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf">PDF of CPPLapack Tutorial in Japanese</a>
</ul>

The sister project of CPPLapack:
<ul>
<li><a target="_blank" href="http://sourceforge.net/projects/cppscalapack/">
CPPScaLapack</a></li>
</ul>

CPPLapack is based on and thanks to:
<ul>
<li><a target="_blank" href="http://netlib.caspur.it/blas/">
BLAS</a></li>
<li><a target="_blank" href="http://netlib.caspur.it/atlas/">
ATLAS</a></li>
<li><a target="_blank" href="http://www.netlib.org/lapack/">
LAPACK</a></li>
</ul>

<ul>
<li><a target="_blank" href="http://developer.intel.com/software/products/compilers/">
Intel C++ Compiler (ICC)</a></li>
<li><a target="_blank" href="http://developer.intel.com/software/products/mkl/index.htm">
Intel Math Kernel Library (MKL)</a></li>
<li><a target="_blank" href="http://h30097.www3.hp.com/linux/compaq_cxx/">
HP(Compaq) C++ Compiler for Linux Alpha (CXX)</a></li>
<li><a target="_blank" href="http://h18000.www1.hp.com/math/">
HP(Compaq) Math Libraries (CPML, CXML)</a></li>
<li><a target="_blank" href="http://www.mpack.com/">
NEC MathKeisan Library (MPACK)</a></li>
<li><a target="_blank" href="http://www.sgi.com/developers/devtools/apis/scsl.html">
SGI Scientific Computing Software Library (SCSL)</a></li>
<li><a target="_blank" href="http://www.amd.com/home/dev01">
AMD Core Math Library (ACML)</a></li>
</ul>
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<center><h3>Have fun.</h3></center>
*/