nAG C ライブラリ クイック イントロダクション
このドキュメントはnAG C ライブラリの構成や利用方法に関するクイック・イントロダクションです。 これからnAG C ライブラリを使うユーザや、nAG C ライブラリの構成や考え方についての理解を深めたい方々を対象にしています。本ドキュメントはライブラリのインストール手順や、ライセンスの設定手順に関する情報は含まれません。 これらについては各実装毎のインストールガイドをご参照下さい。
本ドキュメントは Essential Introduction に含まれる情報から特に重要と思われるものをまとめたものです。 詳細については Essential Introduction をご参照いただきますようお願い致します。
1 nAG C ライブラリの構成
nAG C ライブラリには1100種類以上の数値計算や統計解析の分野の問題を解くための様々な関数が含まれています。 これらの数多くの関数は個別の分野毎に約50の Chapter(チャプター)に区分されています。 そして各チャプターには同じ分野の複数の関数が含まれています。
以下にnAG C ライブラリの構成についての概念図を示します。
チャプターは(一部例外を除き)三文字からなる名称とタイトルが付けられています。
以下にいくかの例を示します。
Chapter d01 - Quadrature (数値積分) Chapter e04 - Minimizing or Maximizing a Function (関数の最小化・最大化) Chapter f12 - Large Scale Eigenproblems (大規模固有値問題) Chapter g03 - Multivariate Methods (多変量解析) Chapter g05 - Random Number Generators (乱数生成)
チャプター内の各関数にはチャプターの名称ではじまる6文字の名称が付けられています。
以下にいくかの例を示します。
d01ajc e04ccc f12abc g03aac g05sbc2番目と3番目の文字は英字ではなく数字である点に注意してください。 この関数名はショートネームと呼ばれます。 これに対し、それぞれの関数はより意味のある長い名称(ロングネームと呼ばれます)も持っています。
以下に上記のショートネームに対応するロングネームの例を示します。
nag_1d_quad_gen nag_opt_simplex nag_real_sparse_eigensystem_iter nag_mv_prin_comp nag_rand_beta関数を呼び出す場合、ショートネームとロングネームのどちらを用いても構いません。
2 ドキュメント
nAG C ライブラリを利用するにあたって以下のドキュメントが利用可能です。
- Essential Introduction
- ライブラリの概要や構成について書かれたドキュメントです。 nAG C ライブラリの利用開始前にお読み下さい。
- チャプター/関数一覧
- 約50のチャプターと1100種類の関数が含まれているリストです。
- Chapter Introduction
- 各チャプター毎に存在するドキュメントで、そのチャプターに含まれる関数の設計思想や、 関数選択の際の指針となる情報を与えてくれます。 ユーザは利用したい関数を含むチャプターのChapter Introductionを読むように強く推奨されています。
- 関数ドキュメント(マニュアル)
- 各関数毎に存在するドキュメントでアルゴリズム、引数の詳細、エラー情報、リファレンス情報などが含まれる他、 その関数を使ったExampleプログラム(及び与える入力データとそれによって得られる出力結果例)が含まれます。
- 実装毎の情報
- 実装毎の情報として、インストール手順を示す「インストールノート」とリンク方法や使い方を示す「ユーザノート」が存在します。
実装毎の個別情報は製品ダウンロードページからご参照下さい。
nAG C Libraryの実装一覧
3 nAG C ライブラリ利用手順
前述の通りnAG C ライブラリには多数の関数が含まれていますが、 ユーザはこの中から必要とする関数を見つけ出して使う必要があります。
以下に推奨されるご利用手順を示します。
- Essential Introductionを読む。(まずライブラリの概要を理解する上でお読みください)
- 求める関数が含まれていそうなチャプターを特定する。
- Chapter Introductionのアドバイスを基に関数を特定する。
- 関数ドキュメント(マニュアル)を読む。
- Exampleプログラムを動かしてみる。
3.1 目的の関数を探す推奨手順
以下に、上記推奨利用手順に基づきnAG C ライブラリに含まれる関数を利用する例を説明と共に示します。3.1.1 Essential Introductionを読む
Essential Introductionは本ドキュメントの基となるドキュメントで、 nAG C ライブラリを利用する前に読むことが強く推奨されているドキュメントです。以下のような内容がカバーされています。
1 概要 2 ライブラリとドキュメント 2.1 ライブラリの構成 2.2 ドキュメントの構成 2.3 ライブラリの実装 2.4 ライブラリの識別 2.5 C 言語標準 3 ライブラリの使用 3.1 一般的なアドバイス 3.2 プログラミングに関するアドバイス 3.2.1 nAG C 環境 3.2.1.1 nAG データ型 3.2.1.2 メモリ管理 3.2.1.3 Nag_Order 引数 3.2.1.4 配列参照 3.2.1.5 内部データ構造 3.2.1.6 チャプターヘッダファイル 3.3 ロングネームの使用 3.4 入出力 3.5 補助関数 3.6 エラー処理と fail 引数 3.6.1 nAGERR_DEFAULT の使用 3.6.2 fail 引数の使用 3.6.3 NagError 構造体 3.7 スレッドセーフ 3.8 多言語からの呼び出し 4 ドキュメントの使用 4.1 マニュアルの使用 4.2 関数ドキュメントの構成 4.3 引数の仕様 4.3.1 引数の分類 4.3.2 制約条件と推奨値 4.4 Example プログラムと結果 5 サポート情報 6 nAG に関する背景情報 7 参考文献
Essential Introductionは以下のリンクよりアクセス可能です。
http://www.nag-j.co.jp/naglib/cl/doc/man/essint.htm
3.1.2 チャプターを特定する
前述のとおりnAG C ライブラリは約50のチャプター(Chapter)に分けられています。
チャプター/関数一覧 からどのチャプターにユーザが求める関数があるかを特定し、 そのチャプターへのリンクをクリックします。
例えば偏微分方程式に関するものを探しているであればd03チャプター(偏微分方程式)が該当します。
以下にd03チャプターへのリンクを含むチャプター/関数一覧の参考図を示します。
3.1.3 Chapter Introductionを読んで関数を特定する
次にチャプター毎に用意されているChapter Introductionを読みます。 Chapter Introductionはチャプター/関数一覧の各チャプターの一番上のリンクから参照する事ができます。
以下にチャプター/関数一覧のd03チャプターの参考図を示します。
Chapter Introductionにはそのチャプターで扱われている計算に関しての背景情報が含まれるほか、 そのチャプターに含まれる関数の選択を助けるフローチャートやアドバイスを得ることができます。
以下は Chapter Introduction に含まれるフローチャートの例です。 提示されている質問にYes/Noで答えて行くことにより、適切な関数を教えてくれます。
最後にフローチャートからの情報等を考慮した上で、このチャプターの関数一覧から必要な関数を選択します。
3.1.4 関数ドキュメント(マニュアル)を見る
関数が特定できたら次に関数ドキュメント(マニュアル)を参照します。 関数ドキュメント(マニュアル)は関数名をクリックすることで参照できます。以下に参考図を示します。
関数ドキュメント(マニュアル)は以下のようのな情報が含まれます。
- 概要(Purpose)
- 関数仕様(Specification)
- アルゴリズムの説明(Description)
- リファレンス(References)
- 引数の説明(Arguments)
- エラーについて(Error Indicators and Warnings)
- 解の精度について(Accuracy)
- 実行時間等、その他情報(Further Comments)
- Exampleプログラムの説明(Example)
- プログラムコード(Program Text)
- 入力データ(Program Data)
- 実行結果例(Program Results)
以下に一例として d03ncc (nag_pde_bs_1d) の関数ドキュメント(マニュアル)の抜粋を示します。
3.2 目的の関数を見つけるその他の方法
目的の関数を見つけるためのその他方法として以下に幾つか述べます。3.2.1 キーワードから探す方法
その他にもキーワードから該当するnAG関数を探す事も可能です。
キーワードから該当関数を探す場合には下記のURLがご利用いただけます。
キーワードからnAG関数を探す :http://www.nag-j.co.jp/naglib/fl/kwic/kwic.html
但しキーワード検索は nAG C ライブラリの兄弟製品である nAG Fortran ライブラリのルーチンを探し出すのに有効です。 見つかったnAG Fortranライブラリルーチン名の末尾を F から C に置き換えて全て小文字にすることで、 同等機能を持つnAG Cライブラリ関数を見つけることが可能です。
例) 例えばD03NCFというnAG Fortranライブラリルーチンが見つかった場合には、 nAG Cライブラリでは同等機能を持つ d03ncc が利用可能であることがわかります。
以下に一例としてARIMAというキーワードを探す場合の手順を示します。
-
上記URLを開く
- A のリンクをクリックする
-
Aで始まるキーワードの一覧が表示されるので、ARIMA のリンクをクリックする
-
以上の操作でARIMAに関連する関数一覧が表示されます。
3.2.2 nAGに問い合わせる方法
もし上記の方法で見つからない、もしくはわからない場合には日本NAG株式会社まで お問い合わせ 下さい。
3.3 Exampleをプログラムを動かす
マニュアルを読み解くのみで、即プログラムを書くことは大変です。
nAG C ライブラリの関数のほぼすべてにExampleプログラムが提供されています。 利用可能な関数が見つかったらまずExampleプログラムを実行してみる事をお勧めします。
Exampleプログラムはマニュアルページにもその説明と記載がありますが、 以下に示すディレクトリにはExampleプログラムのソースファイル、 サンプルデータファイル、 及び結果ファイルが提供されていますのでご活用下さい。
Exampleプログラム(ソースファイル) [nAGインストール先]\examples\source\関数名e.c サンプルデータファイル [nAGインストール先]\examples\data\関数名e.d 出力結果例ファイル [nAGインストール先]\examples\results\関数名e.r※UNIX系の実装では上記の \ を / に読み替えて下さい。
以下に c02akc (nag_cubic_roots) のExampleプログラム、入力データ、及び出力結果例の格納場所の例を示します。
Windowsの場合の例: C:\Program Files\nAG\CL09\clw6i09dal\examples\source\c02akce.c C:\Program Files\nAG\CL09\clw6i09dal\examples\data\c02akce.d C:\Program Files\nAG\CL09\clw6i09dal\examples\results\c02akce.r Unix系の場合の例: /opt/nAG/cll6a09dgl/examples/source/c02akce.c /opt/nAG/cll6a09dgl/examples/data/c02akce.d /opt/nAG/cll6a09dgl/examples/results/c02akce.r
3.3.1 Exampleプログラム活用手順
Exampleプログラムのコンパイル、リンク、実行は以下の手順で行うことができます。[任意のフォルダ(ディレクトリ)にファイルをコピー]
まず、任意のフォルダ(ディレクトリ)を作成し、そのフォルダ(ディレクトリ)に Exampleプログラム、入力データをコピーします。 (関数によっては入力データを必要としないものも存在します。その場合は入力データのコピーは不要です。)
Windowsの場合の一例: cd 作成したフォルダ copy "C:\Program Files\nAG\CL09\clw6i09dal\examples\source\c02akce.c" copy "C:\Program Files\nAG\CL09\clw6i09dal\examples\data\c02akce.d" Unix系の場合の一例 cp /opt/nAG/cll6a09dgl/examples/source/c02akce.c . cp /opt/nAG/cll6a09dgl/examples/data/c02akce.d .
[コンパイル/リンクを行う]
次に、Exampleプログラムのコンパイル/リンクを行います。 (このステップはご利用のコンパイラやnAG C ライブラリの実装により、詳細が異なります。 nAG C ライブラリを利用するプログラムのコンパイル/リンク方法については、各実装にて提供される ユーザノートの「ライブラリへのアクセス」をご参照下さい。)
以下にコンパイル/リンクを行う際のコマンドの一例を示します。
Windowsの場合の一例: cl /MD /Fec02akce.exe c02akce.c CLW6I09DA_nag.lib Unix系の場合の一例 gcc c02akce.c -lnagc_nag -lpthread -lm -o c02akce.exe
[実行する]
出来上がった実行形式ファイルを通常の実行形式と同じように実行可能です。 入力データがある場合にはリダイレクションで標準入力から与えます。
以下に入力データがある場合のリダイレクションを用いた実行例を示します。
Windwosの場合: c02akce.exe < c02akce.d Unix系の場合: ./c02akce.exe < c02akce.d仮に入力データが必要ないExampleプログラムの場合には下記のようにリダイレクションなしで通常どおり実行します。
Windowsの場合: c02akce.exe Unix系の場合: ./c02akce.exe
Created: 2012/02/09 Last Updated: 2012/02/09