Level-1 MATLAB S-Function の維持

Level-1 MATLAB S-Function の維持について

メモ

このセクションに記載されている情報は、既存の Level-1 MATLAB^® S-Function の維持にのみ使用することを目的としています。新しい MATLAB S-Function を開発する場合は、より機能的な Level-2 API を使用してください (Write Level-2 MATLAB S-Functionsを参照)。Level-1 MATLAB S-Function では、Level-2 MATLAB S-Function よりもはるかに小規模な S-Function API のサブセットのみがサポートされており、その機能は組み込みブロックと比較して制限されています。

Level-1 MATLAB S-Function は次の形式の MATLAB 関数です。

[sys,x0,str,ts]=f(t,x,u,flag,p1,p2,...)

ここで、f は S-Function の名前です。モデルのシミュレーション中に、Simulink^® エンジンは、flag 引数を使用して特定の呼び出しに対して実行するタスク (1 つ以上) を指定し、f を繰り返し呼び出します。S-Function がタスクを実行し、結果を出力ベクトルで返します。

Level-1 MATLAB S-Function の引数

Simulink エンジンは、次の引数を Level-1 MATLAB S-Function に渡します。

`t`	現在時間
`x`	状態ベクトル
`u`	入力ベクトル
`flag`	S-Function によって実行されるタスクを示す整数値

次の表で、flag で受け取ることのできる値について説明し、各値に対応する Level-2 MATLAB S-Function メソッドをリストします。

flag の引数

Level-1 の flag	Level-2 のコールバックメソッド	説明
0	`setup`	サンプル時間、連続状態および離散状態の初期条件、`sizes` 配列などの基本的な S-Function ブロックの特性を定義します (`sizes` 配列の説明については、S-Function ブロックの特性の定義を参照してください)。
1	`mdlDerivatives`	連続状態変数の導関数を計算します。
2	`mdlUpdate`	離散状態、サンプル時間、および主要なタイムステップの要件を更新します。
3	`mdlOutputs`	S-Function の出力を計算します。
4	`mdlOutputs` メソッドは実行時オブジェクトの `NextTimeHit` プロパティを更新します。	次のヒットの時間を絶対時間で計算します。このルーチンは、`setup` メソッドで可変離散時間のサンプル時間を指定する場合にのみ使用されます。
9	`mdlTerminate`	必要なシミュレーション終了タスクを実行します。

Level-1 MATLAB S-Function の出力

Level-1 MATLAB S-Function は、次の要素を含む出力ベクトルを返します。

汎用戻り引数の sys。返される値は flag の値によって異なります。たとえば、flag = 3 の場合、sys には S-Function の出力が含まれます。
初期状態値である x0 (システムに状態がない場合は空のベクトル)。x0 は、flag = 0 の場合を除き、無視されます。
元々は将来の使用を目的として用意されていた str。Level-1 MATLAB S-Function ではこれを空の行列 [] に設定する必要があります。
ブロックのサンプル時間とオフセットを含む 2 列の行列である ts (サンプル時間とオフセットを指定する方法については、Simulink の使用に関するページのサンプル時間の指定を参照)。
たとえば、S-Function をすべてのタイムステップ (連続サンプル時間) で実行する場合は、ts を [0 0] に設定します。接続されているブロックと同じレート (継承サンプル時間) で S-Function を実行する場合は、ts を [-1 0] に設定します。シミュレーション開始時間の 0.1 秒後から 0.25 秒ごとに (離散サンプル時間) 実行する場合は、ts を [0.25 0.1] に設定します。
それぞれ異なるサンプルレートで複数のタスクを実行する S-Function (つまり、マルチレート S-Function) を作成できます。この場合、ts では、S-Function で使用されるすべてのサンプルレートをサンプル時間の昇順で指定する必要があります。たとえば、S-Function がシミュレーション開始時間から 0.25 秒ごとに 1 つのタスクを実行し、シミュレーション開始時間の 0.1 秒後から 1 秒ごとに別のタスクを実行するとします。この場合、S-Function では ts を [.25 0; 1.0 .1] に設定する必要があります。これにより、Simulink エンジンは、[0 0.1 0.25 0.5 0.75 1 1.1 ...] の時間に S-Function を実行します。S-Function は、サンプル時間ごとに、そのサンプル時間に実行するタスクを決定する必要があります。
一部のタスクを連続的に (つまり、すべてのタイムステップで) 実行し、他のタスクを離散間隔で実行する S-Function を作成することもできます。

S-Function ブロックの特性の定義

Simulink エンジンで Level-1 MATLAB S-Function が認識されるようにするには、S-Function に関する特定の情報を提供する必要があります。この情報には、入力、出力、状態、およびその他のブロック特性の数が含まれます。

