最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

エントリポイント関数の入力のプロパティの指定

入力プロパティを指定しなければならない理由

C および C++ は静的型付き言語であるため、MATLAB® Coder™ ではコンパイル時に MATLAB ファイル内の変数すべてのプロパティを決定しなければなりません。MATLAB ファイル内の変数のプロパティを推定するために、MATLAB Coder は、"基本" 関数 ("最上位" 関数または "エントリポイント" 関数としても知られる) への入力のプロパティを特定できなければなりません。そのため、基本関数に入力がある場合は、これらの入力のプロパティを MATLAB Coder に指定しなければなりません。基本関数が入力パラメーターをもたない場合は、MATLAB Coder では MATLAB ファイルを修正せずにコンパイルできます。基本関数から呼び出されるローカル関数または外部関数に対する入力のプロパティは指定する必要はありません。

チルダ (~) 文字を使用して未使用の関数入力を指定する場合は、以下を行います。

  • MATLAB Coder プロジェクトで、生成されるコードに異なる型を表示させる場合は、その型を指定します。それ以外の場合は、入力は既定で実数のスカラーの double になります。

  • codegen を使用してコードを生成する場合は、-args オプションを使用してこれらの入力の型を指定しなければなりません。

指定するプロパティ

基本関数が入力をもつ場合は、入力ごとに次のプロパティを指定しなければなりません。

対象指定するプロパティ
 クラスサイズ実数/複素数numerictypefimath
固定小数点入力

構造体の入力の各フィールド

 クラスに応じた各フィールドのプロパティの指定

その他の入力

  

既定のプロパティ値

MATLAB Coder では基本関数入力のプロパティに対して次の既定値が割り当てられます。

プロパティ既定値
クラスdouble
サイズscalar
実数/複素数real
numerictype既定値なし
fimathMATLAB 既定の fimath オブジェクト

構造体フィールドに対する既定値の指定-  ほとんどの場合、プロパティに対して明示的に値が指定されていないときは、MATLAB Coder では、構造体フィールドを除き、既定値が使用されます。構造体内のフィールドに名前を付けるには、そのプロパティの少なくとも 1 つを設定することが唯一の方法です。したがって、構造体フィールドのプロパティに対しては既定値を指定しなければならない場合があります。例については、スカラー構造体のクラスとサイズの指定構造体配列のクラスとサイズの指定を参照してください。

MEX 関数に対する既定の fimath 値の指定-  MATLAB Coder を使用して生成された MEX 関数は、実際にはコンパイル時に既定の fimath 値を使用します。既定の fimath 値を指定しない場合、MATLAB Coder は、MATLAB の既定の fimath を使用します。MATLAB 出荷時の既定のプロパティは以下のとおりです。

RoundingMethod: Nearest
OverflowAction: Saturate
ProductMode: FullPrecision
SumMode: FullPrecision
CastBeforeSum: true
詳細は、fimath による演算規則の共有 (Fixed-Point Designer)を参照してください。

既定の fimath 値に依存する MEX 関数を実行しているときは、MATLAB セッション中にこの値を変更しないでください。変更すると、コンパイル時と実行時の fimath の値が一致していないという警告を受け取ります。

たとえば、次の MATLAB 関数 test を定義するとします。

function y = test %#codegen
y = fi(0);

関数 test は、fimath オブジェクトを明示的に指定することなく fi オブジェクトを構築します。したがって、test は、実際にはコンパイル時に既定の fimath オブジェクトに依存することになります。MATLAB プロンプトで、MEX 関数 text_mex を生成して MATLAB の既定の fimath の工場出荷時の設定を使用します。

codegen test
% codegen generates a MEX function, test_mex, 
% in the current folder

次に、test_mex を実行して MATLAB の既定の fimath 値を表示します。

test_mex
 
ans =
 
     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

ここで、ローカルの MATLABfimath 値を作成します。これ以降は既定値は使用しません。

F = fimath('RoundingMethod','Floor');

最後に、メモリから MEX 関数をクリアして、再度実行します。

clear test_mex
test_mex

不一致が検出され、エラーが発生します。

??? This function was generated with a different default
fimath than the current default.

Error in ==> test_mex

サポートされているクラス

以下の表に MATLAB Coder でサポートされているクラス名を示します。

クラス名説明
logical真および偽の値の論理配列
char文字配列
int88 ビット符号付き整数配列
uint88 ビット符号なしの整数配列
int1616 ビット符号付き整数配列
uint1616 ビット符号なしの整数配列
int3232 ビット符号付き整数配列
uint3232 ビット符号なしの整数配列
int6464 ビット符号付き整数配列
uint6464 ビット符号なしの整数配列
single単精度浮動小数点または固定小数点の数値配列
double倍精度浮動小数点または固定小数点の数値配列
struct構造体配列
embedded.fi固定小数点の数値配列

