CPPLapackドキュメント日本語版

CPPLapackの正式なドキュメント(英語)はこちらで御覧下さい．

最新情報

[2015年05月11日] "cpplapack-2015.05.11"をリリースしました．このリリースはsvnの使用を好まないユーザに対するものです． tar.gz版，rpm版，deb版（alienで作成）も用意しました．今回のリリースは幾つかの大幅な変更がなされており，ユーザーは次の様なコードの修正が必要かも知れません．

BLAS/LAPACK関数はCPPL名前空間に入れられました． BLAS/LAPACK関数を直接コールする場合は"CPPL::"を関数名の頭に付けて下さい．
BLAS/LAPACK関数の引数スタイルをFORTRANスタイルに変更しました．配列変数だけでなく配列以外の変数もアドレス渡しとなります． BLAS/LAPACK関数を直接コールする場合は"&"を配列以外の変数名の頭に付けて下さい．
デフォルトの整数型が"long"から"CPPL_INT"に修正されました． "CPPL_INT"はIntel/MKLでは"MKL_INT"に，g++他では"int"になります．これまで用いていた"long"は使用不可となりますので注意してください．

【具体例】
旧コード：


   long NRHS(mat.n), LDA(n), *IPIV(new long[n]), LDB(mat.m), INFO(1);

   dgesv_(n, NRHS, array, LDA, IPIV, mat.array, LDB, INFO);

新コード：


     CPPL_INT NRHS(mat.n), LDA(n), *IPIV(new CPPL_INT[n]), LDB(mat.m), INFO(1);

     CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);

または


     int NRHS(mat.n), LDA(n), *IPIV(new int[n]), LDB(mat.m), INFO(1);

     CPPL::dgesv_(&n, &NRHS, array, &LDA, IPIV, mat.array, &LDB, &INFO);

（"CPPL_INT"の代わりに"int"を指定しても大抵のプラットフォームで正常に動きます．）

[2014年02月08日] "cpplapack-2014.02.08"をリリースしました．このリリースはsvnの使用を好まないユーザに対するものです． tar.gz版，rpm版，deb版（alienで作成）も用意しました． "ChangeLog"が知りたい場合はsvnのログをご覧ください．

[2010年03月27日] "cpplapack-2010.03.27"をリリースしました．このリリースはsvnの使用を好まないユーザに対するものです． tar.gz版の他に，rpm版とdeb版も用意しました． "ChangeLog"が知りたい場合はsvnのログをご覧ください．

[2005年03月25日] "cpplapack-2005_03_25"をリリースしました．このリリースには幾つかのバグフィックスと改良がなされています．詳しくは"ChangeLog"を御覧下さい．また，このリリースにはスパース行列クラス(dssmatrix, zssmatrix)のアルファ版も含まれています．これらクラスは未だ非常にバギーですが，これらのクラスを使わない限り問題は無いと思います．

[2004年10月15日] 上島君によるCPPLapackの日本語チュートリアルが出来ました．これからCPPLapackを使ってみようという方々，必見です． HTML版は http://cpplapack.sourceforge.net/tutorial/japanese/index.html から，PDF版は http://cpplapack.sourceforge.net/tutorial/japanese/CPPLapack_Tutorial-Japanese.pdf から御覧になれます．

