Essential Introduction(PDF 版)
NAG Library Manual, Mark 25

NAG Library

Essential Introduction

Note: 本ドキュメントは NAG Library のご利用を検討されている方々にとって必須の資料です.

目次

1  概要

2  ライブラリとドキュメント

2.1  ライブラリの構成

2.1.1  ライブラリルーチンの長い名前

2.2  ドキュメントの構成

2.3  ライブラリの実装

2.4  ライブラリの識別

2.5  Fortran 言語標準

3  ライブラリの使用

3.1  一般的なアドバイス

3.2  プログラミングに関するアドバイス

3.2.1  ルーチン名の代替

3.2.2  NAG Fortran 環境

3.2.3  ダイレクト/リバースコミュニケーションルーチン

3.3  エラー処理とパラメータ IFAIL

3.3.1  エラー,失敗,警告

3.3.2  IFAIL パラメータ

3.3.3  Hard Fail オプション

3.3.4  Soft Fail オプション

3.3.5  NAG エラーメッセージの構造

3.3.6  歴史的な経緯

3.4  ライブラリの入出力

3.5  外部手続きパラメータとしての補助ルーチン

3.6  動的メモリ割当て

3.7  ライセンス管理

3.8  予期しないエラー

3.9  スレッドセーフ

3.10  並列性

3.10.1  イントロダクション

3.10.2  NAG ライブラリはどのように並列化されているか?

3.11  他言語からのライブラリのコール

3.12  算術の考察と結果の再現性

3.13  ビット単位の再現性(Bit-wise Reproducibility (BWR))

3.13.1  ベンダーライブラリと条件付きビット単位の再現性(Conditional BWR (CBWR))

4  ドキュメントの使用

4.1  マニュアルの使用

4.2  ルーチンドキュメントの構成

4.3  パラメータの仕様

4.3.1  パラメータの分類

4.3.2  制約条件と推奨値

4.3.3  配列パラメータ

4.4  実装依存情報

4.5  Example プログラムと結果

5  サポート情報

6  NAG に関する背景情報

7  参考文献

1  概要

NAG Library(ライブラリ)の利用経験を問わず,以下の利用要領が推奨されます.

(a)  この Essential Introduction 全体を読む.
(b)  Keyword and GAMS Search を用いて,Chapter(チャプター)や Routine(ルーチン)を選択する.
(c)  関連する Chapter Introduction を読む.
(d)  ルーチンを選択し Routine Document(ルーチンドキュメント)を読む.ルーチンがニーズに合致しなかった場合にはステップ (c) に戻る.
(e)  ご利用のライブラリ製品のユーザーノートUsers' Note)を読む.
(f)  利用方法についてのローカルなドキュメント(サイトで用意されているもの等)があれば,それを読む.
(g)  該当ルーチンの Example プログラム(セクション 4.5 参照)を使用してみる.

この段階でユーザープログラムへのライブラリルーチンのコーディングは終わり,コンパイル,実行を試みる段階にきているはずです.もちろん問題が発生したり,結果に確信が持てなかったような場合には,再度関連するドキュメントを参照する必要があります.

ライブラリの利用経験に応じて (a) から (g) までのステップのいくつかはスキップできますが,次の点だけは忘れないでください.

2  ライブラリとドキュメント

2.1  ライブラリの構成

NAG Library(ライブラリ)は,数値計算や統計解析の分野の問題を解くための様々な Routine(ルーチン)の集合体です.

ライブラリは Chapter(チャプター)に区分されており,その各々は数値計算や統計解析の個別の分野に対応しています.各チャプターには 3 文字からなる名称とタイトルが付けられています.

チャプター H と S は例外で 1 文字の名称からなります.これらのチャプターの構成と名称は ACM 修正版 SHARE 分類インデックス(ACM (1960–1976) 参照)に基づいています.

ライブラリルーチンにはチャプターの名前から始まる 6 文字の名称が付けられています.

2 番目と 3 番目の文字は英字ではなく数字である点に注意してください(英字の O ではなく数字の 0 です).ルーチン名の末尾の文字はほとんどが‘F’として文書上に現れます.ただしチャプター D03 と E04 の中には末尾の文字が‘F’ではなく‘A’のルーチンが含まれています.‘A’ルーチンは常に‘F’ルーチンとペアになっています.‘A’ルーチンはマルチスレッド環境でも安全に使用できますが,その他の機能面では‘F’ルーチンと差はありません.

チャプター F06(線形代数サポートルーチン)には Basic Linear Algebra Subprograms, BLAS(Dongarra et al. (1988)Dongarra et al. (1990))が含まれています.その各々には NAG スタイルの名称の他に実際の BLAS 名も付けられています(例: F06PAF(DGEMV)).括弧内の名称は等価な倍精度 BLAS 名を意味しています.チャプター F16 には BLAS 技術フォーラム(The BLAS Technical Forum Standard (2001)Blackford et al. (2002))で指定されたルーチンのいくつかと標準にはない整数ベクトルのルーチンが含まれています.チャプター F16 のルーチンのいくつかは NAG スタイルの名称と BLAS 名の両方を持っています.チャプター F07(線形方程式(LAPACK))とチャプター F08(最小二乗/固有値問題(LAPACK))には LAPACK プロジェクトに由来するルーチンが含まれています(Anderson et al. (1999)).また,チャプター F01(行列の演算(逆行列を含む))には LAPACK プロジェクトに由来する格納形式変換ルーチンが含まれています.BLAS と同様,これらのルーチンには NAG スタイルの名称と共に LAPACK 名が付けられています(例: F07ADF(DGETRF)).これら別名に関する詳細については該当するチャプターのイントロダクション部(Chapter Introduction)に記述されています.

何社かのハードウェアベンダから提供されているマシン固有の BLAS,LAPACK ルーチンを利用できるようにするためには,プログラム中で NAG スタイルの名称(例えば F06PAF(DGEMV)や F07ADF(DGETRF)等)ではなく BLAS 名や LAPACK 名(例えば DGEMV や DGETRF 等)をなるべく使用するようにしてください.

2.1.1  ライブラリルーチンの長い名前

ライブラリルーチンは 6 文字から成る短い名前に加えて,nagf_ で始まり複数の単語を下線でつないだ長い名前を持っています.長い名前は各ルーチンがその関連性に伴いグループ化されるように命名されています.

各ルーチンの長い名前は各チャプターの Chapter Contents に記載されています.長い名前の二番目の単語は各チャプターに対応しており,例えば,チャプター D01(Quadrature(数値積分))のルーチンはすべて nagf_quad_ で始まる長い名前を持っています.

なお,長い名前の二番目の単語はチャプター毎に異なりますが,例外としてチャプター F07 と F08 は同じ単語(lapack)を共有しています.

BLAS/LAPACK ルーチンの長い名前(例えば nagf_blas_dgemm)は,ハードウェアベンダ提供のマシン固有の BLAS/LAPACK には使えません.セクション 2.1 でも述べたように,パフォーマンス面からは本来の BLAS/LAPACK 名(例えば DGEMM)の使用が推奨されます.

削除予定ルーチンの長い名前は三番目の単語が withdraw となっています.また,今後ライブラリのバージョンアップ(新しい Mark)で新たに削除予定となったルーチンは,長い名前の三番目に withdraw が挿入されることになります(元の長い名前は利用できなくなります).

ペアとなっている‘A’ルーチンと‘F’ルーチンの長い名前は同じです.ただし‘F’ルーチンの長い名前の末尾には old(‘F’ルーチンが‘A’ルーチンよりも古いことを示す)が追加されています.

これらの長い名前は NAG Library インターフェースブロック・モジュールの中で別名を付けること(エイリアシング)によって実装されています.従って,nag_library モジュールを USE することによって Fortran プログラムからこれらの長い名前が利用可能となります.

セクション 3.2.1 において,ルーチンの別名でのご利用やルーチン・インターフェースの単純化についてのアドバイスを得ることができます.

2.2  ドキュメントの構成

