CPPLapack
 All Classes Files Functions Variables Friends Pages
MainPage.html
Go to the documentation of this file.
1 /*!
2 \mainpage
3 <!---------------------------------------------------------------------------->
4 <!---------------------------------------------------------------------------->
5 <!---------------------------------------------------------------------------->
6 <hr><hr>
7 <h2>What's new?</h2>
8 <p>
9 [May 11th 2015]
10 "cpplapack-2015.05.11" has been released.
11 This release is only for the users who don't like to use svn.
12 (We still highly recommend users to use the latest svn code!!)
13 Not only "tar.gz", "rpm" and "deb" (made by alien) packages were prepared.
14 There are some major modifications in this release, and thus users may need to modify the following points in your codes:
15 <ul>
16  <li>
17  The BLAS/LAPACK fictions are put in CPPL namespace.
18  Put "CPPL::" at the head of each direct call of BLAS/LAPACK fictions.
19  </li>
20  <li>
21  The argument style of the BLAS/LAPACK fictions is changed to FORTRAN style.
22  Not only array objects but also non-array objects must be passed as the addresses of the objects.
23  Put "&amp;" at the head of each non-array argument of directly-called BLAS/LAPACK fictions.
24  </li>
25  <li>
26  The default type of an integer is revised to "CPPL_INT" from "long".
27  "CPPL_INT" denotes "MKL_INT" on Intel/MKL and "int" on g++ etc..
28  Note that "long" is no longer valid.
29  </li>
30 </ul>
31 e.g.)<br>
32 Old code:<br>
33 <code>
34 &nbsp;&nbsp; long NRHS(mat.n), LDA(n), *IPIV(new long[n]), LDB(mat.m), INFO(1);<br>
35 &nbsp;&nbsp; dgesv_(n, NRHS, array, LDA, IPIV, mat.array, LDB, INFO);<br>
36 </code>
37 New code:<br>
38 <code>
39  &nbsp;&nbsp; CPPL_INT NRHS(mat.n), LDA(n), *IPIV(new CPPL_INT[n]), LDB(mat.m), INFO(1);<br>
40  &nbsp;&nbsp; CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);<br>
41 </code>
42 or<br>
43 <code>
44  &nbsp;&nbsp; int NRHS(mat.n), LDA(n), *IPIV(new int[n]), LDB(mat.m), INFO(1);<br>
45  &nbsp;&nbsp; CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);<br>
46 </code>
47 (It is OK to use "int" instead of "CPPL_INT" on most platforms.)
48 </p>
49 
50 <p>
51 [Feb. 8th 2014]
52 "cpplapack-2014.02.08" has been released.
53 This release is only for the users who don't like to use svn.
54 (We still highly recommend users to use the latest svn code!!)
55 Not only "tar.gz", "rpm" and "deb" (made by alien) packages were prepared.
56 See the logs of svn to get the "ChangeLog".
57 </p>
58 
59 <p>
60 [Mar. 27th 2010]
61 "cpplapack-2010.03.27" has been released.
62 This release is only for the users who don't like to use svn.
63 (We still recommend users to use svn.:))
64 Not only "tar.gz" but also "rpm" and "deb" packages were prepared.
65 See the logs of svn to get the "ChangeLog".
66 </p>
67 
68 <p>
69 [Sep. 25th 2006]
70 "cpplapack-2006_09_25" has been released.
71 The general sparse matrix(dgsmatrix, zgsmatrix) and symmetric or hermitial sparse matrix(dssmatrix,zhsmatrix) were formally added.
72 This release also contains some bug fixes.
73 See "ChangeLog" for the detail.
74 </p>
75 
76 <p>
77 [Mar. 25th 2005]
78 "cpplapack-2005_03_25" has been released.
79 This release contains some bug fixes and modification.
80 See "ChangeLog" for the detail.
81 It also contains the alpha version of sparse matrix classes (dssmatrix and zssmatrix).
82 These classes are still so buggy, but it is OK as long as you don't use these classes in your code.
83 </p>
84 
85 <p>
86 [Oct. 15th 2004]
87 Mr. Ueshima wrote a tutorial of CPPLapack in Japanese.
88 "cpplapack-2004_04_24" has been released.
89 It is very useful for beginners of CPPLapack.
90 The HTML version is available at
91 <a href="http://cpplapack.sourceforge.net/tutorial/japanese/index.html">
92 http://cpplapack.sourceforge.net/tutorial/japanese/index.html</a>,
93 and the PDF version is available at
94 <a href="http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf">http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf</a>
95 </p>
96 
97 <p>
98 [Apr. 24th 2004]
99 "cpplapack-2004_04_24" has been released.
100 OpenMP macros (<code>\#pragma omp parallel for private(j,k)</code>)
101 are added to all triple for-loops.
102 The search engine for this documentation is added.
103 This search engine is case-sensitive.
104 </p>
105 
106 <p>
107 [Apr. 1st 2004]
108 "cpplapack-2004_04_01" has been released.
109 The complex double-precision matrix and vector classes
110 (zgematrix, zgbmatrix, zhematrix, zcovector, zrovector)
111 are newly added.
112 </p>
113 
114 <!---------------------------------------------------------------------------->
115 <!---------------------------------------------------------------------------->
116 <!---------------------------------------------------------------------------->
117 <hr><hr>
118 <h2>Introduction</h2>
119 <p>
120 CPPLapack is a C++ class wrapper for BLAS, LAPACK and PARDISO.
121 </p>
122 
123 <p>
124 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.
125 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.
126 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.
127 Existing matrix libraries, however, are not sufficient as far as we know.
128 </p>
129 
130 <p>
131 CPPLapack has a very user-friendly interface
132 as same as ordinary C++ matrix libraries.
133 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.
134 </p>
135 
136 <p>
137 The advantage of using CPPLapack are not only user-friendly interface and fast computational speed but also saving memory space.
138 In case of large-size matrix calculation, the number of copy times of objects affects required memory space and computational time materially.
139 CPPLapack has a mechanism called "Smart-Temporary" system to minimize the number of copy times.
140 The "Smart-Temporary" system is also hidden in CPPLapack library so that programmers don't need to pay any attention for this system.
141 (CPPLapack used to employed "to_return" system.
142 Now CPPLapack uses this system to realize the same purpose with keeping the compatibility with old versions.)
143 </p>
144 
145 <p>
146 This program is designed for large matrix calculation.
147 If you don't have mind to handle large matrices,
148 to use another matrix library is recommended.
149 </p>
150 
151 <p>
152 CPPLapack is still a beta program so far.
153 It is a shame but there are a few bugs and unsupported BLAS and LAPACK functions.
154 If you are going to use CPPLapack, please be aware this situation.
155 Of course, it is very nice if you help us to develop CPPLapack.
156 </p>
157 
158 
159 <!---------------------------------------------------------------------------->
160 <!---------------------------------------------------------------------------->
161 <!---------------------------------------------------------------------------->
162 <hr>
163 <h2>Special Features</h2>
164 <ul>
165 <li>
166 User-friendly interface<br>
167 </li>
168 <li>
169 Hi-speed matrix calculations using BLAS, LAPACK and PARDISO<br>
170 </li>
171 <li>
172 Minimized number of copy times of objects using "Smart-Temporary" system<br>
173 </li>
174 </ul>
175 All of the features are hidden in C++ class library
176 so that programmers are not required to do any special programming.
177 
178 
179 <!---------------------------------------------------------------------------->
180 <!---------------------------------------------------------------------------->
181 <!---------------------------------------------------------------------------->
182 <hr>
183 <h2>Where to Get</h2>
184 <p>
185 The official distribution site of CPPLapack is
186 <a href="http://sourceforge.net/projects/cpplapack/">here</a>.
187 It is highly recommended to use the latest svn code on the linked page.
188 </p>
189 
190 
191 <!---------------------------------------------------------------------------->
192 <!---------------------------------------------------------------------------->
193 <!---------------------------------------------------------------------------->
194 <hr>
195 <h2>How to Install</h2>
196 <p>
197 Actually, you don't need to install CPPLapack.
198 CPPLapack is a bunch of C++ header files.
199 Just expand the package at somewhere you like,
200 and write a include path in your "Makefile".
201 All you need to include is only "cpplapack.h".
202 </p>
203 
204 <p>
205 But CPPLapack needs BLAS and LAPACK written in Fortran installed.
206 Just make sure these two libraries are installed and modify "Makefile" to include and link to them.
207 In stead of original BLAS and LAPACK packages, bender-supplied libraries such as Intel math kernel library (MKL) are also acceptable.
208 Note that Intel MKL is necessary to use PARDISO for sparse matrices.
209 </p>
210 
211 <p>
212 What BLAS and LAPACK need to link depends on your platform.
213 Some examples of "Makefile" are prepared.
214 See \ref pg-makefile.
215 </p>
216 
217 <!---------------------------------------------------------------------------->
218 <!---------------------------------------------------------------------------->
219 <!---------------------------------------------------------------------------->
220 <hr>
221 <h2>Important Specification</h2>
222 <ul>
223 <li>
224 The namespace for CPPLapack is "CPPL".
225 </li>
226 <li>
227 You should not and don't need to use underscored matrix classes.
228 These classes are not for project codes.
229 The underscored classes are called "Smart-Temporary" classes.
230 The detail of "Smart-Temporary" system is explained in \ref pg-nt.
231 </li>
232 <li>
233 The numbering system of the matrix component is NOT 1-based but 0-based.
234 In case of m x n matrix,
235 the element number at the upper left is (0,0), and the element number at the lower right is (m-1,n-1).
236 See \ref pg-bandmatrix for information of a band matrix.
237 </li>
238 <li>
239 The matrix arrays are stored in column-major style.
240 although most of C programmers like to use row-major style.
241 This is because of the conventional Fortran LAPACK style.
242 </li>
243 <li>
244 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.
245 </li>
246 <li>
247 LAPACK member functions implemented in CPPLapack, such as A.dgesv(y), overwrite the matrix A.
248 When you need to keep the original matrix A, you have to make a copy of the matrix A before using LAPACK member functions.
249 </li>
250 <li>
251 For easy debugging, "CPPL_VERBOSE" and "CPPL_DEBUG" macros are prepared.
252 When "-DCPPL_VERBOSE" is specified in compilation commands, every called function outputs its function name to stderr.
253 When "-DCPPL_DEBUG" is specified in compilation commands, matrix bounds checking are enabled.
254 We recommend you to enable these macros during the program testing, then recompile codes without these macros for CPPLapack's best performance.
255 </li>
256 <li>
257 It is important NOT to leave out the returned object.
258 The calculated and returned object must be substituted to an object.
259 For example, <code>A+B;</code> is not good.
260 For another example,
261 <code>"dcovector f(const dcovector&amp; x){ return 2*x; }"</code>,
262 <code>f(x);</code> is also not good.
263 These are because of the "Smart-Temporary" system.
264 See \ref pg-nt.
265 </li>
266 </ul>
267 
268 <!---------------------------------------------------------------------------->
269 <!---------------------------------------------------------------------------->
270 <!---------------------------------------------------------------------------->
271 <hr>
272 <h2>Test Programs</h2>
273 Test programs to check the operations are there in "test" directory.
274 They are also easy examples for you to learn how to use CPPLapack.
275 
276 <!---------------------------------------------------------------------------->
277 <!---------------------------------------------------------------------------->
278 <!---------------------------------------------------------------------------->
279 <hr>
280 <h2>Benchmark Programs</h2>
281 <p>
282 Some programs to estimate the speed of CPPLapack are prepared in "benchmark" directory.
283 </p>
284 
285 <p>
286 The performance of CPPLapack is almost the same as the performance of original BLAS and LAPACK.
287 However, some of arguments of BLAS and LAPACK functions such as ALPHA, BETA, TRANS, and so on are fixed at certain values.
288 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.
289 </p>
290 
291 <!---------------------------------------------------------------------------->
292 <!---------------------------------------------------------------------------->
293 <!---------------------------------------------------------------------------->
294 <hr>
295 <h2>FAQ</h2>
296 <p>
297 (Q)I found my program using CPPLapack consuming the memory larger and larger in a loop. Why does this happen?
298 <br>
299 (A)Most likely, you leave out some returned matrix or vector object in the loop.
300 Please read "Important Specification" section carefully.
301 </p>
302 
303 
304 <p>
305 (Q)When I print components of a matrix or vector, I sometimes see "nan" printed. What is the possible reason?
306 <br>
307 (A)First of all, please make sure that your objects are initialized.
308 The constructor with size arguments such as
309 <code>"CPPL::dgematrix A(5,10);"</code>
310 does NOT initialize its array components.
311 The "resize" function does NOT initialize, neither.
312 Please initialize objects using substitutions, or use "identity" or "zero" function to initialize them.
313 </p>
314 
315 <p>
316 (Q)All the member variables are in "public".
317 Why don't you set "private" for capsulation?
318 <br>
319 (A)Matrix programings are frequently required to be custom-made.
320 Choosing "public" or "private" was a tough choice, and we chose "public" so that users could make custom-made functions without modifying CPPLapack itself.
321 </p>
322 
323 <!---------------------------------------------------------------------------->
324 <!---------------------------------------------------------------------------->
325 <!---------------------------------------------------------------------------->
326 <hr>
327 <h2>License</h2>
328 CPPLapack is a GPL software without any guarantee.
329 
330 <!---------------------------------------------------------------------------->
331 <!---------------------------------------------------------------------------->
332 <!---------------------------------------------------------------------------->
333 <hr>
334 <h2>Author and Cooperators</h2>
335 Author: &nbsp;
336 Yuki ONISHI<br>
337 Cooperator: &nbsp;
338 Masafumi IAI, &nbsp;
339 Toshiyasu SHIMIZU, &nbsp;
340 Masashi UESHIMA
341 
342 <!---------------------------------------------------------------------------->
343 <!---------------------------------------------------------------------------->
344 <!---------------------------------------------------------------------------->
345 <hr>
346 <h2>Bug Report</h2>
347 Please send bug reports to
348 <a href="mailto:yuki.onishi@gmail.com">yuki.onishi@gmail.com</a>.
349 I also welcome any kind of comments.
350 
351 <!---------------------------------------------------------------------------->
352 <!---------------------------------------------------------------------------->
353 <!---------------------------------------------------------------------------->
354 <hr>
355 <h2>Links</h2>
356 CPPLapack Documents in Japanese:
357 <ul>
358 <li><a target="_blank" href="../main_page/Japanese.html">
359 CPPLapack Document in Japanese</a></li>
360 <li><a target="_blank" href="http://cpplapack.sourceforge.net/tutorial/japanese/index.html">
361 CPPLapack Tutorial in Japanese</a></li>
362 <li><a href="http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf">PDF of CPPLapack Tutorial in Japanese</a>
363 </ul>
364 
365 The sister project of CPPLapack:
366 <ul>
367 <li><a target="_blank" href="http://sourceforge.net/projects/cppscalapack/">
368 CPPScaLapack</a></li>
369 </ul>
370 
371 CPPLapack is based on and thanks to:
372 <ul>
373 <li><a target="_blank" href="http://netlib.caspur.it/blas/">
374 BLAS</a></li>
375 <li><a target="_blank" href="http://netlib.caspur.it/atlas/">
376 ATLAS</a></li>
377 <li><a target="_blank" href="http://www.netlib.org/lapack/">
378 LAPACK</a></li>
379 </ul>
380 
381 <ul>
382 <li><a target="_blank" href="http://developer.intel.com/software/products/compilers/">
383 Intel C++ Compiler (ICC)</a></li>
384 <li><a target="_blank" href="http://developer.intel.com/software/products/mkl/index.htm">
385 Intel Math Kernel Library (MKL)</a></li>
386 <li><a target="_blank" href="http://h30097.www3.hp.com/linux/compaq_cxx/">
387 HP(Compaq) C++ Compiler for Linux Alpha (CXX)</a></li>
388 <li><a target="_blank" href="http://h18000.www1.hp.com/math/">
389 HP(Compaq) Math Libraries (CPML, CXML)</a></li>
390 <li><a target="_blank" href="http://www.mpack.com/">
391 NEC MathKeisan Library (MPACK)</a></li>
392 <li><a target="_blank" href="http://www.sgi.com/developers/devtools/apis/scsl.html">
393 SGI Scientific Computing Software Library (SCSL)</a></li>
394 <li><a target="_blank" href="http://www.amd.com/home/dev01">
395 AMD Core Math Library (ACML)</a></li>
396 </ul>
397 <!---------------------------------------------------------------------------->
398 <!---------------------------------------------------------------------------->
399 <!---------------------------------------------------------------------------->
400 <center><h3>Have fun.</h3></center>
401 */