S-Function とは

S-Function (システム関数) は、Simulink^® 環境の機能を拡張する強力なメカニズムを提供します。"S-Function" は MATLAB^®、C、C++ または Fortran で記述された Simulink ブロックをコンピューター言語で記述したものです。C、C++、および Fortran S-Function は、mex ユーティリティを使用して MEX ファイルとしてコンパイルされます (C MEX 関数のビルドを参照)。他の MEX ファイルと同様に、S-Function は、MATLAB 実行エンジンが自動的に読み込んで実行できる、動的にリンクされたサブルーチンです。

S-Function では、S-Function API と呼ばれる特殊な呼び出し構文を使用して Simulink エンジンと対話できます。この対話は、エンジンと組み込みの Simulink ブロックの間で行われる対話と非常によく似ています。

S-Function は一般的な形式に従っており、連続システム、離散システム、およびハイブリッドシステムに対応できます。一連の簡単な規則に従って S-Function でアルゴリズムを実装し、それを S-Function ブロックを使用して Simulink モデルに追加できます。S-Function を記述して、その名前を S-Function ブロック (User-Defined Functions ブロックライブラリで利用可能) に配置した後、マスクを使用してユーザーインターフェイスをカスタマイズできます (Author Block Masksを参照)。

Simulink Coder™ がある場合は、S-Function をモデル内で使用してコードを生成できます。Target Language Compiler (TLC) ファイルを記述して S-Function の生成コードをカスタマイズすることもできます。詳細については、S-Function とコード生成 (Simulink Coder)を参照してください。

S-Function の動作

S-Function では、初期化、更新、微分、出力、終了など、シミュレーションのさまざまな部分におけるブロックの動作を定義します。シミュレーションの各ステップで、シミュレーションエンジンにより、特定のタスクを実行するメソッドが呼び出されます。S-Function の基礎として、ブロックの入力、状態、および出力の間の数学的関係に関する基本的な知識が必要になります。S-Function の動作を理解するには、まず Simulink でモデルをシミュレートする数学的な動作、つまりシミュレーションの段階について理解する必要があります。詳細については、動的システムのシミュレーションの段階を参照してください。

Simulink ブロックの数学的な動作

Simulink ブロックは一連の入力、一連の状態、一連のパラメーター、および一連の出力で構成されます。ここで、出力はシミュレーション時間、入力、パラメーター、および状態の関数になります。

次の方程式は、入力、出力、パラメーター、状態、およびシミュレーション時間の間の数学的関係を表しています。

$\begin{array}{l} y = f_{0} (t, x, u) (Outputs) \\ \dot{x} = f_{d} (t, x, u) (Derivatives) \\ x_{d_{k + 1}} = f_{u} (t, x_{c}, x_{d_{k}}, u), (Update) \end{array}$

ここで $x = [x_{c}; x_{d}] .$

シミュレーションの段階

Simulink モデルの実行は段階ごとに進みます。"初期化" フェーズで、Simulink エンジンはライブラリブロックをモデルに組み込み、信号の幅、データ型、およびサンプル時間を伝播し、ブロックのパラメーターを評価してブロックの実行順序を決定し、メモリを割り当てます。その後、エンジンは "シミュレーションループ" に入ります。このループの 1 回の実行を "シミュレーションステップ" と呼びます。各シミュレーションステップで、エンジンはモデル内の各ブロックを初期化時に決定された順序で実行します。それぞれのブロックについて、エンジンは現在のサンプル時間に対するブロックの状態、微分、および出力を計算する関数を呼び出します。その後、シミュレーションループ全体がシミュレーションが完了するまで続行されます。

モデルの初期化 - モデルをシミュレーション用に準備します。この段階で、ブロックのパラメーターが評価されてブロックの実行順序が決定され、各演算用のメモリが割り当てられます。この段階の後、ブロックはシミュレーションループに進みます。

連続状態と時間の更新 - モデルに連続状態がある場合のみ行われます。mdlOutputs、mdlDerivatives、mdlZeroCrossing などのマイナーステップのメソッドを変更して出力を計算できます。

S-Function コールバックメソッド

S-Function は、シミュレーションの各段階で必要なタスクを実行する一連の "S-Function コールバックメソッド" で構成されます。モデルのシミュレーション時、シミュレーションの各段階において、Simulink エンジンはモデル内の各 S-Function ブロックに対する適切なメソッドを呼び出します。S-Function コールバックメソッドで実行されるタスクには次が含まれます。