NAG Library Manual(マニュアル)は,ライブラリを使用する際に基本となるドキュメントです.それはライブラリと同一のチャプター構成を取っています.すなわち複数のライブラリルーチンから成る個々のチャプターにはマニュアルの同名のチャプターが対応しています.これらのチャプターはアルファベット順に並べられています.またマニュアルの先頭部にはライブラリの使用に際して基本となるドキュメント(Introduction)が配置されています.

それぞれのチャプターは次のドキュメントから構成されます.

ルーチンドキュメントの名称はルーチン名と同一です.チャプター内においてルーチンドキュメントは短い名前のアルファベット順に並んでいます.‘A’ルーチンを持つチャプターにおいては,‘A’ルーチンに関する記述はペアとなる‘F’ルーチンと共に一つのルーチンドキュメントに集約されています.

ドキュメントは次の形式で提供されます.

それぞれの閲覧方法,操作方法については Online Documentation をご参照ください.

ドキュメントの最新版には,NAG のウェブサイトからアクセスできます(セクション 5 参照).

2.3  ライブラリの実装

ライブラリは数多くのコンピュータシステムごとに用意されています.それぞれのシステムごとに異なる実装が NAG によって用意されます(例えば Linux 64(Intel® 64 / AMD64),GNU gfortran 実装など).個々の実装はコンパイル済み,動作確認済みのライブラリとしてサイトに配布されます.

実装は通常一連のマシン/OS(例えば x86-64 アーキテクチャー)に固有のものとなります.またさらに Fortran コンパイラ,コンパイラオプション(例えば,呼び出し規約など)ごとに固有のものとなることもあります.

ライブラリの実装ごとに提供される機能が異なるということはありませんが,演算機構やコンパイラの違いのために,ルーチンの実行結果がシステムによって異なったものとなる場合があります(特に数値計算の場合).

ドキュメントは少数の簡単な慣行を用いることによってすべての実装に共通したものとなっていますが,実装依存の情報がユーザーノートUsers' Note)という形で個別に提供されます(セクション 4.4 参照).

2.4  ライブラリの識別

定期的にライブラリの新たな Mark(バージョン)がリリースされます.具体的には新たなルーチンの追加,既存ルーチンの修正,改良,さらに改良版導入に伴うルーチンの削除といった内容が伴います.

ユーザーはライブラリのどの実装どの演算精度どの Mark とリビジョン を使用しているかを知っていなくてはなりません.これらの情報を確認するには,ライブラリルーチン A00AAF をコールするプログラムを実行します.

次に示すのはプログラムの一例です.

USE nag_library, ONLY: a00aaf
CALL a00aaf
END

これとは別に,実装と共に提供される nag_example スクリプトを使って A00AAF の Example プログラムを実行させることもできます(詳細はユーザーノートをご参照ください).

出力例は次のようになります.

*** Start of NAG Library implementation details ***

Implementation title: Linux, 64-bit, NAG Fortran (32-bit integers)
           Precision: FORTRAN double precision
        Product Code: FLL6A25D9L
                Mark: 25.0 (self-contained)

 *** End of NAG Library implementation details ***

2.5  Fortran 言語標準

すべてのライブラリルーチンは ISO Fortran 95 標準(ISO (1997))に準拠しています.

3  ライブラリの使用

3.1  一般的なアドバイス

NAG Library ルーチン(ライブラリルーチン)は,与えられたデータとは無関係に常に有意義な結果を返すことを保証するものではありません.次の点に関する注意配慮が必要です.

(a)  問題の定式化
(b)  ライブラリルーチンを使用したプログラミング
(c)  結果の評価

マニュアルの Foreword ドキュメントに (a)(c) に関するさらなる記述があります.セクション 3 の残りの部分では (b)(c) について解説します.

3.2  プログラミングに関するアドバイス

ライブラリとそのドキュメントはユーザーがルーチンをコールするプログラムを Fortran で書けることを前提に作成されています.(その他の言語からの利用に関してはセクション 3.11 をご参照ください.)

ライブラリルーチンのコールをプログラミングする場合にはルーチンドキュメント,特に Parameters(パラメータ)の記述部を注意して読んでください.この部分ではルーチンを呼び出した(entry)際,どのパラメータに値がセットされていなくてはならないか,復帰(exit)時にはどのパラメータに有用な情報が含まれているかについて明確に記述されています.さらなるガイダンスについてはセクション 4.3 をご参照ください.

ライブラリを使用する上で最も良く見られるプログラミングエラーのタイプは次の 2 つです.

nag_library モジュールはこれらのエラーを検知して防ぐために役立ちます.これを用いれば(USE すれば),不正なパラメータ型はコンパイル時に検知されるようになります.また,更に KIND=nag_wp を用いることで,実数と複素数の変数は精度の面でライブラリとの一貫性を保つことができます.

従ってライブラリルーチンのコールによってシステムからの(あるいはライブラリ内からの)予期せぬエラーメッセージが生じた場合には,次の点をチェックしてください.

ユーザー自身のプログラム単位や COMMON ブロックに対し NAG タイプの名称を使わないようにしてください.一般論として,3 文字からなる NAG のチャプター名を含む名称をそれらの中で使用しないでください.ライブラリで用いられている補助ルーチン名や COMMON ブロック名と競合する恐れがあります.

3.2.1  ルーチン名の代替

Fortran プログラムからライブラリルーチンを別の名前で利用することができます.これは,ライブラリルーチンを呼び出しているプログラムの頭の方で,‘USE nag_library’文を通して行うことができます.例えば,ライブラリルーチン名 S17AEF の代わりに‘BesselJ0’という名前を使いたい場合,以下の行を,

USE nag_library, ONLY: s17aef

次の行で置き換えます.

USE nag_library, ONLY: BesselJ0 => s17aef

これにより,‘BesselJ0’という名前でライブラリルーチン S17AEF を利用できるようになります.

ライブラリルーチンを他の環境から利用する場合にも,多くの環境がルーチン名に別名を付ける方法を提供しています.

複雑なインターフェースのライブラリルーチンをご利用の場合には,一部のパラメータだけを必要とし,その他のパラメータは値が常に一定である(または参照されない)ことが多いでしょう.そのような場合,ライブラリルーチンのラッパーを書くことで,より単純なインターフェース(および適当な代替名)でライブラリルーチンを利用することができます.例えば,求根と中間出力なしで硬い連立常微分方程式を解く場合,D02EJF の複雑なインターフェースに対して以下のようなラッパーを作成することができます.

SUBROUTINE BDFsolve(xend,y)
USE nag_library, ONLY: nag_wp, d02ejf, d02ejw, d02ejx, d02ejy
REAL(kind=nag_wp) :: xend, y(:)
REAL(kind=nag_wp) :: tol, xstart
INTEGER           :: ifail, iw, n
CHARACTER         :: relabs
REAL(kind=nag_wp), ALLOCATABLE :: w(:)

n = SIZE(y)
tol = 1.0e-3_nag_wp
relabs = 'M'
iw = (12+n)*n + 50
ALLOCATE(w(iw))
ifail = 0
xstart = 0.0_nag_wp
CALL d02ejf(xstart,xend,n,y,fcn,d02ejy,tol,relabs,d02ejx, &
            d02ejw,w,iw,ifail)
RETURN
END SUBROUTINE BDFsolve

そして,次のように単純なインターフェースでルーチンを呼び出すことができます.

CALL BDFsolve(xend,y)

3.2.2  NAG Fortran 環境

NAG ライブラリの環境は nag_library モジュールに定義されています.NAG 定義の定数(例えば nag_wp)を利用するためには,このモジュールを USE する必要があります.また,ライブラリルーチンのインターフェースブロックを利用するためにも,このモジュールを USE することが推奨されます.

nag_library.mod の格納場所はインストールに依存しています.詳細はご利用の製品のユーザーノートをご参照ください.

3.2.3  ダイレクト/リバースコミュニケーションルーチン

ユーザー提供の関数を必要とするライブラリルーチンは,ダイレクトコミュニケーションとリバースコミュニケーションのどちらかに分類されます.

