XLPack API の使用法

XLPack APIとは

XLPack API (C/C++インターフェース) はXLPackの数値計算モジュールをExcel以外のプログラムから使用するためのインターフェースです. これを使うと以下のことができます.

  • XLPack(あるいは XLPack Lite)が使用している数値計算モジュールをC/C++プログラムから呼び出すことができます
  • C/C++とインターフェースできるならばその他の言語からも呼び出すことができます. Python, Julia, C#, F#, VB.Net, DelphiについてはXLPack Lite用のインターフェースプログラムが提供されます
  • XLPack APIを使用して作成したプログラムはXLPack(あるいは XLPack Lite)をインストールしたパソコンで実行することができます

ご注意

XLPack APIはXLPackの内部インターフェースをありのまま公開するもので, すべての条件下でテストされたものではありません. 従って, これらの機能, 動作, 信頼性等を保証するものではありません. また, 予告なく仕様変更されることがあります.

ソフトウェアのダウンロード

XLPack SDK が ダウンロードページ より入手できます.

SDKにはプログラミング言語 C/C++, Python, Julia, .Net言語 (C#, F#, VB.Net), Delphi (Pascal) を対象としてAPIを使用するために必要なソフトウェアが入っています. SDKに含まれるインターフェースプログラムを使ってC/C++からXLPack/XLPack Lite, その他の言語からXLPack Liteを呼び出すことができます. XLPack Liteの全関数の使用例が添付されていますので, それを参考にすれば容易にプログラムを作成することができます.

リファレンスマニュアル

C/C++, Python, Juliaについては以下のリンクよりオンラインマニュアルを参照できます.

C/C++インターフェース

C/C++数値計算ライブラリ リファレンスマニュアル (別タブで開きます)
C/C++数値計算ライブラリ リファレンスマニュアル (XLPack Lite用) (別タブで開きます)

Python インターフェース

Python数値計算ライブラリ リファレンスマニュアル (XLPack Lite用) (別タブで開きます)

Julia インターフェース

Julia数値計算ライブラリ リファレンスマニュアル (XLPack Lite用) (別タブで開きます)

API の使用法

APIを使用するにはライブラリをリンクする方法とDLLを直接呼び出す方法の2種類があります.

ライブラリをリンクする方法

C/C++からはSDKに含まれるライブラリをリンクするだけで呼び出すことができます.

Windowsの場合には XLPack.lib (64ビット) または XLPack_32.lib (32ビット)をリンクします. Lite版の場合は XLPackLite.lib (64ビット) または XLPackLite_32.lib (32ビット)となります.

macOSの場合には XLPack.dylib と libXLPack.a の両方をリンクします. Lite版の場合は XLPackLite.dylib と libXLPackLite.a となります.

ヘッダーファイルは cnumlib.h または cnumlib (C++用) を使用します. Lite版の場合は cnumlib_lite.h または cnumlib_lite (C++用) となります.

注 – 5.3版より特殊関数の多くとBLAS 2, 3 関数ではエラー時にerrnoを設定するようにインターフェースが変更されています.

PythonについてはXLPack Liteを呼び出すために必要な拡張モジュールがSDKに含まれています.

Windows用は XLPackLite.pyd (64ビット版) または XLPackLite_32.pyd (32ビット版), macOS用は XLPackLite.so となります. これを使用するためには, 呼び出すスクリプトと同じディレクトリまたは環境変数PYTHONPATHで指定されたディレクトリに置いておきます. ソフトウェアのバージョンなどによっては拡張モジュールがうまく動作しないことがあります. その場合にはXLPackLite.py(拡張モジュールと同等の動作をするctypes版)を試してみてください.

Python拡張モジュールでは行列を表すのにNumpyのndarrayを使用しています. あらかじめNumpyをインストールしておく必要があります.

DLLを直接呼び出す方法

その他の言語ではライブラリをリンクせずDLLを直接呼び出します. その場合でも呼び出しインターフェースはライブラリをリンクする場合(リファレンスマニュアル)と下記の場合を除いて同じです. SDKには各言語用のDLLインターフェースプログラムが用意されていますので, DLLインターフェースの詳細を意識することなく呼び出すことができます.

DLL直接呼出しの場合, 特殊関数とBLAS2, 3 関数のように errnoをセットする関数はリファレンスマニュアルとインターフェースが異なります. 関数名の先頭にアンダーバー(_)を付け, 引数の最後にerrnoを付け加えたものになります. 例えば,

func(double a1, double a2)

の場合, 次のように変更になります.

_func(double a1, double a2, errno_t *xerrno)

xerrnoは正常終了時には0を返しますが, エラーがあればEDOMまたはERANGE(C言語のerrno.hの値)を返します.
BLAS 2, 3 関数については一般的な実装ではerrnoを設定しませんが, 拡張機能として引数にエラーがあった場合にEDOMを設定するようにしています.
対象になる関数は以下のとおりです.

errnoを設定する関数の一覧

特殊関数

factorial
ccbrt ccbrt_sub
laguerre alaguerre legendre legendred alegendre sharmonic sharmonic_sub
sharmonicr sharmonici hermite chebt chebtd chebu chebs
sqrt1pm1 powm1 sin_pi cos_pi cexpm1 cexpm1_sub clog1p clog1p_sub ccot ccot_sub
li ei e1 en spence
ci si chi shi
tgamma1pm1 lgammas rgamma tgammaratio tgammadratio cgamma cgamma_sub clgamma
clgamma_sub crgamma crgamma_sub poch poch1
beta lbeta cbeta cbeta_sub clbeta clbeta_sub
digamma trigamma polygamma cdigamma cdigamma_sub
gammai gammaic gammait gammap gammaq gammapi gammaqi gammapia gammaqia gammapd
betax betaxc ibeta ibetac ibetai ibetaci ibetaia ibetacia ibetaib ibetacib ibetad
zeta
erfi erfci dawson
besj0 besj1 besjn besy0 besy1 besyn besjnu besynu besjnd besjnud besynd besynud
sbesjn sbesyn sbesjnu sbesynu
besi0 besi0e besi1 besi1e besin besk0 besk0e besk1 besk1e beskn besinu besknu
besind besknd besinud besknud sbesin sbeskn sbesinu sbesknu
airyai airybi airyaid airybid
chu hyp1f1 lhyp1f1 hyp1f1r hyp2f1 hyp0f1 hyp1f0 hyp2f0
jelli jsn jcn jdn jns jnc jnd jsc jsd jdc jds jcs jcd
celli1 celli2 celli3 elli1 elli2 elli3 rc rd rg rf rj jzeta

BLAS 2

dgemv dgbmv dsymv dsbmv dspmv dtrmv dtbmv dtpmv dtrsv dtbsv dtpsv dger dsyr dspr
dsyr2 dspr2
zgemv zgbmv zhemv zhbmv zhpmv zsymv zsbmv zspmv ztrmv ztbmv ztpmv ztrsv ztbsv
ztpsv zgeru zgerc zher zhpr zsyr zspr zher2 zhpr2 zsyr2 zspr2

BLAS 3

dgemm dsymm dtrmm dtrsm dsyrk dsyr2k
zgemm zsymm zhemm ztrmm ztrsm zsyrk zherk zsyr2k zher2k

LAPACKE/CBLASの使用法

C/C++についてはXLPack API用のLAPACKE/CBLASライブラリが添付されています. Windowsの場合には Lapacke.lib (64ビット) または Lapacke_32.lib (32ビット)をリンクします. Lite版の場合は Lapacke_Lite.lib (64ビット) または Lapacke_Lite_32.lib (32ビット)となります. macOSの場合には libLapack.a または libLapacke_Lite.a (Lite版) となります.

ヘッダーファイルは lapacke.h および cblas.h を使用します. Lite版の場合は lapacke_lite.h となります.

これらのライブラリとヘッダーファイルを使用することによりLAPACKE/CBLASインターフェース(LAPACK/BLASに含まれる標準Cインターフェース)でLAPACK/BLASを呼び出すことができます. 各関数の使用法についてはオリジナルサイトを参照してください.
LAPACKEの説明
LAPACKマニュアル (LAPACKEおよびCBLASを含む)

XLPackに含まれているLapack/BLASの関数に対応する以下のLAPACKEおよびCBLAS関数が使用できます.

LAPACKE/CBLAS関数一覧
(*)はXLPack Liteで使用できるものを示します.

cblas_drotg cblas_drotmg cblas_drot cblas_drotm cblas_dswap cblas_dscal
cblas_dcopy cblas_daxpy cblas_ddot cblas_dsdot cblas_dnrm2 cblas_dasum
cblas_idamax
cblas_dgemv cblas_dgbmv cblas_dger cblas_dsbmv cblas_dspmv cblas_dspr
cblas_dspr2 cblas_dsymv cblas_dsyr cblas_dsyr2 cblas_dtbmv cblas_dtbsv
cblas_dtpmv cblas_dtpsv cblas_dtrmv cblas_dtrsv
cblas_dgemm cblas_dsymm cblas_dsyrk cblas_dsyr2k cblas_dtrmm cblas_dtrsm

cblas_zswap cblas_zscal cblas_zdscal cblas_zcopy cblas_zaxpy cblas_zdotu_sub
cblas_zdotc_sub cblas_dznrm2 cblas_dzasum cblas_izamax
cblas_zgemv cblas_zgbmv cblas_zhemv cblas_zhbmv cblas_zhpmv cblas_ztrmv
cblas_ztbmv cblas_ztpmv cblas_ztrsv cblas_ztbsv cblas_ztpsv cblas_zgeru
cblas_zgerc cblas_zher cblas_zher2 cblas_zhpr cblas_zhpr2
cblas_zgemm cblas_zsymm cblas_zhemm cblas_zherk cblas_zher2k cblas_ztrmm
cblas_ztrsm cblas_zsyrk cblas_zsyr2k

LAPACKE_ddisna LAPACKE_dgbcon LAPACKE_dgbsv LAPACKE_dgbsvx LAPACKE_dgbtrf
LAPACKE_dgbtrs LAPACKE_dgecon(*) LAPACKE_dgees LAPACKE_dgeesx LAPACKE_dgeev
LAPACKE_dgeevx LAPACKE_dgejsv LAPACKE_dgelqf LAPACKE_dgels(*) LAPACKE_dgelss
LAPACKE_dgelsy LAPACKE_dgeqp3 LAPACKE_dgeqrf LAPACKE_dgesv(*) LAPACKE_dgesvd
LAPACKE_dgesvdx LAPACKE_dgesvj LAPACKE_dgesvx LAPACKE_dgetrf LAPACKE_dgetri
LAPACKE_dgetrs LAPACKE_dgges LAPACKE_dggesx LAPACKE_dggev LAPACKE_dggevx
LAPACKE_dggglm LAPACKE_dgglse LAPACKE_dggsvd3 LAPACKE_dgtcon LAPACKE_dgtsv
LAPACKE_dgtsvx LAPACKE_dgttrf LAPACKE_dgttrs LAPACKE_dlamch(*) LAPACKE_dlange(*)
LAPACKE_dlansy(*) LAPACKE_dlantr LAPACKE_dorglq LAPACKE_dorgqr LAPACKE_dormlq
LAPACKE_dormqr LAPACKE_dpbcon LAPACKE_dpbsv LAPACKE_dpbsvx LAPACKE_dpbtrf
LAPACKE_dpbtrs LAPACKE_dpocon(*) LAPACKE_dposv(*) LAPACKE_dposvx LAPACKE_dpotrf
LAPACKE_dpotri LAPACKE_dpotrs LAPACKE_dppcon LAPACKE_dppsv LAPACKE_dppsvx
LAPACKE_dpptrf LAPACKE_dpptri LAPACKE_dpptrs LAPACKE_dptcon LAPACKE_dptsv
LAPACKE_dptsvx LAPACKE_dpttrf LAPACKE_dpttrs LAPACKE_dsbev LAPACKE_dsbevx
LAPACKE_dsbgv LAPACKE_dsbgvx LAPACKE_dsgesv LAPACKE_dspcon LAPACKE_dspev
LAPACKE_dspevx LAPACKE_dspgv LAPACKE_dspgvx LAPACKE_dsposv LAPACKE_dspsv
LAPACKE_dspsvx LAPACKE_dsptrf LAPACKE_dsptri LAPACKE_dsptrs LAPACKE_dstev
LAPACKE_dstevx LAPACKE_dsycon LAPACKE_dsyev(*) LAPACKE_dsyevx LAPACKE_dsygv
LAPACKE_dsygvx LAPACKE_dsysv LAPACKE_dsysvx LAPACKE_dsytrf LAPACKE_dsytri
LAPACKE_dsytrs LAPACKE_dtbcon LAPACKE_dtbtrs LAPACKE_dtpcon LAPACKE_dtptri
LAPACKE_dtptrs LAPACKE_dtrcon LAPACKE_dtrtri LAPACKE_dtrtrs LAPACKE_dtrttf
LAPACKE_dlatms

LAPACKE_slamch

LAPACKE_zcgesv LAPACKE_zcposv LAPACKE_zgbcon LAPACKE_zgbsv LAPACKE_zgbsvx
LAPACKE_zgbtrf LAPACKE_zgbtrs LAPACKE_zgecon LAPACKE_zgees LAPACKE_zgeesx
LAPACKE_zgeev LAPACKE_zgeevx LAPACKE_zgejsv LAPACKE_zgelqf LAPACKE_zgels
LAPACKE_zgelss LAPACKE_zgelsy LAPACKE_zgeqp3 LAPACKE_zgeqrf LAPACKE_zgesv
LAPACKE_zgesvd LAPACKE_zgesvdx LAPACKE_zgesvj LAPACKE_zgesvx LAPACKE_zgetrf
LAPACKE_zgetri LAPACKE_zgetrs LAPACKE_zgges LAPACKE_zggesx LAPACKE_zggev
LAPACKE_zggevx LAPACKE_zggglm LAPACKE_zgglse LAPACKE_zggsvd3 LAPACKE_zgtcon
LAPACKE_zgtsv LAPACKE_zgtsvx LAPACKE_zgttrf LAPACKE_zgttrs LAPACKE_zhbev
LAPACKE_zhbevx LAPACKE_zhbgv LAPACKE_zhbgvx LAPACKE_zhecon LAPACKE_zheev
LAPACKE_zheevx LAPACKE_zhegv LAPACKE_zhegvx LAPACKE_zhesv LAPACKE_zhesvx
LAPACKE_zhetrf LAPACKE_zhetri LAPACKE_zhetrs LAPACKE_zhpcon LAPACKE_zhpev
LAPACKE_zhpevx LAPACKE_zhpgv LAPACKE_zhpgvx LAPACKE_zhpsv LAPACKE_zhpsvx
LAPACKE_zhptrf LAPACKE_zhptri LAPACKE_zhptrs LAPACKE_zlange LAPACKE_zlanhe
LAPACKE_zlansy LAPACKE_zlantr LAPACKE_zpbcon LAPACKE_zpbsv LAPACKE_zpbsvx
LAPACKE_zpbtrf LAPACKE_zpbtrs LAPACKE_zpocon LAPACKE_zposv LAPACKE_zposvx
LAPACKE_zpotrf LAPACKE_zpotri LAPACKE_zpotrs LAPACKE_zppcon LAPACKE_zppsv
LAPACKE_zppsvx LAPACKE_zpptrf LAPACKE_zpptri LAPACKE_zpptrs LAPACKE_zptcon
LAPACKE_zptsv LAPACKE_zptsvx LAPACKE_zpttrf LAPACKE_zpttrs LAPACKE_zspcon
LAPACKE_zspsv LAPACKE_zspsvx LAPACKE_zsptrf LAPACKE_zsptri LAPACKE_zsptrs
LAPACKE_zsycon LAPACKE_zsyr LAPACKE_zsysv LAPACKE_zsysvx LAPACKE_zsytrf
LAPACKE_zsytri LAPACKE_zsytrs LAPACKE_ztbcon LAPACKE_ztbtrs LAPACKE_ztpcon
LAPACKE_ztptri LAPACKE_ztptrs LAPACKE_ztpttf LAPACKE_ztrcon LAPACKE_ztrtri
LAPACKE_ztrtrs LAPACKE_ztrttf LAPACKE_zunglq LAPACKE_zungqr LAPACKE_zunmlq
LAPACKE_zunmqr LAPACKE_zlatms

実行時エラーメッセージの出力に関してオリジナルと異なり一部のエラーについてLapacke/CBLASではなく元のLapack/BLASのエラーメッセージが出力されます. その場合, 引数の番号がLapacke/CBLASとは異なる場合があるので読み替えてください.

オリジナルのLAPACKEには含まれていない以下の関数を拡張機能として追加しています.

LAPACKE追加関数一覧
double LAPACKE_dlangb(int matrix_layout, char norm, lapack_int n, lapack_int kl, lapack_int ku, const double *ab, lapack_int ldab)
double LAPACKE_dlangt(char norm, lapack_int n, const double *dl, const double *d, const double *du)
double LAPACKE_dlansb(int matrix_layout, char norm, char uplo, lapack_int n, lapack_int k, const double *ab, lapack_int ldab)
double LAPACKE_dlansp(int matrix_layout, char norm, char uplo, lapack_int n, const double *ap)
double LAPACKE_dlanst(char norm, lapack_int n, const double *d, const double *e)
double LAPACKE_zlangb(int matrix_layout, char norm, lapack_int n, lapack_int kl, lapack_int ku, const lapack_complex_double *ab, lapack_int ldab)
double LAPACKE_zlangt(char norm, lapack_int n, const lapack_complex_double *dl, const lapack_complex_double *d, const lapack_complex_double *du)
double LAPACKE_zlanhb(int matrix_layout, char norm, char uplo, lapack_int n, lapack_int k, const lapack_complex_double *ab, lapack_int ldab)
double LAPACKE_zlanhp(int matrix_layout, char norm, char uplo, lapack_int n, const lapack_complex_double *ap)
double LAPACKE_zlanht(char norm, lapack_int n, const double *d, const lapack_complex_double *e)
double LAPACKE_zlansp(int matrix_layout, char norm, char uplo, lapack_int n, const lapack_complex_double *ap)

APIの使用例

以下, APIの使用例を示します.
ここでは次の2つの例題を使用してdgesvとqk15の使用法を説明します. その他の関数の使用例についてはSDKに入っているサンプルプログラムを参照ください.

例題(1)

連立一次方程式 Ax = B を解く. ただし, 係数行列A, 右辺行列B および 解x は次のとおり.

      (  0.2  -0.11 -0.93 )       ( -0.3727 )       ( 0.86 )
  A = ( -0.32  0.81  0.37 ),  B = (  0.4319 ),  x = ( 0.64 )
      ( -0.8  -0.92 -0.29 )       ( -1.4247 )       ( 0.51 )

例題(2)

次の定積分を求める. 厳密解は atan(4) = 1.32581766366803 である.

  ∫ 1/(1 + x^2) dx [0, 4]

引用ライブラリ

LAPACK: http://www.netlib.org/lapack/
SLATEC: http://www.netlib.org/slatec/
MINPACK: http://www.netlib.org/minpack/
Note – MINPACK software is included with some modifications under the MINPACK Software License
Acknowledgment – This product includes software developed by the University of Chicago, as Operator of Argonne National Laboratory

CMLIB: Center for Computing and Applied Mathematics, NIST
FFTPACK5: http://www2.cisl.ucar.edu/resources/legacy/fftpack5
Note – FFTPACK5 software is included with some modifications under the FFTPACK5 Software License
Mersenne Twister: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/mt.html
Boost: http://www.boost.org/
Cephes: http://www.netlib.org/cephes/
Fn: http://www.netlib.org/fn/

参考文献

D. Kahaner, C. Moler, S. Nash, “Numerical Methods and Software”, Prentice-Hall (1989)
森正武, 「FORTRAN77数値計算プログラミング」岩波書店 (1987)
D. E. Knuth, “The Art of Computer Programming Third Edition, Vol. 2 / Seminumerical Algorithms”, Addison Wesley Longman (1998)
E. Hairer, et al., “Solving Ordinary Differential Equations I”, Springer-Verlag (1993) (Note)
E. Hairer, et al., “Solving Ordinary Differential Equations II”, Springer-Verlag (1996) (Note)
Note – E. Hairer’s software is included with some modifications under Ernst Hairer’s License