[2004年4月24日] "cpplapack-2004_04_24"をリリースしました． OpenMPのマクロ (#pragma omp parallel for private(j,k)) を全ての３重forループに付け加えました．このドキュメントに検索機能を付けました．大文字小文字は区別されます．

[2004年4月1日] "cpplapack-2004_04_01"をリリースしました．倍精度複素数マトリックス，ベクトルクラス (zgematrix, zgbmatrix, zhematrix, zcovector, zrovector) が新たに追加されています．

CPPLapackとは？

CPPLapackは BLAS，LAPACK，および PARDISO の C++ クラスラッパーです．

Fortran BLAS，LAPACK，CBLAS，CLAPACKでは，インタフェースがユーザーフレンドリーでないため，LAPACK初心者に限らず，経験を積んだプログラマでも間違いを起こしやすくなっています．また，そのインタフェースの使いにくさから，BLASの関数は，"+"，"-"，"*"等の利用頻度の高い単純な演算にはあまり利用されていません．したがって，BLASやLAPACKに対するインタフェースをユーザーフレンドリーな形で提供するライブラリがあれば，プログラム開発期間と計算時間をともに最小化できることになります．しかし，この両方の点において十分満足できるものは，既存の行列計算ライブラリにはないようです．

CPPLapackのインタフェースは，普通の行列計算ライブラリと同じく，非常にユーザーフレンドリーになっています．たとえば，"A=B*C;"や"A.dgesv(y);"のような表記が使えます．それと同時に，CPPLapackでは，内部でBLASとLAPACKの関数を使って高速な行列計算を提供しています．

CPPLapackの利点としては，ユーザーフレンドリーなインタフェースや高速な行列計算だけではなく，無駄のないメモリ利用もあります．大規模な行列を扱う場合，行列オブジェクトのコピー回数はメモリ消費量と計算時間に大きく影響します．CPPLapackでは，コピー回数を必要最小限に抑えるために，"Smart Temporary"システムという機構を導入しています．"Smart Temporary"システムはCPPLapackの内部的な機構ですので，CPPLapackのユーザーはこれについて気にする必要はありません．（2003年リリースのバージョンでは，"to_return"システムを利用していましたが，2004年以降リリースのバージョンでは，その代わりに，禁止コードのない"Smart Temporary"システムを利用しています．双方のバージョンで互換性は完全に保たれています．）

CPPLapackは大規模行列の計算のためのライブラリです．したがって，大規模行列を扱わない場合には，他のライブラリを使うことをおすすめします．

本プログラムはベータ版ですので，まだバグが残っている可能性があります．また，BLASやLAPACKの関数の中にまだ未対応のものもあります．CPPLapackを利用する場合には，この点にお気をつけ下さい．CPPLapackの開発へのご協力は，もちろん歓迎いたします．

CPPLapackの特徴

ユーザーフレンドリーなインタフェース
BLAS，LAPACK，およびPARDISOを利用した高速行列計算
"Smart Temporary" システムを利用したオブジェクトコピー回数の最小化

高速化などのための仕組みはCPPLapack内部に隠されているため，CPPLapackを利用するプログラマが特殊なプログラミングをする必要は一切ありません．

配布元

CPPLapackの公式配布元はこちらです．リンク先のページの最新版svnコードを利用することを強くお奨めします．

インストール方法

CPPLapackはC++のヘッダファイル群ですので，「インストール」と呼ぶ程の作業は必要はありません．ダウンロードしたファイルをお好きな場所に展開し，Makefileのインクルードパスを適当に書き換えるだけです．インクルードしなければならないファイルは"cpplapack.h"だけです．

とはいうものの，CPPLapackを使うにはBLASとLAPACKがインストールされている必要があります．オリジナルのBLAS,LAPACKの他にも Intel math kernel library (MKL)など，ベンダーの提供するライブラリにBLASやLAPACKが含まれているものでも結構です．ただし，スパース行列に対してPARDISOを使うためにはIntel MKLが必須です．

お使いの環境に合わせてMakefileを書き換えて下さい．幾つかのプラットフォームでのMakefile例が[typical Makefiles]に用意されていますので参考にしてみて下さい．

プラットフォームによって，利用するBLASやLAPACKのライブラリは異なります． Makefileの例を[typical Makefiles]に用意してありますのでご覧下さい．

Cygwinユーザー向けに，ATLASとLAPACKのインストール手順の説明を用意しました． [How to install ATLAS and LAPACK on Cygwin]をご覧下さい．

重要な仕様

CPPLapackの名前空間は"CPPL"です．
アンダースコアのついたクラスをCPPLapackのユーザーが利用する必要はありませんので，利用しないで下さい．アンダースコアのついた行列クラスは，"Smart Temporary"クラスです． "Smart Temporary"システムの詳細は[Mechanism of Smart Temporary system]をご覧下さい．
マトリックス成分の番号は１ベースではなく０ベースです．すなわち，m x nマトリックスの場合，左上の成分は(0,0)，右下の成分は(m-1,n-1)といった具合になります．バンドマトリックスに関しては[illustration of band matrix]をご覧下さい．
マトリックスは列メジャー方式で蓄えられています．ほとんどのCおよびC++プログラマーは行メジャー方式を好みますが，CPPLapackはFortranで元々開発されていた経緯を持つBLASやLAPACKを用いる為，やむなく列メジャー方式を採用しているのです．
マトリックスの行数はm，列数はn，データ配列の先頭はarrayでそれぞれ参照することが出来ます．しかしこれらの値を代入演算子=で書き換えることは出来ません． m,nの変更はresize関数を，マトリックス成分の値の変更にはoperator()を用いて下さい．またマトリックス成分は"A.array[10]=3.14"の様にして書き換えることも可能となっているので注意して下さい．
LAPACKの関数に対応するCPPLapackのメンバ関数（たとえば，A.dgesv(y)）は，行列Aを上書きします． Aの元の値を保持したい場合は，LAPACKメンバ関数を呼び出す前に，Aのコピーを作っておいて下さい．
デバッグを容易にするために，"CPPL_VERBOSE"および"CPPL_DEBUG"マクロを用意してあります． "-DCPPL_VERBOSE"をコンパイルコマンドに指定すると，呼ばれた全ての関数が標準エラー出力に関数名を出力します． "-DCPPL_DEBUG"をコンパイルコマンドに指定すると，範囲検査(bounds checking)が有効になります．デバッグ作業の間は，このマクロを有効にし，その後，CPPLapackの最高性能を得るために，このマクロを無効にしてから再コンパイルして下さい．
関数が返すオブジェクトを放置しないように注意して下さい．計算したあとに返されるオブジェクトは，必ず何らかのオブジェクトに代入しなければなりません．たとえば，A+B;というコードはよくありません．また， "dcovector f(const dcovector& x){ return 2*x; }", f(x);なども同様です．これは，"Smart Temporary"システムの特性から起こる現象です．詳しくは，[Mechanism of Smart Temporary system]をご覧下さい．

テストプログラム

CPPLapackの動作を確認するためのテストプログラム群が"test"ディレクトリ以下に収められています．そこに置かれているプログラムはCPPLapackの使いかたを学ぶ為の良い易しいプログラム例にもなると思います．

ベンチマークプログラム

CPPLapackの速度を評価するためのベンチマークプログラム群が"benchmark"ディレクトリ以下に収められています．

CPPLapackのパフォーマンスはオリジナルのBLASやLAPACKと同等です．しかしながら，BLASやLAPACKで用いられるalpha,beta,Transposeといった引数をフルに用いたオリジナルのBLASやLAPACKのプログラムに比べると，シンプルな演算子だけを用いたCPPLapackのプログラムは遅くなってしまいます．どうしてもこれらの引数をフルに使いたい場合は，CPPLapackのプログラム内でオリジナルのBLASやLAPACKの関数を呼んで下さい．そうすれば，CPPLapackを用いつつオリジナルのBLASやLAPACKと同等のパフォーマンスが得られます．

よくある質問

(質問) CPPLapackのプログラム書いてみたところ，ループの中でメモリ使用量がどんどん膨らんで行くという現象が見られました．どうしてこんなことが起こるのでしょうか？
(回答) 恐らく，そのループの中でマトリックスやベクトルの返り値を放置してしまっていると思われます． "重要な仕様"の章を注意深く読んでみて下さい．

(質問) マトリックスやベクトルの中身を表示させると，おかしな数字や"nan"が表示されます．これは何故でしょうか？
(回答) まず，そのオブジェクトが初期化されているかどうかを確認して下さい． CPPLapackではサイズ指定のコンストラクター，例えば"CPPL::dgematrix A(5,10);"，はその成分を一切初期化しません． "resize"関数も同様で，初期化を行いません．代入によって値を設定するか，もしくは"identity"関数や"zero"関数を使って初期化作業を行って下さい．

ライセンス

CPPLapackはオープンソースでフリー，かつ無保証なソフトウェアです．

著者と協力者

著者：大西有希
協力者：居相政史，清水利恭，上島正史

バグレポート

バグレポートはyuki.onishi@gmail.comにお願いします．コメントも歓迎します．