この情報を提供するには、S-Function の先頭で simsizes 関数を呼び出します。

sizes = simsizes;

この関数は初期化されていない sizes 構造体を返します。sizes 構造体に S-Function に関する情報を読み込む必要があります。以下の表に、sizes 構造体のフィールドをリストし、各フィールドに含まれる情報について説明します。

sizes 構造体のフィールド

フィールド名	説明
`sizes.NumContStates`	連続状態の数
`sizes.NumDiscStates`	離散状態の数
`sizes.NumOutputs`	出力の数
`sizes.NumInputs`	入力の数
`sizes.DirFeedthrough`	直達のフラグ
`sizes.NumSampleTimes`	サンプル時間の数

sizes 構造体を初期化した後、再度 simsizes を呼び出します。

sys = simsizes(sizes);

これにより、sizes 構造体内の情報が、Simulink エンジンで使用する情報を保持するベクトルである sys に渡されます。

S-Function パラメーターの処理

Level-1 MATLAB S-Function を呼び出すと、Simulink エンジンは常に標準ブロックパラメーター t、x、u、および flag を関数引数として S-Function に渡します。エンジンは、ユーザーによって指定された追加のブロック固有のパラメーターを S-Function に渡すことができます。ユーザーは、[S-Function ブロックパラメーター] ダイアログボックスの [S-Function パラメーター] フィールドでパラメーターを指定します (S-Function へのパラメーターの受け渡しを参照)。ブロックダイアログで追加のパラメーターが指定された場合、エンジンは追加の関数引数としてそのパラメーターを S-Function に渡します。追加の引数は、S-Function の引数リスト内で標準引数の後に続きます。その順序は、対応するパラメーターがブロックダイアログに表示されている順序になります。このブロック固有の S-Function パラメーター機能を使用することで、同じ S-Function でさまざまな処理オプションを実装できます。

Level-1 MATLAB S-Function から Level-2 への変換

各 Level-1 S-Function の flag に関連付けられたコードを適切な Level-2 S-Function のコールバックメソッドにマッピングすることで、Level-1 MATLAB S-Function を Level-2 MATLAB S-Function に変換できます。Level-1 の flag から Level-2 のコールバックメソッドへのマッピングについては、flag の引数の表を参照してください。さらに、

PostPropagationSetup メソッドで初期化された DWork ベクトルに Level-2 MATLAB S-Function の離散状態情報を保存します。
関数引数として S-Function に渡すのではなく、DialogPrm 実行時オブジェクトプロパティを使用して、Level-2 MATLAB S-Function ダイアログパラメーターにアクセスします。
可変サンプル時間を持つ S-Function の場合、Outputs メソッドの NextTimeHit 実行時オブジェクトプロパティを更新して、Level-2 MATLAB S-Function の次のサンプル時間ヒットを設定します。

たとえば、次の表では、Level-1 MATLAB S-Function の sfundsc2.m を Level-2 MATLAB S-Function に変換する方法を示しています。この例では、Level-1 MATLAB S-Function を変換する際の開始点として、Level-2 MATLAB S-Function のテンプレート msfuntmpl_basic.m を使用しています。表の行番号は、sfundsc2.m 内のコード行に対応しています。

sfundsc2_level2.m

function sfundsc2_level2(block)
%SFUNDSC2_LEVEL2 Level-2 version of sfundsc2.m
%  
%   Copyright 2003-2007 The MathWorks, Inc. 
  
%%
%% The setup method is used to setup the basic attributes of the
%% S-function such as ports, parameters, etc. Do not add any other
%% calls to the main body of the function.  
%%   
setup(block);
  
%endfunction

function setup(block)

  % Register number of ports
  block.NumInputPorts  = 1;
  block.NumOutputPorts = 1;
  
  % Setup port properties to be inherited or dynamic
  block.SetPreCompInpPortInfoToDynamic;
  block.SetPreCompOutPortInfoToDynamic;

  % Override input port properties
  block.InputPort(1).DatatypeID  = 0;  % double
  block.InputPort(1).Complexity  = 'Real';
  block.InputPort(1).Dimensions        = 1;
  block.InputPort(1).DirectFeedthrough = false;
  
  % Override output port properties
  block.OutputPort(1).DatatypeID  = 0; % double
  block.OutputPort(1).Complexity  = 'Real';
  block.OutputPort(1).Dimensions       = 1;
  
  % Register parameters
  block.NumDialogPrms     = 0;

  % Register sample times
  block.SampleTimes = [.10 0];
  
  %% -----------------------------------------------------------------
  %% Options
  %% -----------------------------------------------------------------
  % Specify if Accelerator should use TLC or call back into 
  % MATLAB file
  block.SetAccelRunOnTLC(false);
  
    
  %% -----------------------------------------------------------------
  %% Register methods
  %% -----------------------------------------------------------------
  block.RegBlockMethod('PostPropagationSetup', @DoPostPropSetup);
  block.RegBlockMethod('InitializeConditions', @InitializeConditions);
  block.RegBlockMethod('Outputs', @Outputs);
  block.RegBlockMethod('Update', @Update);