ダイレクトコミュニケーションルーチンでは,ユーザー提供のサブルーチンを実引数として渡します.ユーザー提供のサブルーチンは,該当のルーチンドキュメントに記載される引用仕様に従って書かなくてはなりません.大抵の場合,ダイレクトコミュニケーションの方が簡単かつ便利です.しかし時に,この用法がネックになる場合があります.

  1. 決められたサブルーチンの仕様では,ライブラリルーチンと呼び出し元プログラム間で必要な情報をやり取りできない場合
  2. 他のコンピューター言語からダイレクトコミュニケーションルーチンを呼び出す際に,そのコンピューター言語がライブラリと完全に互換性のある形で手続引数をサポートしていない場合

これらの制限はリバースコミュニケーションルーチンを用いることで取り除かれます.リバースコミュニケーションルーチンは,1回の呼び出しで解を得るのではなく,解法プロセスを1ステップだけ実行し適切なフラグ(IREVCM)をセットして呼び出し元プログラムに戻ります. プロセスが終了したかどうか,もしくは新しい情報が必要かどうかは,IREVCM の値で判断します.後者の場合,リバースコミュニケーションルーチンを再度呼び出す前に,必要な情報を計算しなければなりません.要するに,解法プロセスの反復ループをユーザー側で行うことになります.一般的に,リバースコミュニケーションルーチンはダイレクトコミュニケーションルーチンよりも使用が複雑ですが,関数の評価に対してより大きな柔軟性を持ちます.

3.3  エラー処理とパラメータ IFAIL

3.3.1  エラー,失敗,警告

ここでは,ライブラリルーチンで検出可能なエラー,失敗,警告の条件が説明されます.これらは,ライブラリルーチンの作成者により予め想定済みの条件であって,コンパイラシステムにより検出される実行時エラー(例えば,オーバーフロー,初期化忘れ,等)とは別のものであることに注意してください.

以後,このドキュメント内で「エラー」という単語はルーチンが検出するエラー,失敗,警告のすべてを意味します.エラーは主に以下の 3 種類に分類されます.

  1. ルーチンが呼び出された時点で与えられた引数の値が範囲外の場合.これは計算を始める前に意味の無い値や利用可能で無い値が引数として与えられた場合のエラーです.
  2. 計算が行われている途中で求められる結果が得られないと判断された場合.例えば,逆行列を求める計算で行列が特異であると判断されたような場合です.
  3. 計算は終了したものの結果の信頼性が危ぶまれる場合.このような場合は警告が返されます.例えば,最適化ルーチンは局所的な最小値が求まった事を保証できない場合,警告を返します.

ライブラリはこれら 3 種類のエラーを同様に処理します.

各々のエラーにはエラー番号が対応しています.動的メモリ割当て(セクション 3.6 参照)とライセンスチェック(セクション 3.7 参照)に関するエラー番号は,全てのライブラリルーチンで共通しているため,個々のルーチンドキュメントには記載されていません.また,最近新たに追加されたルーチンでは予期しないエラーに対しても共通の番号を用います(セクション 3.8 参照).その他すべてのエラー番号は(エラーの説明と共に)ルーチンドキュメントのセクション 6(Error Indicators and Warnings)に列記されています.特に説明が無い限り,エラーチェックの順番はエラー番号の順番とは対応していません.(例えば,あるエラーが検出された場合に他のエラーのチェックが既に行われたかどうかは明らかではありません.)

3.3.2  IFAIL パラメータ

多くのライブラリルーチンは IFAIL と呼ばれるパラメータを持っています.この IFAIL パラメータはライブラリのエラー処理に関連するものです.(また,いくつかのルーチンでは,エラーメッセージと警告メッセージの出力のコントロールに関連します.)

IFAIL には以下の 2 つの目的があります.

  1. エラーが検出された際にライブラリルーチンがどのような動作を行うべきかの指定
  2. ルーチンを呼び出した結果(エラーが発生したかどうか)の報告

目的 (i) に関しては,ルーチンを呼び出す前に IFAIL に値を設定して行います.IFAIL は目的 (ii) に即して出力引数としても使われるため(定数表現では無く)変数として与えなくてはいけません.

IFAIL に設定する値は 0(Hard Fail オプション),1 または −1(Soft Fail オプション)のいずれかです.エラーが検出されなかった場合(計算が正常終了した場合)IFAIL は 0 を返し,呼出し元のプログラムは通常通り続行されます.エラーが検出された場合には,Hard Fail オプションか Soft Fail オプションかの指定によって異なる動作となります.ライブラリルーチンを呼び出す時に IFAIL に −1,0,1 以外の値を設定した場合,IFAIL にはデフォルト値 1 が用いられます.

3.3.3  Hard Fail オプション

ライブラリルーチンを呼び出す前に IFAIL を 0 に設定した場合,エラーが検出されるとプログラムは終了します.プログラムの終了前に以下のエラーメッセージが出力されます.

** ABNORMAL EXIT from NAG Library routine XXXXXX: IFAIL = n
** NAG hard failure - execution terminated

ここで XXXXXX はルーチン名で n がエラー番号です.エラー番号の説明は XXXXXX ルーチンドキュメントのセクション 6 に記載されています.

また,多くのルーチンでは上記のメッセージの直前に,より詳細なエラーメッセージが出力されます.

Hard Fail オプションは,ライブラリルーチンの呼び出しに失敗した(エラーが発生した)際に,プログラムを続行させたく無い場合に指定してください.エラーが発生しても,呼出し元のプログラムを続行させたい場合は,Hard Fail オプションを指定しないようにしてください.

3.3.4  Soft Fail オプション

ライブラリルーチンを呼び出す前に IFAIL を 1 または −1 に設定した場合,エラーが検出されると,IFAIL に適切なエラー番号が設定され,(計算はそれ以上行われずに)実行が呼出し元のプログラムに戻されます.なお,IFAIL に不正な値が設定された場合,IFAIL にはデフォルト値 1 が用いられることに注意してください.

IFAIL に 1 を指定した場合(silent exit),エラーメッセージは出力されません.

IFAIL に −1 を指定した場合(noisy exit),以下の様なエラーメッセージが出力された後に,実行が呼出し元のプログラムに戻されます.

** ABNORMAL EXIT from NAG Library routine XXXXXX: IFAIL = n
** NAG soft failure - control returned

ここで XXXXXX はルーチン名で n がエラー番号です.エラー番号の説明は XXXXXX ルーチンドキュメントのセクション 6 に記載されています.

また,多くのルーチンでは上記のメッセージの直前に,より詳細なエラーメッセージが出力されます.

Soft Fail オプションを指定した場合には,ルーチンからの復帰後に IFAIL の値をチェックすることが重要です.IFAIL が 0 以外の値であった場合は何らかのエラーを意味しますので,呼出し元のプログラムで適切な処理を行う必要があります.簡単な例で言えば,戻された IFAIL の値を(適切な説明と共に)出力してからプログラムを終了するといった処理です.ルーチンドキュメントのセクション 9 にある多くの Example プログラムには IFAIL に対するこの様な処理が含まれています.(ルーチンからのエラー復帰後に)より積極的に呼出し元のプログラムを続行したい場合には,実行を再開するのに相応しい箇所への分岐を持つようなプログラミングが基本となるでしょう.

Soft Fail オプションでは,ライブラリルーチンで検出されたエラーに対する処理はユーザー側に委ねられますので,適切に利用すれば,Hard Fail オプションに比べてより柔軟性の高いエラー処理が可能となります.特に以下の 2 つの場合にこの柔軟性が有用です.

  1. エラーや計算経過に関する追加情報が他のパラメータを通じて得られる場合
  2. いくつかのルーチンでは部分的な成功があり得ます.例えば,(すべての条件が満たされているわけではないが)有望な計算結果が得られた場合,ルーチンはその計算結果と共に警告を返します.このような場合,ルーチンドキュメントのセクション 6(及び,その他の部分)のアドバイスに基づき,ユーザーはこの計算結果(部分的な成功)をある目的では適切であると見なし利用する事ができます.

