MATLAB の MEX 関数におけるインターリーブされた複素数 API のサポート

複素数の行列をコンピューターのメモリで表現する際には、格納の場所と順序にいくつかの選択肢があります。MATLAB^® Version 9.4 (R2018a) 以前は、MATLAB は "実数/虚数分離型" 格納表現を使用していました。数値の実数部と虚数部は別々に格納されていました。MATLAB は、C および Fortran 言語の MEX ファイルに対して "インターリーブされた" 格納表現を使用するため、実数部と虚数部が一緒に格納されます。"インターリーブされた複素数" はこの表現のことをいいます。

多くの数学ライブラリがインターリーブされた複素数表現を使用しているため、MEX 関数で同じ表現を使用することでデータを変換する必要がなくなります。これによりコードが簡略化され、大規模なデータセットが関わる場合に処理が高速化する可能性があります。

この変更は MATLAB 言語には影響しません。関数やスクリプトを変更せずに複素数で説明されている機能の使用を継続できます。

実数/虚数分離型複素数 API とインターリーブされた複素数 API

C 行列 API とFortran 行列 APIには 2 つのバージョンがあります。

"実数/虚数分離型の複素数 API" には、MATLAB R2017b 以前の C および Fortran 行列 API の機能が含まれています。
"インターリーブされた複素数 API" には、MATLAB R2018a の時点での C 行列 API の機能と、MATLAB R2018a Update 3 の時点での Fortran 行列 API の機能が含まれています。

インターリーブされた複素数 API を使用して MEX ファイルをビルドするには、mex の "リリース固有ビルドオプション" -R2018a を使用します。実数/虚数分離型複素数 API を使用して MEX ファイルをビルドするには、-R2017b ビルドオプションを使用します。mex コマンドは既定で実数/虚数分離型複素数 API を使用します。ただし、MATLAB の将来のバージョンでは、mex はインターリーブされた複素数 API (-R2018a オプション) を既定で使用するため、ビルドコマンドの変更が必要になります。したがって、MATLAB のバージョンが変わっても確実に望ましい動作が得られるようにするために、既存のビルドスクリプトに -R2017b オプションを追加してください。両方の API をサポートするコードを記述するには、両方の複素数表現をサポートするために MX_HAS_INTERLEAVED_COMPLEX を追加を参照してください。

メモ

インターリーブされた複素数 API によってビルドされた Fortran MEX ファイルを R2018a で実行するには、R2018a Update 3 を使用しなければなりません。

インターリーブされた複素数をサポートするための行列 API の変更

C および Fortran 行列 API に対する次の変更は、インターリーブされた複素数をサポートします。

新しい型付きのデータアクセス関数。詳細については、C MEX ファイルでの型付きデータアクセスを参照してください。

