C言語MEX-ファイルの作成(外部インタフェース/API)

外部インタフェース/API

LAPACKおよびBLAS関数の使用法

LAPACKは、MATLABが数値線形代数に対して利用する大規模のマルチオーサFortranサブルーチンライブラリです。BLASは、Basic Linear Algebra Subroutinesの略で、MATLABは行列の乗算およびLAPACKルーチン自身の高速化のために利用します。LAPACKおよびBLASが提供する関数は、C MEX-ファイル内部から直接呼び出すことも可能です。

本節では、LAPACKおよびBLAS関数を呼び出すMEX-ファイルの作成およびビルドの方法を説明します。以下に関する情報を提供します。

関数名の指定

CからFortranへ引数を渡す

複素数の扱い

MEX-ファイルの作成

LAPACKから関数を利用する対称不定分解に関する例題も提供します。

関数名の指定

LAPACKまたはBLAS関数の呼び出し時に、プラットフォームの中には呼び出しステートメント内の関数名の後にアンダーバーが必要なものがあります。

PC, IBM_RS, HPプラットフォームでは、後に続くアンダーバーを利用せずに、関数名のみを利用します。たとえば、LAPACKの関数dgemmを呼び出すには、つぎのようにします。

dgemm (arg1, arg2, ..., argn);

SGI, LINUX, Solaris, Alphaプラットフォームでは、関数名の後にアンダーバーを付け加えます。たとえば、これらのプラットフォーム上でdgemmを呼び出すには、つぎのようにします。

dgemm_ (arg1, arg2, ..., argn);

CからFortranへ引数を渡す

LAPACKおよびBLAS関数はFortranで書かれているため、これらの関数から、またこれらの関数へ渡される引数は、参照として渡される必要があります。つぎの例では、すべての引数を参照として渡すdgemmを呼び出します。アンパーサンド(&)は引数が既に参照であっても、引数の前に置きます。

#include "mex.h"

void mexFunction( int nlhs, mxArray *plhs[], int nrhs, mxArray 
*prhs[] )
{
double *A, *B, *C, one=1.0, zero=0.0;
int m,n,p; 
char *chn="N";

A = mxGetPr( prhs[0] );
B = mxGetPr( prhs[1] );
m = mxGetM( prhs[0] );
p = mxGetN( prhs[0] );
n = mxGetN( prhs[1] );

if ( p != mxGetM( prhs[1] ) ) {
mexErrMsgTxt("Inner dimensions of matrix multiply do not match");
}

plhs[0] = mxCreateDoubleMatrix( m, n, mxREAL );
C = mxGetPr( plhs[0] );

/* Pass all arguments to Fortran by reference */
dgemm (chn, chn, &m, &n, &p, &one, A, &m, B, &p, &zero, C, &m);
}

複素数の扱い

MATLABは、FORTRANと異なる方法で複素数を格納します。MATLABは、複素数の実部と虚部を別々に同じ長さのベクトルprとpiに格納します。FORTRANは、実部と虚部をインタリーブして1つの位置に同じ数値を格納します。

結果として、LAPACKおよびBLASでのMATLAB関数とFORTRAN関数間で交換された複素変数は、互換性がありません。MATLABは、この非互換性を解決するために複素数のストレージ形式を変更する変換ルーチンを提供します。

入力引数 FORTAN関数の入力引数として渡されるすべての複素変数に対して、MATLAB変数のストレージをFORTRAN関数と互換に変換する必要があります。そのために、関数mat2fortを使います。以下の例題を参照してください。

出力引数 FORTRAN関数の出力引数として渡されるすべての複素変数に対して、以下を行う必要があります。

複素変数用のストレージの割り当て時に、同じサイズのMATLAB変数用の2倍の容量を実数変数に割り当てます。返される変数が2倍の容量を必要とするFORTRAN形式を利用するために、これを行う必要があります。以下の例題のzoutの割り当てを参照してください。
変数がMATLABに返されると、MATLABと互換であるようにストレージを変換します。これを行うために関数fort2matを使ってください。

例題 - 複素変数を渡す 以下の例は、複素数のprhs[0]を入力として渡し、複素数のplhs[0]を出力として受け取るLAPACK関数をMATLABから呼び出す方法を示します。テンポラリ変数zinおよびzoutは、FORTRAN形式でprhs[0]およびplhs[0]を保持するために利用されます。

#include "mex.h" 
#include "fort.h"      /* defines mat2fort and fort2mat */

void mexFunction( int nlhs, mxArray *plhs[], int nrhs, mxArray 
*prhs[] ) 
{ 
int lda, n; 
double *zin, *zout;
lda = mxGetM( prhs[0] ); 
n = mxGetN( prhs[0] ); 

/* Convert input to FORTRAN format */
zin = mat2fort( prhs[0], lda, n );

/* Allocate a real, complex, lda-by-n variable to store output */
zout = (double *)mxCalloc( 2*lda*n );

/* Call complex LAPACK function */ 
zlapack_function( zin, &lda, &n, zout );

/* Convert output to MATLAB format */ 
plhs[0] = fort2mat( zout, lda, lda, n );

/* Free intermediate FORTRAN format arrays */ 
mxFree( zin );
mxFree( zout ); 
}

MEX-ファイルの作成

本節の例題では、C MEXファイル、myCmexFile.cをMATLABがサポートするプラットフォームでコンパイルおよびリンクする方法を説明しています。各例題で、<matlab>はMATLABルートディレクトリを意味します。

PCまたはIBM_RSプラットフォームでC MEX-ファイルをビルドする場合は、リンクするライブラリファイルを明示的に指定する必要があります。

PCでは、以下のいずれかを利用します。

mex myCmexFile.c <matlab>/extern/lib/win32/digital/df60/
libmwlapack.lib
mex myCmexFile.c <matlab>/extern/lib/win32/microsoft/msvc60/
libmwlapack.lib

IBM_RSでは、以下の用法を利用します。

mex myCmexFile.c -L<matlab>/bin/ibm_rs -lmwlapack

それ以外のすべてのプラットフォームでは、C MEX-ファイルをビルドするのと同様にMEX-ファイルをビルドすることができます。たとえば、以下のようにします。

mex myCmexFile.c

例題 - LAPACKを使った対称不定分解

ディレクトリ<matlab>/extern/examples/refbookには、2つのLAPACK関数を呼び出すC MEX-ファイルの例題があります。ここで、<matlab>は、MATLABルートディレクトリを意味します。このファイルには2つのバージョンがあります。

utdu_slv.c - 関数zhesvxおよびdsysvxを呼び出し、PC, HP, IBMプラットフォームで利用可能です。

utdu_slv_.c - 関数zhesvx_およびdsysvx_を呼び出し、SGI, LINUX, Solaris, Alphaプラットフォームで利用可能です。

出力ファイルは、同じディレクトリにあり、通常のMEX-ファイル拡張子をもつファイル名xc_utdu_slvです。

M-ファイルラッパーutdusolve.mは、ヘルプを提供し、以下を呼び出すことができます。

X = xc_utdu_slv(A,B);

メモリ管理 C 言語MEX-ファイルのデバッグ方法