3.3.5  NAG エラーメッセージの構造

ルーチンドキュメントのエラーメッセージの説明に出てくる表記〈value 〉はプレースホルダです.エラーメッセージが実際に表示される時に,具体的な情報(変数値や引数名など)に置き換わります.

3.3.6  歴史的な経緯

上記で説明されたエラー処理機構は NAG Library, Mark 12 から導入されました.それ以前のバージョン(Mark)では IFAIL には 0 または 1 しか指定ができませんでした.上記で説明された新しいエラー処理機構は,Hard Fail オプション時に出力されるエラーメッセージの詳細が異なる点と IFAIL に −1(Soft Fail オプション,noisy exit)を指定できる点を除いて,古いエラー処理機構と互換性があります.

(主に Mark 7 および Mark 8 から導入された)いくつかのルーチンは IFAIL を特殊な方法で利用し,エラーメッセージと警告メッセージの出力方法の指定を行います(チャプター X04 参照).これらのルーチンでは IFAIL を十進整数として扱い最小桁の数字 ba が以下を表すようになっています.

a = 0: hard failure a = 1: soft failure
b = 0: silent exit b = 1: noisy exit

詳細は各ルーチンドキュメントに記載されています.

3.4  ライブラリの入出力

ほとんどのライブラリルーチンはエラーメッセージ出力を除き,外部ファイルへの出力は行いません.すべてのエラーメッセージは論理エラーメッセージ装置(logical error message unit)に対して出力されます.この装置番号(多くの実装においてはデフォルトで 6 にセットされます)はライブラリルーチン X04AAF をコールすることによって変更できます.

ある種のライブラリルーチンはオプションとして最終結果を,あるいは計算過程のモニタリングのために中間結果を出力することがあります.一般的にエラーメッセージ以外の出力は論理補助メッセージ装置(logical advisory message unit)に書き出されます.この装置番号(多くの実装においてはこれもデフォルトで 6 にセットされます)はライブラリルーチン X04ABF をコールすることによって変更できます.論理的にはエラーメッセージ装置とは異なるわけですが,実際問題としては両者の装置番号は同一のことが多いと言えます.チャプター E04 の少数のルーチンにはこの装置番号を直接指定できるオプションが用意されています.

ライブラリからのすべての出力は適切にフォーマットされています.

外部ファイルからの入力を行うライブラリルーチンはわずかしかありません.そのようなルーチンはチャプター E04,E05,H に存在します.外部ファイルに対する装置番号はルーチンへのパラメータで指定する形となっており,またすべての入力はフォーマットされているものとします.

関連する装置番号と所定の外部ファイルとのくくりつけは呼出し元のプログラム中における OPEN 文,または OS コマンドにより行われていなくてはなりません.

3.5  外部手続きパラメータとしての補助ルーチン

ドキュメント化され,ユーザーからコールされることを想定したこれらのライブラリルーチンに加え,ライブラリには数多くの補助ルーチン(auxiliary routines)が収納されています.

一般的にはこれらについて気にする必要はありませんが,ライブラリルーチンをコールする実行プログラムのメモリマップを調べたりするとその存在に気が付かれるかも知れません.唯一の例外はある種のライブラリルーチンをコールする場合に,これらの補助ルーチンの名前を外部手続きパラメータとして指定しなくてはならない,あるいは指定できるケースがあるということです.必要な詳細はルーチンドキュメントに記述されています.そのような場合に必要となるのはルーチン名のみです.(補助ルーチンの)パラメータリストの詳細について知っている必要はありません

NAG の補助ルーチンにはそれが関係するドキュメント化されたルーチンの名称に似た名前が付けられていますが,末尾の文字は‘Z’や‘Y’等となっています.例えば,

一部のチャプターに含まれる補助ルーチンの場合,その名称はチャプターの第 2,第 3 の文字に 50 を加えることで得られることがあります.例えばチャプター E04 に含まれる補助ルーチンの場合,E54NFU という名称を持っています.(E54NFU は,通常は E04NFA の QPHESS パラメータの実際の引数として使用されます.また,E04NFF で使用される同様の補助ルーチンの名称は E04NFU です.)

3.6  動的メモリ割当て

ライブラリルーチンの中にはインタフェースの簡略化のために動的にメモリを割当てるものがあります.可能な場合にはどれだけのメモリが確保されるか(通常はルーチンパラメータの関数式)がルーチンドキュメントに明記されています.ライブラリルーチンによって確保されたメモリはすべて復帰(exit)前に解放されます.

十分なメモリの動的割当てに失敗した場合には,ルーチンはエラー条件 IFAIL = −999 をセットすると同時にエラーメッセージを出力しリターンします.

3.7  ライセンス管理

ご使用の実装がライセンス管理されている場合,その運用の詳細情報はユーザーのローカルサイトに存在するはずです.サイト管理者にお尋ねください.お使いのマシン上で正当なライセンスが利用できるかどうかを確認するためには,ライブラリルーチン A00ACF に対する Example プログラムを実行してください.

ライブラリからライセンス管理ルーチンをコールした際,万一正しいライセンスが見つからなかった場合には,ルーチンはエラー条件 IFAIL = −399 をセットすると同時にエラーメッセージを出力しリターンします.その場合,Unix ベースのシステムでは,環境変数 NAG_KUSARI_FILE に適切なライセンスファイルまでのフルパスが正しく指定されているかどうかチェックしてください.また,ライセンスファイルの内容が適切かどうか(例えば,異なる製品のライセンスを使用してないかどうか)チェックしてください.すべての設定が正しいと思われる場合は,日本 NAG にお問い合わせください(セクション 5 参照).

3.8  予期しないエラー

万一予期しないエラーが起こった場合でも,ルーチンはエラー番号を IFAIL に設定し,適切なエラーメッセージを出力して終了します.基本的には IFAIL に設定される番号の意味はルーチン毎に異なり,予期しないエラーに対してもルーチン毎に異なる番号が設定されます.しかし,最近新たに追加されたルーチンでは,予期しないエラーに対して共通の番号 IFAIL = −99 を用いるよう標準化が行われています.

3.9  スレッドセーフ

可能な限り,ライブラリの実装はスレッドセーフです.すなわちマルチスレッドアプリケーションの中からもライブラリルーチンをコールできるわけです.マルチスレッド環境でのライブラリの使用に関する詳細なガイダンスについては Thread Safety ドキュメントをご参照ください.また,お使いの実装がスレッドセーフかどうかの詳細はユーザーノートをご参照ください.

ライブラリは実装によっては,例えば BLAS ルーチンを高速化するため等の理由により,ベンダライブラリとリンクされていることがあります.それらのベンダライブラリがスレッドセーフであることを NAG は保証できません.

3.10  並列性

3.10.1  イントロダクション

通常の並列化されていない(シリアル)NAG ライブラリの計算時間は,使用されるプロセッサの逐次処理性能に大きく左右されます.一方で,並列化された(マルチスレッド)NAG ライブラリは,計算タスクを複数のコアに分配し並列に処理するため,プロセッサの逐次処理性能を超えて計算を行うことができます.

従来,コンピュータシステムは少数のシングルコアプロセッサで構成されていました.そして,プロセッサの処理性能の向上はクロック周波数の増加によって行われてきました.しかし,このクロック周波数の増加が限界に達し,処理性能を向上させる別の方法が求められました.そこで登場したのがマルチコアプロセッサです.そして,それは今や至るところで使われています.マルチコアプロセッサは,単一のコアではなく,複数のコア(各コアは基本的には CPU と小さなキャシュから成る)で構成されています.従って,現今のハードウェアリソースを最大限に利用するためには,並列性を活用することが必須となっています.