基本入力のプロパティの指定規則

基本入力のプロパティを指定するときは次の規則に従います。

  • cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。

  • MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。

  • MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。

  • クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictypefimath プロパティを指定します。

  • クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

基本入力のプロパティの定義方法

方法利点短所

アプリを使用したエントリポイント関数の入力のプロパティの指定

  • MATLAB Coder プロジェクトで作業している場合は、使用が簡単。

  • 元の MATLAB コードを変更しない。

  • MATLAB Coder は、プロジェクト ファイル内に定義を保存する。

  • 大きな構造体や配列など、メモリを大量に使用する入力を指定する場合は効率的でない。

コマンド ラインでの例による入力プロパティの定義

メモ

MATLAB ファイルでプログラムによって入力プロパティを定義する場合は、この方法は使用できません。

  • 使いやすい。

  • 元の MATLAB コードを変更しない。

  • 少数の基本入力をもつ関数のプロトタイプを作成するために設計されている。

  • codegen を起動するたびにコマンド ラインで指定しなければならない (スクリプトを使用しない場合)。

  • 大きな構造体や配列など、メモリを大量に使用する入力を指定する場合は効率的でない。

MATLAB ファイル内でのプログラムによる入力プロパティの定義

  • MATLAB コードと統合されているため、MATLAB Coder を呼び出すたびにプロパティを再定義する必要がない。

  • MATLAB コード内にプロパティ指定のドキュメンテーションが提供されている。

  • 大きな構造体などメモリを大量に使用する入力を指定する場合に効率的である。

  • 複雑な構文を使用する。

  • MATLAB Coder プロジェクト ファイルは、現在、プログラムで定義されたプロパティを認識しない。プロジェクトを使用する場合は、入力の型をプロジェクトに再入力しなければならない。

コマンド ラインでの例による入力プロパティの定義

コマンド ライン オプション -args

関数 codegen には、基本 (エントリポイント) 関数の入力を、値または型の例の cell 配列で指定する -args コマンド ライン オプションがあります。cell 配列は、可変またはリテラル配列の一定値を使用できます。このオプションを使用することで、codegen を使用して MATLAB 関数のコードを生成すると同時に、入力のプロパティを指定します。

あるエントリポイント関数の出力の型を別の関数の入力として渡すことができます。入力としてのエントリポイント関数出力の受け渡しを参照してください。cell 配列入力の指定の詳細は、コマンド ラインでの cell 配列入力の指定を参照してください。

必要な型を使用してエントリポイント MATLAB 関数を呼び出すテスト関数またはスクリプトがある場合は、coder.getArgTypes を使用して、関数入力の型を決定できます。coder.getArgTypes は、coder.Type オブジェクトの cell 配列を返します。この cell 配列は -args オプションを使用して codegen に渡すことができます。codegen の詳細は、基本入力の一般的なプロパティの指定を参照してください。

-args オプションを使用する場合の規則

-args コマンド ライン オプションを使用して、例によってプロパティを定義するには次の規則に従います。

  • cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。

  • MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。

  • MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。

  • クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictypefimath プロパティを指定します。

  • クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

コマンド ラインでの例による基本入力のプロパティの指定

2 つの入力を追加する MATLAB 関数を考えてみます。

function y = mcf(u,v)
%#codegen
y = u + v;

次の例では、コマンド ラインで例によって基本入力 uv で異なるプロパティを指定する方法を示します。

  • 定数のリテラル cell 配列を使用して、両方の入力が実数スカラーの double であるように指定します。

    codegen mcf -args {0,0}

  • 定数のリテラル cell 配列を使用して、入力 u が符号なしの 16 ビットの 1 行 4 列のベクトル、入力 v がスカラーの double であるように指定します。

    codegen  mcf -args {zeros(1,4,'uint16'),0}

  • 同じ値を cell 配列変数に代入し、両方の入力が実数、符号なし 8 ビットの整数ベクトルであるように指定します。

    a = uint8([1;2;3;4])
    b = uint8([5;6;7;8])
    ex = {a,b}
    codegen mcf -args ex

コマンド ラインでの例による基本固定小数点入力のプロパティの指定

固定小数点 MATLAB コードの MEX 関数または C/C++ コードを生成するには、Fixed-Point Designer™ ソフトウェアをインストールしなければなりません。

固定小数点数の平方根を計算する MATLAB 関数を考えてみます。

%#codegen
function y = sqrtfi(x)
y = sqrt(x);

