/*!
\mainpage
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr><hr>
<h2>What's new?</h2>
<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 (#pragma omp parallel for private(j,k))
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 and LAPACK.
</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 and LAPACK<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>.
</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),
Compaq extended math library(CXML), and so on are also acceptable.
</p>
<p>
What BLAS and LAPACK need to link depends on your platform.
Some examples of "Makefile" are prepared.
See \ref pg-makefile.
</p>
<p>
For Cygwin users, a simple instructions on
how to install ATLAS and LAPACK is prepared.
See \ref pg-cygwin.
</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, when
<code>"dcovector f(const dcovector& 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>
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>License</h2>
CPPLapack is an open-source, free, and unguaranteed software.
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<h2>Author and Cooperators</h2>
Author:
Yuki ONISHI<br>
Cooperator:
Masafumi IAI,
Toshiyasu SHIMIZU,
Masashi UESHIMA
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<hr>
<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.
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<!---------------------------------------------------------------------------->
<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>
*/