並列化の有効性は,並列プログラムが同等の逐次プログラムに比べてどの程度速いかで評価できます.これは並列高速化(parallel speedup)と呼ばれます.逐次プログラムが並列化されたときの高速化は,同じ計算問題に対して,逐次プログラムの計算時間を並列プログラムの計算時間で割ることによって定義されます.もし,並列プログラムが n コアを使用した場合に,この高速化の値が n ならば(つまり,並列プログラムの計算時間が元の逐次プログラムの 1/n ならば),理想的な高速化が得られたことになります.使用するコア数の増加に対して,並列プログラムの高速化がこの理想的な値に近いならば,その並列プログラムはスケーラビリティ(scalability)が良いと言います.

以下の2つの要因のため,並列プログラムのスケーラビリティは理想的な値よりも小さくなります.

(a)  並列化に伴うオーバーヘッド
(b)  プログラムの並列化不可能な逐次部分

オーバーヘッドは並列化に必要なセットアップだけでなく通信と同期も含みます.このようなオーバーヘッドは,実装の効率と API の使用そして基礎となるハードウェアに依存して異なります.プログラムの並列化不可能な逐次部分の影響は,アムダールの法則(Amdahl's law)によって理論的に(つまり,オーバーヘッドがゼロである理想的なシステムを仮定して)説明されます.アムダールの法則は,逐次部分を持つ並列プログラムの高速化に上限を設けます.r をプログラムの並列部分の割合,s = 1 − r を逐次部分の割合とすると,n コアを使用した場合の高速化 Sn は次の条件を満たします.

S_n <= 1 / (s + (r / n))

例えば,4 分の 1 が逐次部分である並列プログラムの高速化は高々 4 となります.なぜなら,n → ∞,Sn ≤ 4 だからです.

並列化は共有メモリマシンと分散メモリマシンの二種類のシステムで利用でき,それぞれ異なるプログラミング技術を必要とします.分散メモリマシンは,ネットワークで繋がった複数のコンポーネントで構成されており,個々のコンポーネントがプロセッサとメモリ領域を持ちます.これらのコンポーネント間の通信と同期は明示的です.共有メモリマシンは,複数の(もしくは一つの)マルチコアプロセッサを持ち,これらが同じメモリ領域にアクセスします.そして,この共有メモリが通信と同期に使われます.マルチスレッド NAG ライブラリは OpenMP API を用いた共有メモリ並列化を利用します(セクション 3.10.2 参照).

OpenMP を用いた並列プログラムは,実行時に必要に応じて,単一のプロセスから複数のスレッドを生成します(fork).(なお,共有メモリ並列化を利用するプログラムのことをマルチスレッドプログラムと呼びます.)並列処理が一旦完了すると,スレッドは親プロセスに制御を戻し,次の並列処理領域まで非アクティブとなります(join).スレッドは同じメモリアドレス空間(例えば,親プロセスのメモリアドレス空間)を共有します.そして,この共有メモリが通信と同期に使われます.OpenMP はアクセス制御のメカニズムを提供します.各スレッドは共有変数にアクセスできるだけでなく,自分だけがアクセス可能な他の変数のプライベートコピーを持つことができます.特に,共有変数についてはスレッドの安全性が問題となります.結果に支障をきたすことなく複数のスレッドを用いて実行できるプログラムを「スレッドセーフ」と言います.並列領域でどれだけ多くのスレッドが使われても,スレッドセーフなプログラムは等しく正しい結果を返します.しかし,これは同一の結果が保証・期待できるという意味ではありません.並列プログラムでは,多くの場合,同一の結果を得ることは不可能です.なぜなら,使用するスレッド数が異なると,浮動小数点演算の順番が異なり(しかしどれも正しい),結果として丸め誤差の累積が変わるからです.結果の再現性についての更なる議論はセクション 3.12 をご参照ください.

3.10.2  NAG ライブラリはどのように並列化されているか?

マルチスレッド NAG ライブラリは,OpenMP API (Version 3.0) によるマルチスレッディングを利用しているという点でシリアル NAG ライブラリとは異なります.OpenMP API (Version 3.0) は,多くの異なるハードウェアプラットフォームの多くの異なるコンパイラで利用可能な共有メモリプログラミングについての移植性のある仕様です.

マルチスレッド NAG ライブラリの全てのルーチンが並列化されているわけではないのでご注意ください.各ルーチンの並列性とパフォーマンスについての詳細は,各ルーチンドキュメントのセクション 8 をご参照ください.

NAG ライブラリルーチンの呼び出しがマルチスレッディングの恩恵を受ける状況には以下の2つがあります:

NAG ライブラリルーチンの完全なリストならびにスレッド化の状況は Multithreaded Routines ドキュメントをご参照ください.

ライブラリの非効率な使用を避けるために,ライブラリの中で OpenMP がどのように利用されているかを知ることは有益です.

スレッド化された NAG 固有のルーチンは,実行中に OpenMP を用いて複数の並列処理領域でスレッドチームを生成します.スレッドチームは並列領域の開始時に分岐(fork)し,並列領域の終了時に合流(join)します.fork と join は両方とも呼び出されたルーチンの内部で起こります.(ただし,ユーザー提供のサブプログラムの中に親無し指示文(orphaned directive)があれば,そこでスレッドチームが利用されるという状況はあり得ます.詳細はルーチンドキュメントのセクション 8 をご参照ください.)NAG ルーチン内の OpenMP 指示構文は NAG コード内で生成されたスレッドチームと結合します(つまり,親無し指示文はありません).スレッド化された NAG 固有のルーチンでは,全てのスレッド管理が OpenMP ランタイムによって行われるため,NAG から特別なスレッド制御やオプションは提供されません.全ての OpenMP の環境変数とルーチン設定は,これらの NAG ルーチンとユーザープログラムの並列領域の両方に等しく適用されます.従って,ユーザープログラムの並列領域から NAG ルーチンを呼び出すときには注意が必要です.ネスト並列処理(nested parallelism)が有効になっている場合(デフォルトでは無効になっています),NAG ルーチンは各スレッドからの呼び出しに対してスレッドチームを fork および join します.これによりシステムリソースの競合が起き,パフォーマンスが著しく低下します.競合によるパフォーマンスの低下は,要求されたスレッド数がハードウェアのサポート数を超える場合や,ハードウェアリソースが他のプロセス(共有システムにおける他のユーザープロセス)の実行でビジーな場合にも起こります.このような理由から,ハードウェアがサポートできるスレッドの最大数とマシンにかかる作業負荷を考慮して,リソースの競合を最小にするスレッド数を選択する必要があります.スレッド数の設定についてのアドバイスは,ご利用の製品のユーザーノートをご参照ください.

他のスレッドメカニズムからマルチスレッド NAG ルーチンを呼び出す場合は,そのスレッドメカニズムが,ご利用のマルチスレッド NAG ライブラリをビルドする際に使用された OpenMP コンパイラランタイムと互換性があるか否かが問題となります.この件についてのアドバイスは,ご利用の製品のユーザーノートをご参照ください.

NAG ルーチンの多くは並列化の対象になっていませんが,これらの並列化されていない NAG ルーチンでも,並列化された NAG ルーチン,および/または,並列化されたベンダールーチン(例えば,BLAS と LAPACK)を内部的に呼び出して利用しているルーチンは間接的に並列化の恩恵を受けます.従って,ライブラリ全体に渡り多くの箇所で並列処理は行われます.マルチスレッディングによるパフォーマンスの向上は,呼び出すルーチンの種類,問題サイズとパラメータ,システム設計そして OS 構成に依って変わってきます.もし,同様のデータサイズとパラメータでルーチンを頻繁に呼び出すなら,最適なパフォーマンスを得るために異なるスレッド数を試してみることは価値があります.

一般的な指針として,以下の分野の主なルーチンは共有メモリ並列化の恩恵を受けます:

3.11  他言語からのライブラリのコール

一般的には NAG Library はデータタイプ間に適切なマッピングが存在する場合に,C や Visual Basic 等の他言語からもコールできます.

NAG はこれまでに各種 C ヘッダファイル(各種コンパイラに対して C と Fortran のデータタイプ間のマッチングを示すヘッダファイル),ドキュメント,Example を作成してきました.これらは NAG のウェブサイトに掲載されています(セクション 5 参照).

DLL(Dynamic Link Library)実装の場合には多くの言語環境(例えば Visual Basic,Visual Basic for Applications (Excel),Fortran,C,C++ 等)から容易にコールできます.そのためのガイダンスは NAG Library DLL のユーザーノート(Users' Note)に提供されます.詳細は NAG のウェブサイトをご参照ください(セクション 5 参照).

3.12  算術の考察と結果の再現性

NAG ライブラリルーチンから得られる結果は,問題の解決に使用されたアルゴリズムだけではなく,ライブラリをビルドする際に使用されたコンピュータやコンパイラの実行時ライブラリ,また実行に使われるマシンの算術特性にも依存します.

歴史的に,異なる種類のコンピューター・ハードウェアは異なる種類の算術システムを持つ傾向がありました.浮動小数点数の格納に,あるマシンでは基数 16 を使い,あるマシンでは基数 2 を使いました(基数が 8 や 10 といったマシンもありました).そのような違いはライブラリ・プロバイダにとって頭痛の種でした.ある算術システムで上手く動作したコードが別の算術システムでは同じように動作しないかもしれないからです.ライブラリ・コードをポータブルにするためには,たくさんの注意を払わなければなりませんでした.

加えて,マシンの算術がフローやエラーを起こすことがあり,掛け算や割り算などの基本的な演算が(特に非常に大きい数や非常に小さい数に対して)時おり間違った結果を与えることがありました.

浮動小数点数の算術に関する最初の IEEE 標準(ANSI/IEEE (1985))が 1980 年代に導入された後に,この状況は大きく改善されました.現在,主なハードウェア(NAG ライブラリが動作する殆どのハードウェア)は IEEE スタイルの基数 2 の算術を使っています.これによりポータブル・コードの製造がより簡単になりました.しかし,IEEE 標準には自由裁量の部分があるため,まだ問題は残されています.例えば,算術に 80-bit 内部レジスタ(元々は 1980 年代に Intel 8087 コプロセッサで導入された)を使うハードウェアは,特にコンパイラが算術の部分式を保持する最適化コードを生成する場合には,64-bit レジスタを使うハードウェアとは微妙に異なる動きをします.

コンピュータの算術は(IEEE 標準の算術がそうであるように)一般的に有限精度です.そのため,NAG ライブラリルーチンで実装されている数値計算法のほとんどの解は(単に丸め誤差の蓄積により)厳密解の近似ということになります.

従って,二つの異なるマシンで同じデータを用いてNAG ライブラリルーチンのプログラムを実行すると,コンパイラやハードウェア,また実行時ライブラリなどの違いによって結果が異なります.大抵この違いは小さく,例えば,二つの異なるマシンで良条件の連立一次方程式を解いた場合に,二つの計算結果が最後の数ビットだけ異なるといった具合です.しかし,時には小さな違いが重要視される場合があります.例えば,条件判断がその小さな違いに依存している場合などです.最適化問題のルーチンは常に同じ局所的最適解に収束するとは限りません(常に同じ局所的最適解が得られる場合は,その旨がルーチンドキュメントに注記されています).また,たとえ同じ局所的最適解に収束するとしても,反復回数は異なるかもしれません.

最新のハードウェアと最適化コンパイラは算術演算に更なる問題を喚起します.その一例がストリーミング SIMD 拡張(SSE)命令の利用にあります.

SSE 命令は浮動小数点数算術演算の低レベルの並列化を可能にします.例えば,128-bit SSE レジスタは二つの 64-bit 倍精度の数値(または四つの 32-bit 単精度の数値)を同時に保持し同時に演算することができます.大量のデータを扱っている場合,これは大きな時間の節約になります.

しかし,SSE 命令の効率的な使用はメモリ上のデータの並び方に依存します.メモリ間のデータの移動を行う SSE 命令は,データが 16 バイト境界に並んでいることを必要とします.もし NAG ルーチンが使用しているデータ(例えば,数値の配列へのポインタ)がたまたま上手く整列していない場合,それらの SSE 命令は使用できません.これに対して,最適化コンパイラは二つの命令ストリーム(データが上手く整列している場合とそうでない場合)を上手く生成します.

例えば,二つの N 次元ベクトル X と Y の内積を計算する場合を考えてみましょう.ベクトルの内積は,二つのベクトルの相対する成分の積を取り,個々の積を足し合わせることで得られます.良い最適化コンパイラでコンパイルされたルーチンは,二つ(または四つ)の数値を一度にロードします.そして,二つ(または四つ)の数値同士の積を一度に行って最終結果に加算します.

しかし,データがメモリ上に上手く整列していない状況では(これは良くあることなのですが),一度に一つの数値同士の演算しかできません(従って,最終結果を得るのにより長い時間がかかります).最適化コンパイラはこの状況に対応するコードパスも生成します.そして,実行時にコードは速いパスを取れるかどうかをチェックして適切に動作します.

問題は,加算の順序が変わると最終結果が変わるということです.これはコンピュータの算術が有限精度であるところから来る丸め誤差に由来します.以下の内積の代わりに,

s = x1 × y1 + x2 × y2 + x3 × y3 + ⋅⋅⋅ + xn × yn

次のような内積が行われるかもしれません.

s = (x1 × y1 + x3 × y3) + (x2 × y2 + x4 × y4) + ⋅⋅⋅

どちらの方法でも同じ結果が得られるように思えますが(ただし算術は有限精度であるため,どちらの結果も近似解でしかありません),二つの結果は微妙に異なります.もしこの小さな違いが呼び出し元のプログラムで異なる分岐をもたらすならば,呼び出し元のプログラムの動作に大きな違いを生じさせることになります.

更に,同じマシンで同じデータ用いて同じプログラムを連続で2回実行した場合でも,結果は異なる可能性があります.これは,プログラムがロードされた時に,たまたまデータが特定の境界に整列する場合もあれば,そうでない場合もあるからです.

より新しいハードウェアにおいては,AVX 命令が 256-bit レジスタを使用することにより,一度により多くの数値を演算することができます.AVX 命令に対して,データはメモリ上に 32 バイト幅で並んでいる必要があります.

NAG ライブラリルーチンによって使用されるデータは,NAG ライブラリの内部でメモリに割当てられます.NAG ライブラリルーチンは上述した計算結果の違いを最小にするために,自前のメモリ割当てルーチンを使うなどして,データが常に上手く整列するように配慮します.しかし,その配慮は部分的にコンパイラのサポートに依存しているため,常に有効とは限りません.

当然のことながら,ルーチンに渡される前のデータのメモリ割当てをライブラリルーチンはコントロールできません.もし容認できないような非決定論的な計算結果に遭遇し,それがメモリ上のデータの並び方に依るものではないかと疑われる場合は,データがメモリ上で上手く整列するように配慮することが望まれます.しかし,これをどのように行うかはご利用のシステムに依存した話となります.

マルチスレッド NAG ライブラリやマルチスレッドベンダーライブラリの並列性は,計算結果の非再現性のまた別の要因となります.ルーチンによっては,異なるコア数で実行した時に(または,同じコア数で同じ計算を繰り返した時でさえ)異なる結果を得ることがあるかもしれません.結果の再現性が重要な場合は,並列化されていないシリアル NAG ライブラリを利用するのが最良です.

3.13  ビット単位の再現性(Bit-wise Reproducibility (BWR))

固定長浮動小数点数(例えば,32-bit 単精度や 64-bit 倍精度など)の数学演算では,結合法則が常に満たされるとは限りません.つまり,コンピューターの計算では a + (b + c) と (a + b) + c の結果が異なる場合があるということです.例えば,IEEE 754 32-bit 浮動小数点数では,224 + (1 - 224) = 1 となる一方で (224 + 1) - 224 = 0 となります.これは,IEEE 754 32-bit 浮動小数点数の仮数が 23 ビットであるため,224 + 1 = 224 となるからです.BWR という用語は,コンピュータープログラム(例えば,一連のソースプログラム)が以下のような異なるコンピューター環境においてビット単位で正確に同じ答えを生成する場合を指します.

ユーザーはしばしば BWR を望みますが,しかし,これを達成することは極めて困難です.一般的に,次の条件を満たさなければなりません.

(a)  命令を常に正確に同じ順番で実行すること.
(b)  他のプロセッサでは利用できないかもしれない高度な CPU 機能(例えば,SSE3,SSE4,AVX)を使わないこと.
(c)  スレッド数を常に固定すること.

条件 (a) は,最適化なしで(または,非常に制限した最適化で)コンパイルを行うことを意味します.何故なら,一般的に,コンパイラのバージョンに依って最適化の方法が異なるからです.条件 (b) は,一般的に,最も普及している基本的な SSE 命令だけを利用し,新しいプロセッサの強化された SIMD 命令は利用しない,ということを意味します.

要するに,幅広いコンピューター環境で BWR を達成するためには,パフォーマンスを犠牲にする必要があるということです.

3.13.1  ベンダーライブラリと条件付きビット単位の再現性(Conditional BWR (CBWR))

NAG ライブラリの実装には,ベンダーライブラリ(特に,ベンダーライブラリの線形代数ルーチン)を利用するものがあります.ベンダーライブラリから得られる計算結果については,NAG ライブラリは BWR を直接制御することができません.

CBWR を導入した一部のベンダーライブラリでは,呼び出し元のコードが一定の条件を満たしていれば,環境変数を設定することによって BWR が有効になります.しかしながら,多くの NAG ルーチンは,ベンダーライブラリの CBWR が要求する条件を満たしていません.従って,ベンダーライブラリを利用するタイプの NAG ライブラリ実装では,異なる CPU アーキテクチャに渡って BWR を保証することはできません.

4  ドキュメントの使用

4.1  マニュアルの使用

NAG Library Manual(マニュアル)は NAG Library(ライブラリ)に対し次の役割を果たすべく作成されています.

マニュアルの先頭部(Introduction)には背景情報や追加情報に関する一般的な紹介資料が含まれています.

Mark 25 NAG Fortran Library News’というドキュメントは,新たに追加されたルーチン,削除予定のルーチン,当 Mark で削除されたルーチンの詳細を記述しています.

Advice on Replacement Calls for Withdrawn/Superseded Routines’(削除済みルーチンの代替についてのアドバイス)というドキュメントからはユーザープログラムの更新についてのアドバイスを得ることができます.

オンラインドキュメントでは Keyword and GAMS Search を用いて,キーワードでライブラリを検索することができます.

該当しそうなチャプターやルーチンが見つかったら,まず Chapter Introduction(チャプターイントロダクション)を読んでください.該当する数値計算分野に関する背景情報およびルーチン選択に関する推奨案(インデックス,テーブル,決定木を含む)が記述されています.

ルーチン選択が終わったら今度は Routine Document(ルーチンドキュメント)の参照が必要です.個々のルーチンドキュメントは本質的に自己完結型の資料です(関連ドキュメントへの参照は含まれますが).それには手法の説明,各パラメータの詳細仕様,個々のエラー復帰(exit)に関する説明,精度に関するコメント,および(ほとんどの場合)ルーチンの用法を示す Example プログラムが含まれています.

4.2  ルーチンドキュメントの構成

すべてのルーチンドキュメントは 10 のセクションからなる同一の構成を持っています.

1. Purpose(目的)
2. Specification(仕様)
3. Description(説明)
4. References(参考文献)
5. Parameters(パラメータ)(セクション 4.3 参照)
6. Error Indicators and Warnings(エラーと警告)
7. Accuracy(精度)
8. Parallelism and Performance(並列性とパフォーマンス)
9. Further Comments(コメント)
10. Example(使用例)(セクション 4.5 参照)

一部のドキュメント(主にチャプター E04,E05,H)においては更に 3 つのセクションが加わります.

11. Algorithmic Details(アルゴリズム詳細)
12. Optional Parameters(オプショナルパラメータ)
13. Description of Monitoring Information(監視情報)

この時,上記のセクション 11. と 13. は無い場合もあります.その場合 Optional Parameters(オプショナルパラメータ)がセクション 11. として登場します.

4.3  パラメータの仕様

各ルーチンドキュメントのセクション 5 にはパラメータの仕様がパラメータリストに現れる順に記述されています.

4.3.1  パラメータの分類

パラメータは次のように分類されます.

Input(入力):
ルーチンを実行する際にはこれらのパラメータに対し値を代入しておく必要があります.これらの値はルーチンから復帰(exit)した際も変化しません.

Output(出力):
ルーチンを実行する際にはこれらのパラメータに対し値を代入しておく必要はありません.ルーチンの中で値がセットされます.

Input/Output(入出力):
ルーチンを実行する際にこれらのパラメータに対し値を代入しておく必要がありますが,これらはルーチン中で値が変更されることがあります.

Workspace(ワークスペース):
ルーチン用作業エリアとして使用される配列パラメータ.正しい型と次元の配列をユーザーが用意する必要があります.ただし一般的に言うと,ユーザーはその内容に関知する必要はありません.

Communication Array(コミュニケーション配列):
一つのルーチンコールから別のものへデータを受け渡すために使用される配列パラメータ.

External Procedure(外部手続き):
ユーザーによって提供されなくてはならないルーチン(例えば,被積分関数の値を評価したり,中間結果を出力したりするためのもの).通常それは呼出し元のプログラムの一部として提供されなくてはなりません.ルーチンドキュメントにはこの外部手続きのパラメータリストと各パラメータの仕様の詳細が含まれることになります.そのパラメータはライブラリルーチンのパラメータと同様の形で分類されますが,ユーザーはそれをコールするのではなく自ら書く立場にあるため,分類の意味は異なってきます.

セクション 3.5 に記されているように,手続きはライブラリから提供される場合もあります.そのような場合には名称の指定だけで済みます.

User Workspace(ユーザーワークスペース):
ライブラリルーチンから外部手続きに引き渡される配列パラメータ.それらはルーチンによって使用されるものではなく,呼出し元のプログラムと外部手続きとの間での情報交換に使用されます.

Dummy(ダミー):
ルーチンでは使用されない通常変数.所定の変数または定数が提供されなくてはなりませんが,値の設定は必要ありません.(ダミーパラメータは多くの場合,旧バージョンでは必要だったものが互換性維持のために残されているパラメータです.)

4.3.2  制約条件と推奨値

入力パラメータの仕様中にある‘Constraint : ’または‘Constraints : ’(制約条件)という語は,そのパラメータに対する適正な値の範囲を規定します.

不正なパラメータ値を用いてコールされた場合(例えば N = 0),ルーチンは通常エラー復帰(exit)し,IFAIL として 0 以外の値を返します(セクション 3.3 参照).

タイプが CHARACTER のパラメータに対する制約条件としては大文字のアルファベットのみを記載しています.

しかし実際には CHARACTER パラメータを取るすべてのルーチンは小文字の使用を許しています.

Suggested value : ’(推奨値)という語は,ユーザーがどのような値にすべきかわからないケースを想定して,入力パラメータに対する妥当な設定値を示唆します(例えば精度や最大反復回数,等).個別の問題に対しそれらの値が適切ではないと判断される場合には異なる値を設定してください.

4.3.3  配列パラメータ

配列パラメータの多くは問題のサイズに依存した寸法を持っています.Fortran の用語で言うと,それらは‘整合寸法(adjustable dimensions)’を持っているということになります.配列の宣言文に記述される寸法は整数変数であり,それらもまたライブラリルーチンのパラメータです.

例えばライブラリルーチンの仕様が次のように与えられたとします.

SUBROUTINE <name> (M, N, A, B, LDB)
INTEGER            M, N, A(N), B(LDB,N), LDB

この例における A のような 1 次元配列の場合,その仕様は次のような記述で始まることになります.

この場合,呼出し元の(サブ)プログラム内で宣言される配列の寸法は少なくともパラメータ N に設定する値と同じ大きさでなくてはなりません.それより大きくても構いませんが,ルーチンが使用するのは最初の N 要素のみです.

上の例における B のような 2 次元配列の場合,その仕様は次のように与えられたとします.

一方,パラメータ LDB の仕様は次のように与えられたとします.

この場合,たとえルーチン内で実際に使用される行の数はパラメータ M によって決定されるとしても,配列 B の第 1 次元の寸法をパラメータ LDB でルーチンに与えなくてはなりません.またその寸法は少なくともパラメータ M に設定する値と同じ大きさでなくてはなりません.2 次元配列の部分配列にルーチンが作用できるように追加のパラメータ LDB が必要になります.配列の第 2 次元の寸法もまた,少なくともパラメータ N に設定する値と同じ大きさでなくてはなりません.それより大きくても構いませんが,ルーチンが使用するのは最初の N 列のみです.

上で示したルーチンをコールするプログラムのサンプルコードを次に示します.

INTEGER AA(100), BB(100,50)
LDB = 100
.
.
.
M = 80
N = 20
CALL <name>(M,N,AA,BB,LDB)
or
INTEGER ALLOCATABLE :: AA(:), BB(:,:)
INTEGER             :: M, N, LDB
.
.
.
READ(5,*) M, N
LDB = M
ALLOCATE (AA(M),BB(LDB,N))
CALL <name>(M,N,AA,BB,LDB)

多くの NAG ルーチンは,以下の様な‘大きさ引継ぎ(assumed size)’配列次元で宣言される配列パラメータを持っています.

INTEGER        A(*), B(LDB,*)

しかし呼出し元のプログラム中での配列宣言においては常にドキュメントに書かれている最小値以上の定数値を寸法として指定しなくてはなりません.配列に ALLOCATABLE 属性を付加すれば,コンパイル時には分からない配列の大きさを実行時に動的に割付けることができます.

配列パラメータを伴う NAG ルーチンのコールで問題が生じた場合には専門家に相談するか,または Fortran の書籍を調べてください.

4.4  実装依存情報

ライブラリのすべての実装に対応するために,マニュアルでは実装によって解釈が異なる項目を区別する意味で太字イタリック体を使用しています.

一つ重要なものは machine precision という表現で,これは実数の浮動小数点数が計算機内で格納されている相対精度を意味します.例えば 10 進で約 16 桁の実装であれば,machine precision は 10–16 に近い値を持ちます.

machine precision の正確な値はルーチン X02AJF を使って確認できます.チャプター X02 のその他のルーチンを使うと,オーバフロー用の閾値や表現可能な最大整数といった実装依存の定数値を求めることができます.詳細については X02 Chapter Introduction をご参照ください.

block size という表現はチャプター F07 と F08 の中でのみ使用されています.それはこれらのチャプターにおけるブロックアルゴリズムによって用いられているブロックサイズを表すものです.用意すべき作業エリアの量に影響が及ぶ場合にのみ,この値に留意する必要があります.関係するルーチンドキュメントとチャプターイントロダクションに記述されているパラメータ WORK と LWORK についてご参照ください.

ライブラリの各実装ごとに個別のユーザーノートUsers' Note)が発行されます.これは短いドキュメントで Mark ごとに改訂されます.ほとんどのインストレーションにおいては machine-readable な形式で利用できます.それは実装に固有の追加情報,特に次のような項目を含んでいます.

4.5  Example プログラムと結果

ルーチンドキュメントのセクション 10 に記述されている Example プログラムはルーチンのコールのしかたを例で示すものです.修正が容易な形で作られているので,ユーザープログラムを開発する際のテンプレートとしてご利用いただけます.

これらの Example プログラムはライブラリの実装ごとに machine-readable な形で配布されます.必要な修正は実施済みです.多くのサイトではこの形式でプログラムをユーザーに公開しています.実装固有の修正を加えていない一般形式のプログラムは NAG のウェブサイトから直接ダウンロードできます.ご利用の実装に対するユーザーノートUsers' Note)には Example プログラムに対して必要となる変更ついて記述されています.

Example プログラムの実行結果はすべての実装で同一になるとは限りません.また,マニュアルに記述されている結果とも一致しないことがあります.

多くのルーチンドキュメントでは,Example プログラムの実行結果に対してプロット図が提供されています.場合によっては,解のプロット図をより典型的なものとする為に,より大きな実行結果を生成するような(若干の)変更が Example プログラムに施されています.

5  サポート情報

製品のご利用に関してご質問等ございましたら,電子メールにて「日本 NAG ヘルプデスク」までお問い合わせください.
その際,ご利用の製品の製品コード(FLW6I25DCL など)とお客様の保守 ID をご明記いただきますようお願い致します.
ご返答は平日 9:30~12:00,13:00~17:30 に行わせていただきます.
何卒よろしくお願い致します.

日本 NAG ヘルプデスク

コンタクト先情報

日本ニューメリカルアルゴリズムズグループ株式会社
(略称:日本 NAG)

〒 104-0032
東京都中央区八丁堀 4-9-9 八丁堀フロンティアビル 2F

NAG のウェブサイトでは製品およびサービスに関する情報を定期的に更新しています.

6  NAG に関する背景情報

NAG Library の設計,開発に関する種々の見解,NAG の技術的方針と組織に関する情報については Ford (1982)Ford et al. (1979)Ford and Pool (1984)Hague et al. (1982) をご参照ください.

7  参考文献

ACM (1960–1976) Collected algorithms from ACM index by subject to algorithms

Al–Mohy A H and Higham N J (2011) Computing the action of the matrix exponential, with an application to exponential integrators SIAM J. Sci. Statist. Comput. 33(2) 488-511

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

ANSI (1966) USA standard Fortran Publication X3.9 American National Standards Institute

ANSI (1978) American National Standard Fortran Publication X3.9 American National Standards Institute

ANSI/IEEE (1985) IEEE standard for binary floating-point arithmetic Std 754-1985 IEEE, New York

ANSI/IEEE POSIX (1995) POSIX Standard Thread Library ANSI/IEEE POSIX 1003.1c:1995

Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001) Basic Linear Algebra Subprograms Technical (BLAST) Forum Standard University of Tennessee, Knoxville, Tennessee http://www.netlib.org/blas/blast-forum/blas-report.pdf

Blackford L S, Demmel J, Dongarra J J, Duff I S, Hammarling S, Henry G, Heroux M, Kaufman L, Lumsdaine A, Petitet A, Pozo R, Remington K and Whaley R C (2002) An updated set of Basic Linear Algebra Subprograms (BLAS) ACM Trans. Math. Software 28 135–151

Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A set of Level 3 basic linear algebra subprograms ACM Trans. Math. Software 16 1–28

Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An extended set of FORTRAN basic linear algebra subprograms ACM Trans. Math. Software 14 1–32

Ford B (1982) Transportable numerical software Lecture Notes in Computer Science 142 128–140 Springer–Verlag

Ford B, Bentley J, Du Croz J J and Hague S J (1979) The NAG Library‘machine’Softw. Pract. Exper. 9 (1) 65–72

Ford B and Pool J C T (1984) The evolving NAG Library service Sources and Development of Mathematical Software (ed W Cowell) 375–397 Prentice–Hall

Hague S J, Nugent S M and Ford B (1982) Computer-based documentation for the NAG Library Lecture Notes in Computer Science 142 91–127 Springer–Verlag

ISO (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)

ISO/IEC (1990) Information technology – programming language C Current C Language Standard ISO/IEC 9899:1990

Kernighan B W and Ritchie D M (1988) The C Programming Language (2nd Edition) Prentice–Hall

OpenMP The OpenMP Specification for Parallel Programming http://www.openmp.org

The BLAS Technical Forum Standard (2001) http://www.netlib.org/blas/blast-forum


Essential Introduction(PDF 版)
NAG Library Manual, Mark 25

© 日本ニューメリカルアルゴリズムズグループ株式会社 2015