MATLAB `mxArray` の型	C 型付きのデータアクセス関数	Fortran 型付きのデータアクセス関数
`mxDOUBLE_CLASS`	`mxGetDoubles` `mxSetDoubles` `mxGetComplexDoubles` `mxSetComplexDoubles`	`mxGetDoubles` `mxSetDoubles` `mxGetComplexDoubles` `mxSetComplexDoubles`
`mxSINGLE_CLASS`	`mxGetSingles` `mxSetSingles` `mxGetComplexSingles` `mxSetComplexSingles`	`mxGetSingles` `mxSetSingles` `mxGetComplexSingles` `mxSetComplexSingles`
`mxINT8_CLASS`	`mxGetInt8s` `mxSetInt8s` `mxGetComplexInt8s` `mxSetComplexInt8s`	`mxGetInt8s` `mxSetInt8s` `mxGetComplexInt8s` `mxSetComplexInt8s`
`mxUINT8_CLASS`	`mxGetUint8s` `mxSetUint8s` `mxGetComplexUint8s` `mxSetComplexUint8s`	`mxGetUint8s` `mxSetUint8s` `mxGetComplexUint8s` `mxSetComplexUint8s`
`mxINT16_CLASS`	`mxGetInt16s` `mxSetInt16s` `mxGetComplexInt16s` `mxSetComplexInt16s`	`mxGetInt16s` `mxSetInt16s` `mxGetComplexInt16s` `mxSetComplexInt16s`
`mxUINT16_CLASS`	`mxGetUint16s` `mxSetUint16s` `mxGetComplexUint16s` `mxSetComplexUint16s`	`mxGetUint16s` `mxSetUint16s` `mxGetComplexUint16s` `mxSetComplexUint16s`
`mxINT32_CLASS`	`mxGetInt32s` `mxSetInt32s` `mxGetComplexInt32s` `mxSetComplexInt32s`	`mxGetInt32s` `mxSetInt32s` `mxGetComplexInt32s` `mxSetComplexInt32s`
`mxUINT32_CLASS`	`mxGetUint32s` `mxSetUint32s` `mxGetComplexUint32s` `mxSetComplexUint32s`	`mxGetUint32s` `mxSetUint32s` `mxGetComplexUint32s` `mxSetComplexUint32s`
`mxINT64_CLASS`	`mxGetInt64s` `mxSetInt64s` `mxGetComplexInt64s` `mxSetComplexInt64s`	`mxGetInt64s` `mxSetInt64s` `mxGetComplexInt64s` `mxSetComplexInt64s`
`mxUINT64_CLASS`	`mxGetUint64s` `mxSetUint64s` `mxGetComplexUint64s` `mxSetComplexUint64s`	`mxGetUint64s` `mxSetUint64s` `mxGetComplexUint64s` `mxSetComplexUint64s`

-R2018a API に追加された行列 API 関数:
- mxMakeArrayComplex (C) および mxMakeArrayComplex (Fortran)
- mxMakeArrayReal (C) および mxMakeArrayReal (Fortran)
-R2018a API でサポートされない行列 API 関数:
- mxGetPi (C) および mxGetPi (Fortran)
- mxGetImagData (C) および mxGetImagData (Fortran)
- mxSetPi (C) および mxSetPi (Fortran)
- mxSetImagData (C) および mxSetImagData (Fortran)
次の行列 API 関数の動作は -R2018a API で変更されます。さらに、これらの関数は廃止予定です。
- mxGetPr (C) および mxGetPr (Fortran)
- mxSetPr (C) および mxSetPr (Fortran)
次の行列 API 関数の動作は -R2018a API で変更されます。
- mxGetData (C) および mxGetData (Fortran)
- mxSetData (C) および mxSetData (Fortran)
- mxGetElementSize (C) および mxGetElementSize (Fortran)
次の Fortran 行列 API 関数の動作は -R2018a API で変更されます。

インターリーブされた複素数 API を使用した MEX 関数の作成

インターリーブされた複素数 API を使用して MEX 関数を作成する方法については、C アプリケーションのC MEX ファイルでの複素数データの処理または複素数 Fortran データの処理を参照してください。

MATLAB R2017b 以前で作成された MEX 関数

MEX 関数、MEX S-Function、またはスタンドアロンの MATLAB エンジンおよび MAT ファイルアプリケーションを既にビルドしている場合、インターリーブされた複素数 API を使用するために MEX ファイルをアップグレードする必要があるかトピックを参照してください。MEX ファイルと S-Function をインターリーブされた複素数 API に移行する作業を支援するため、MATLAB には互換性インターフェイスがあります。互換性インターフェイスを使用して MEX ファイルをビルドするには、mex -R2017b フラグを使用します。コードで複素数を処理している場合、MATLAB がデータをインターリーブされた複素数形式に適応させるため、パフォーマンスへの影響が発生する場合があります。

mex コマンドは既定で -R2017b API を使用します。ただし、MATLAB の将来のバージョンでは、mex はインターリーブされた複素数 API -R2018a を既定で使用するため、ビルドコマンドの変更が必要になります。したがって、MATLAB のバージョンが変わっても確実に望ましい動作が得られるようにするために、ビルドスクリプトに互換性フラグ -R2017b を追加してください。