コンパイル — この段階で、Simulink エンジンは S-Function を初期化します。次のタスクが含まれます。
- ライブラリブロックをモデルに組み込み、信号の幅、データ型、およびサンプル時間を伝播する
- 入力端子と出力端子の数および次元を設定する
- ブロックのパラメーターを評価してブロックの実行順序を決定する
- メモリとストレージ領域を割り当てる
出力の計算 — この状態で、ブロックのすべての出力端子が現在のタイムステップに対して有効になるまで、つまりすべての出力値が特定の誤差範囲になるまで出力が計算されます。
離散状態の更新 — この呼び出しで、ブロックはタイムステップごとに 1 回実行される離散状態の更新などのアクティビティを実行します。
初期化メソッドと終了メソッド — これらのオプションのメソッドは、S-Function で 1 回だけ必要な初期化と終了のアクティビティを実行します。初期化のアクティビティには、ユーザーデータの設定や S-Function での状態ベクトルの初期化が含まれる場合があります。終了メソッドは、メモリの解放など、シミュレーションを終了するときや S-Function ブロックをモデルから削除するときに必要なアクションを実行します。
積分 — これは、連続状態やサンプリングされていないゼロクロッシングがあるモデルに適用されます。S-Function に連続状態がある場合、エンジンは S-Function の出力と微分の部分をマイナータイムステップで呼び出します。これは、S-Function の状態をソルバーで計算できるようにするためです。S-Function にサンプリングされていないゼロクロッシングがある場合も、エンジンはゼロクロッシングを特定できるように S-Function の出力とゼロクロッシングの部分をマイナータイムステップで呼び出します。

特に S-Function のシミュレーションで使用される用語については、S-Function Conceptsを参照してください。

C MEX S-Function をモデルに組み込むには、S-function ブロックを [Simulink ライブラリブラウザー] からドラッグします。同様に、Level-2 MATLAB S-function をモデルに組み込むには、Level-2 MATLAB S-function ブロックをモデルにドラッグします。
[ブロックパラメーター] ダイアログを開き、[S-Function 名] フィールドで S-Function の名前を指定して S-function ブロックの機能を提供します。たとえば、入力信号を 2 倍にする C MEX S-Function を追加するには、「timestwo」と入力して [適用] をクリックします。

メモ

S-Function ブロックが参照する同じ名前の C MEX ファイルと MATLAB ファイルが MATLAB パスに含まれている場合、S-Function ブロックでは C MEX ファイルが使用されます。

S-Function へのパラメーターの受け渡し

S-function ブロックと Level-2 MATLAB S-Function のどちらについても、対応する S-Function に渡すパラメーターの値を [ブロックパラメーター] ウィンドウで指定できます。それらのフィールドを使用するには、S-Function に必要なパラメーターとそれらが関数で必要になる順序を知っていなければなりません。(わからない場合は、S-Function の作成者に問い合わせるか、ドキュメンテーションまたはソースコードを確認してください。)パラメーターをコンマで区切り、S-Function に必要な順序で入力します。パラメーターの値は、定数、MATLAB ワークスペースまたはモデルワークスペースで定義されている変数の名前、あるいは MATLAB 式にすることができます。

次の例は、Level-2 MATLAB S-Function について、[パラメーター] フィールドを使用してユーザー定義のパラメーターを入力する例を示しています。

この例のモデル msfcndemo_limintm では、サンプルの S-Function msfcn_limintm.m を組み込みます。

S-Function msfcn_limintm.m は、下限、上限、初期条件の 3 つのパラメーターを受け入れます。この S-Function は、入力信号の時間積分が下限と上限の間にある場合は時間積分、時間積分が下限を下回る場合は下限、時間積分が上限を上回る場合は上限を出力します。この例のダイアログボックスでは、下限、上限、初期条件がそれぞれ -5.0、5.0、0 と指定されています。スコープに示されている出力は、入力が振幅 5 の正弦波の場合の結果です。

S-Function でユーザー指定のパラメーターにアクセスする方法の詳細については、Processing S-Function ParametersおよびHandle Errors in S-Functionsを参照してください。

S-Function ブロック用に、マスク機能を使用してカスタムのダイアログボックスやアイコンを作成できます。マスクダイアログボックスを使用すると、S-Function の追加パラメーターの指定が簡単になります。マスクの詳細については、Author Block Masksを参照してください。

S-Function の使用目的

S-Function は、次のようなさまざまな用途に使用できます。

新しい汎用のブロックを作成する
ハードウェアデバイスドライバーを表すブロックを追加する
既存の C コードをシミュレーションに組み込む (Integrate C Functions Using Legacy Code Toolを参照)
システムを一連の数式として記述する
グラフィカルアニメーションを使用する (アニメーションを使った倒立振子の倒立振子の例を参照)

S-Function の最も一般的な用途は、カスタムの Simulink ブロックを作成することです (Block Authoring Basicsを参照)。S-Function を使用して汎用のブロックを作成すると、それをモデルで繰り返し使用し、ブロックのインスタンスごとにパラメーターを変えることができます。

参考

Level-2 MATLAB S-Function | S-Function Builder | S-Function | MATLAB Function