XLPack API Manual

What is XLPack API

XLPack API (C/C++ interface) is the interface for other programs than Excel to use numerical calculation module of XLPack. With this interface you will be able to do the followings:

  • You can use the numerical calculation function module of XLPack (or XLPack Lite) from your C/C++ program
  • The other programming languages which have the interface to C/C++ can also be used. The XLPack Lite wrapper (interface) programs for Python, Julia, C#, F#, VB.Net and Delphi are provided
  • The program developed by using XLPack API can run on the personal computers in which XLPack (or XLPack Lite) is installed

Notes

XLPack API provides the internal interface in as-is condition. It has not been thoroughly tested under all conditions. Therefore, the function, performance, or reliability of this software are not guaranteed. And specifications are subject to change without notice.

Downloading software

XLPack SDK can be downloaded from Download Page.
SDK includes the necessary software to use API with programming languages C/C++, Python, Julia, .Net languages (C#, F#, VB.Net) and Delphi (Pascal). Using interface programs included in SDK, it is possible to call XLPack/XLPack Lite from C/C++ and to call XLPack Lite from other languages. Example programs to use all functions of XLPack Lite are included, so that you can easily develop the application programs by referring those examples.

Reference manuals

Please refer to the following online manuals for C/C++ and Python.

C/C++ interface

C/C++ numerical library reference manual (open in a separate tab)
C/C++ numerical library reference manual (XLPack Lite) (open in a separate tab)

Python interface

Python numerical library reference manual (XLPack Lite) (open in a separate tab)

Julia interface

Julia numerical library reference manual (XLPack Lite) (open in a separate tab)

Using API

There are two methods to use API. One is to link with the library. The other is to call DLL directly.

Linking library

C/C++ programs can call XLPack just by linking the following library included in SDK.

For Windows, link XLPack.lib (64 bit XLPack), XLPack_32.lib (32 bit XLPack), XLPackLite.lib (64 bit XLPack Lite) or XLPackLite_32.lib (32 bit XLPack Lite).

For macOS, link both XLPack.dylib and libXLPack.a (XLPack) or both XLPackLite.dylib and libXLPackLite.a (XLPack Lite).

Header files cnumlib.h or cnumlib (for C++) can be used for XLPack. cnumlib_lite.h or cnumlib_lite (C++) can be used for XLPack Lite.

Note – The interface have been changed from version 5.3 to set errno when error occurred for most of special functions and BLAS 2 and 3 functions.

The Python extension module which is used to call XLPack Lite is included in SDK.

For Windows, use XLPackLite.pyd (64 bit) or XLPackLite_32.pyd (32 bit). For macOS, use XLPackLite.so. These modules have to be placed in the same directory with calling script or the directory given by the variable PYTHONPATH. Depending on the software version and other environments, the extension module may not work. In such case, please try XLPackLite.py (ctypes version which provides equivalent functions with extension module).

Numpy ndarray is used in the Python extension module to handle matrices. Numpy must be installed in advance.

Calling DLL directly

Other languages do not link the library but call DLL directly. In that case, the calling interface is same with the case linking library (i.e. reference manual) except the special case below. However, DLL interface programs for each language are provided in SDK, so that it is possible to call XLPack without considering the details of DLL interface.

In the case of calling DLL directly, the calling interface of functions which may set errno such as special functions and BLAS 2 and 3 functions is different from the reference manual. Underbar (_) is added in front of the name of function and errno is added as the lase argument. For example,

func(double a1, double a2)

is changed as follows.

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

In the case of normal exit, 0 will be returned in xerrno. When error occurred, EDOM or ERANGE (the values of errno.h of C language) will be returned. In BLAS 2 and 3 functions, errno is not set in most implementation. However, as an extension, EDOM will be set if the argument error is found.
THe following functions may set errno.

List of functions which set errno

Special functions

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

How to use LAPACKE/CBLAS

LAPACKE/CBLAS library for XLPack API for C/C++ is included in SDK. For Windows, link Lapacke.lib (64 bit XLPack), Lapacke_32.lib (32 bit XLPack), Lapacke_Lite.lib (64 bit XLPack Lite) or Lapacke_Lite_32.lib (32 bit XLPack Lite). For macOS, link libLapack.a (XLPack) or libLapacke_Lite.a (XLPack Lite).

Header files lapacke.h and cblas.h can be used for XLPack. lapacke_lite.h can be used for XLPack Lite.

Using these libraries and header files, you can call LAPACK/BLAS through LAPACKE/CBLAS interface (standard C interface included in LAPACK/BLAS). For the details of how to use each function, please refer to the original site below:
Description of LAPACKE/CBLAS
LAPACK function reference manual including LAPACKE/CBLAS

LAPACKE and CBLAS routines corresponding to LAPACK and BLAS routines included in XLPack are supported.

List of supported LAPACKE/CBLAS functions
(*) shows the routines supported by 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

Different from the original version, error messages for some errors are output by the LAPACK/BLAS base routines instead of LAPACKE/CBLAS routines. In those cases, the displayed argument number may be different from LAPACKE/CBLAS. Please replace it as necessary.

The following functions which are not included in the original library are added as an extension.

LAPACKE additional functions
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)

Example programs using API

Example programs using API are described below.
The following two example problems are used to describe the usage of dgesv and qk15. For other functions, please refer to sample programs included in SDK.

Example (1)

Solve the system of linear equations Ax = B. Coefficient matrix A, right hand matrix B and solution x are as follows.

      (  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 )

Example (2)

Computes the following integral. The true analytic solution is atan(4) = 1.32581766366803.

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

Source libraries

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/

References

D. Kahaner, C. Moler, S. Nash, “Numerical Methods and Software”, Prentice-Hall (1989)
Masatake Mori “FORTRAN77 Numerical Calculation Programming (augmented edition)” Iwanami Shoten (1987) (Japanese book)
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