%endfunction

%% -------------------------------------------------------------------
%% The local functions 
%% -------------------------------------------------------------------
function DoPostPropSetup(block)
  
  block.NumDworks = 1;
  block.Dwork(1).Name            = 'x0';
  block.Dwork(1).Dimensions      = 1;
  block.Dwork(1).DatatypeID      = 0;      % double
  block.Dwork(1).Complexity      = 'Real'; % real
  block.Dwork(1).UsedAsDiscState = true;

 %endfunction

function InitializeConditions(block)
%% Initialize Dwork  
  block.Dwork(1).Data = 0;

%endfunction

function Outputs(block)
  
  block.OutputPort(1).Data = block.Dwork(1).Data;
  
%endfunction

function Update(block)
  
  block.Dwork(1).Data = block.InputPort(1).Data;
  
%endfunction

行番号	sfundsc2.m のコード	Level-2 MATLAB (sfundsc2_level2.m) のコード
1	function [sys,x0,str,ts]= ... sfundsc2(t,x,u,flag)	function sfundsc2(block) setup(block); `function` 行の構文は、Level-2 MATLAB S-Function ブロックの実行時オブジェクトである 1 つの入力引数 `block` を受け入れるように変更されます。Level-2 MATLAB S-Function の本体には、ローカル `setup` 関数を呼び出す 1 行が含まれています。
13 ～ 19	switch flag, case 0, [sys,x0,str,ts] = ... mdlInitializeSizes;	function setup(block) `flag` の値ゼロは、`setup` メソッドの呼び出しに対応します。Level-2 MATLAB S-Function は、コールバックメソッドを呼び出すために `switch` ステートメントを使用しません。代わりに、ローカル `setup` 関数により、シミュレーション中に直接呼び出されるコールバックメソッドを登録します。
24 ～ 31	case 2, sys = mdlUpdate(t,x,u); case 3, sys = mdlOutputs(t,x,u);	`setup` 関数は、`flag` の値 `2` と `3` に関連付けられた 2 つのローカル関数を登録します。 block.RegBlockMethod('Outputs' ,@Output); block.RegBlockMethod('Update' ,@Update);
53 ～ 66	sizes = simsizes; sizes.NumContStates = 0; sizes.NumDiscStates = 1; sizes.NumOutputs = 1; sizes.NumInputs = 1; sizes.DirFeedthrough = 0; sizes.NumSampleTimes = 1; sys = simsizes(sizes); x0 = 0; str = []; ts = [.1 0];	`setup` 関数は Level-2 MATLAB S-Function の属性も初期化します。 block.NumInputPorts = 1; block.NumOutputPorts = 1; block.InputPort(1).Dimensions = 1; block.InputPort(1).DirectFeedthrough = false; block.OutputPort(1).Dimensions = 1; block.NumDialogPrms = 0; block.SampleTimes = [0.1 0]; この S-Function には離散状態が含まれているため、`setup` メソッドは、DWork ベクトルを初期化する `PostPropagationSetup` コールバックメソッドと、初期状態値を設定する `InitializeConditions` コールバックメソッドを登録します。 block.RegBlockMethod('PostPropagationSetup',... @DoPostPropSetup); block.RegBlockMethod('InitializeConditions', ... @InitConditions);
56	sizes.NumDiscStates = 1;	`PostPropagationSetup` メソッドは、単一の離散状態を保存する DWork ベクトルを初期化します。 function DoPostPropSetup(block) %% Setup Dwork block.NumDworks = 1; block.Dwork(1).Name = 'x0'; block.Dwork(1).Dimensions = 1; block.Dwork(1).DatatypeID = 0; block.Dwork(1).Complexity = 'Real'; block.Dwork(1).UsedAsDiscState = true;
64	x0 = 0;	`InitializeConditions` メソッドは離散状態値を初期化します。 function InitConditions(block) %% Initialize Dwork block.Dwork(1).Data = 0
77 ～ 78	function sys = ... mdlUpdate(t,x,u) sys = u;	`Update` メソッドは、離散状態の次の値を計算します。 function Update(block) block.Dwork(1).Data = block.InputPort(1).Data;
88 ～ 89	function sys = ... mdlOutputs(t,x,u) sys = x;	`Outputs` メソッドは S-Function の出力を計算します。 function Outputs(block) block.OutputPort(1).Data = block.Dwork(1).Data;