例によって基本固定小数点入力 x のプロパティを指定するには、以下の手順に従います。

  1. 次の例のように、xnumerictype プロパティを定義します。

    T = numerictype('WordLength',32,...
                    'FractionLength',23,...
                    'Signed',true);

  2. 次の例のように、xfimath プロパティを定義します。

    F = fimath('SumMode','SpecifyPrecision',...
               'SumWordLength',32,...
               'SumFractionLength',23,...
               'ProductMode','SpecifyPrecision',...
               'ProductWordLength',32,...
               'ProductFractionLength',23);
  3. 次の例のように、先ほど定義した numerictypefimath プロパティをもつ固定小数点変数を作成します。

    myeg = { fi(4.0,T,F) };

  4. 次の例のように、codegen コマンドを使用して、変数 myeg-args オプションの引数として渡して、関数 sqrtfi をコンパイルします。

    codegen sqrtfi -args myeg;

コマンド ラインでの定数入力の指定

基本入力が実行時に変化しないことがわかっている場合、基本入力を定数値として指定することで、生成されたコードのオーバーヘッドを削減できます。定数入力は、通常、アルゴリズムの実行方法を制御するフラグや、データのサイズや型を指定する値に使用されます。

入力に定数を指定するには、-args コマンド ライン オプションを coder.Constant オブジェクトと共に使用します。入力に constant_input のサイズ、クラス、実数/複素数および値をもつ定数を指定するには、以下の構文を使用します。

-args {coder.Constant(constant_input)}

定数入力をもつ関数の呼び出し

コード ジェネレーターでは、生成されるコードに関数への定数入力がコンパイルされます。生成された C または C++ コードでは、関数シグネチャに定数入力は含まれません。既定では、MEX 関数のシグネチャに定数入力を含めます。MEX 関数を呼び出す場合、コンパイル時の値と一致する値を指定しなければなりません。MEX 関数のシグネチャに定数入力が含まれているかどうかや、定数入力に指定する値を MEX 関数がチェックするかどうかを制御できます。MEX 関数での定数入力のチェックを参照してください。

定数入力として構造体を指定

次のように、MATLAB ワークスペースに構造体 tmp を定義することで行列の次元を指定するとします。

tmp = struct('rows', 2, 'cols', 3);

次の MATLAB 関数 rowcol は、構造体入力 p を受け取って行列 y を定義します。

function y = rowcol(u,p) %#codegen
y = zeros(p.rows,p.cols) + u;

次の例は、基本入力 u が double スカラー変数で、基本入力 p が定数構造体であることを指定する方法を示しています。

codegen rowcol -args {0,coder.Constant(tmp)}

コマンド ラインでの可変サイズ入力の指定

可変サイズ データは実行時にサイズが変わる可能性のあるデータです。MATLAB では、コード生成に対して制限付きと制限なしの可変サイズ データがサポートされています。"制限付き可変サイズ データ" には上限が設定されています。このデータはスタックで静的に割り当てることも、ヒープで動的に割り当てることもできます。"制限なしの可変サイズ データ" には上限が設定されていません。このデータはヒープで割り当てなければなりません。-args オプションと関数 coder.typeof を使用すると、入力が 1 つ以上の可変サイズの次元をもつように定義し、その上限を指定できます。

-args {coder.typeof(example_value, size_vector, variable_dims)}
可変サイズ入力を次のように指定します。

  • example_value と同じクラスと実数/複素数

  • size_vector と同じサイズと上限

  • variable_dims によって指定された可変次元

動的メモリ割り当てが有効な場合は、コンパイル時に、上限が不明な次元のサイズ ベクトルで Inf を指定できます。

variable_dims がスカラーの場合は、次の例外を除き、すべての次元に適用されます。

  • 次元が 1 または 0 の場合は、固定

  • 次元が制限なしの場合は、常に可変サイズ

詳細は、「coder.typeof」および可変サイズ データのためのコード生成を参照してください。

可変サイズ ベクトル入力の指定

  1. ベクトル A の各 n 要素の平均を計算し、ベクトル B に格納する関数を作成します。

    function B = nway(A,n) %#codegen
    % Compute average of every N elements of A and put them in B.
    
    coder.extrinsic('error');
    if ((mod(numel(A),n) == 0) && (n>=1 && n<=numel(A)))
        B = ones(1,numel(A)/n);
        k = 1;
        for i = 1 : numel(A)/n
             B(i) = mean(A(k + (0:n-1)));
             k = k + n;
        end
    else
        B = zeros(1,0);
        error('n <= 0 or does not divide number of elements evenly');
    end
    

  2. 最初の入力 A を double 値のベクトルとして指定します。最初の次元のサイズは固定ですが、2 番目の次元は上限 100 まで増やせます。2 番目の入力 n を double スカラーとして指定します。

    codegen -report nway -args {coder.typeof(0,[1 100],1),1} 
  3. また、この代わりに、coder.typeof の式を MATLAB 変数に代入し、この変数を -args に引数として渡すこともできます。

    vareg = coder.typeof(0,[1 100],1)
    codegen -report nway -args {vareg, 0}

関連するトピック