Matlab 中S-函數的使用 sfuntmpl

function [sys,x0,str,ts,simStateCompliance] = sfuntmpl(t,x,u,flag)
%SFUNTMPL General MATLAB S-Function Template
%   With MATLAB S-functions, you can define you own ordinary differential
%   equations (ODEs), discrete system equations, and/or just about
%   any type of algorithm to be used within a Simulink block diagram.
%
%   The general form of an MATLAB S-function syntax is:
%       [SYS,X0,STR,TS,SIMSTATECOMPLIANCE] = SFUNC(T,X,U,FLAG,P1,...,Pn)
%
%   What is returned by SFUNC at a given point in time, T, depends on the
%   value of the FLAG, the current state vector, X, and the current
%   input vector, U.
%
%   FLAG   RESULT             DESCRIPTION
%   -----  ------             --------------------------------------------
%   0      [SIZES,X0,STR,TS]  Initialization, return system sizes in SYS,
%                             initial state in X0, state ordering strings
%                             in STR, and sample times in TS.
%   1      DX                 Return continuous state derivatives in SYS.
%   2      DS                 Update discrete states SYS = X(n+1)
%   3      Y                  Return outputs in SYS.
%   4      TNEXT              Return next time hit for variable step sample
%                             time in SYS.
%   5                         Reserved for future (root finding).
%   9      []                 Termination, perform any cleanup SYS=[].
%
%
%   The state vectors, X and X0 consists of continuous states followed
%   by discrete states.
%
%   Optional parameters, P1,...,Pn can be provided to the S-function and
%   used during any FLAG operation.
%
%   When SFUNC is called with FLAG = 0, the following information
%   should be returned:
%
%      SYS(1) = Number of continuous states.
%      SYS(2) = Number of discrete states.
%      SYS(3) = Number of outputs.
%      SYS(4) = Number of inputs.
%               Any of the first four elements in SYS can be specified
%               as -1 indicating that they are dynamically sized. The
%               actual length for all other flags will be equal to the
%               length of the input, U.
%      SYS(5) = Reserved for root finding. Must be zero.
%      SYS(6) = Direct feedthrough flag (1=yes, 0=no). The s-function
%               has direct feedthrough if U is used during the FLAG=3
%               call. Setting this to 0 is akin to making a promise that
%               U will not be used during FLAG=3. If you break the promise
%               then unpredictable results will occur.
%      SYS(7) = Number of sample times. This is the number of rows in TS.
%
%
%      X0     = Initial state conditions or [] if no states.
%
%      STR    = State ordering strings which is generally specified as [].
%
%      TS     = An m-by-2 matrix containing the sample time
%               (period, offset) information. Where m = number of sample
%               times. The ordering of the sample times must be:
%
%               TS = [0      0,      : Continuous sample time.
%                     0      1,      : Continuous, but fixed in minor step
%                                      sample time.
%                     PERIOD OFFSET, : Discrete sample time where
%                                      PERIOD > 0 & OFFSET < PERIOD.
%                     -2     0];     : Variable step discrete sample time
%                                      where FLAG=4 is used to get time of
%                                      next hit.
%
%               There can be more than one sample time providing
%               they are ordered such that they are monotonically
%               increasing. Only the needed sample times should be
%               specified in TS. When specifying more than one
%               sample time, you must check for sample hits explicitly by
%               seeing if
%                  abs(round((T-OFFSET)/PERIOD) - (T-OFFSET)/PERIOD)
%               is within a specified tolerance, generally 1e-8. This
%               tolerance is dependent upon your model's sampling times
%               and simulation time.
%
%               You can also specify that the sample time of the S-function
%               is inherited from the driving block. For functions which
%               change during minor steps, this is done by
%               specifying SYS(7) = 1 and TS = [-1 0]. For functions which
%               are held during minor steps, this is done by specifying
%               SYS(7) = 1 and TS = [-1 1].
%
%      SIMSTATECOMPLIANCE = Specifices how to handle this block when saving and
%                           restoring the complete simulation state of the
%                           model. The allowed values are: 'DefaultSimState',
%                           'HasNoSimState' or 'DisallowSimState'. If this value
%                           is not speficified, then the block's compliance with
%                           simState feature is set to 'UknownSimState'.


%   Copyright 1990-2010 The MathWorks, Inc.

%
% The following outlines the general structure of an S-function.
%
switch flag,

  %%%%%%%%%%%%%%%%%%
  % Initialization %
  %%%%%%%%%%%%%%%%%%
  case 0,
    [sys,x0,str,ts,simStateCompliance]=mdlInitializeSizes;

  %%%%%%%%%%%%%%%
  % Derivatives %
  %%%%%%%%%%%%%%%
  case 1,
    sys=mdlDerivatives(t,x,u);

  %%%%%%%%%%
  % Update %
  %%%%%%%%%%
  case 2,
    sys=mdlUpdate(t,x,u);

  %%%%%%%%%%%
  % Outputs %
  %%%%%%%%%%%
  case 3,
    sys=mdlOutputs(t,x,u);

  %%%%%%%%%%%%%%%%%%%%%%%
  % GetTimeOfNextVarHit %
  %%%%%%%%%%%%%%%%%%%%%%%
  case 4,
    sys=mdlGetTimeOfNextVarHit(t,x,u);

  %%%%%%%%%%%%%
  % Terminate %
  %%%%%%%%%%%%%
  case 9,
    sys=mdlTerminate(t,x,u);

  %%%%%%%%%%%%%%%%%%%%
  % Unexpected flags %
  %%%%%%%%%%%%%%%%%%%%
  otherwise
    DAStudio.error('Simulink:blocks:unhandledFlag', num2str(flag));

end

% end sfuntmpl

%
%=============================================================================
% mdlInitializeSizes
% Return the sizes, initial conditions, and sample times for the S-function.
%=============================================================================
%
function [sys,x0,str,ts,simStateCompliance]=mdlInitializeSizes

%
% call simsizes for a sizes structure, fill it in and convert it to a
% sizes array.
%
% Note that in this example, the values are hard coded.  This is not a
% recommended practice as the characteristics of the block are typically
% defined by the S-function parameters.
%
sizes = simsizes;

sizes.NumContStates  = 0;
sizes.NumDiscStates  = 0;
sizes.NumOutputs     = 0;
sizes.NumInputs      = 0;
sizes.DirFeedthrough = 1;
sizes.NumSampleTimes = 1;   % at least one sample time is needed

sys = simsizes(sizes);

%
% initialize the initial conditions
%
x0  = [];

%
% str is always an empty matrix
%
str = [];

%
% initialize the array of sample times
%
ts  = [0 0];

% Specify the block simStateCompliance. The allowed values are:
%    'UnknownSimState', < The default setting; warn and assume DefaultSimState
%    'DefaultSimState', < Same sim state as a built-in block
%    'HasNoSimState',   < No sim state
%    'DisallowSimState' < Error out when saving or restoring the model sim state
simStateCompliance = 'UnknownSimState';

% end mdlInitializeSizes

%
%=============================================================================
% mdlDerivatives
% Return the derivatives for the continuous states.
%=============================================================================
%
function sys=mdlDerivatives(t,x,u)

sys = [];

% end mdlDerivatives

%
%=============================================================================
% mdlUpdate
% Handle discrete state updates, sample time hits, and major time step
% requirements.
%=============================================================================
%
function sys=mdlUpdate(t,x,u)

sys = [];

% end mdlUpdate

%
%=============================================================================
% mdlOutputs
% Return the block outputs.
%=============================================================================
%
function sys=mdlOutputs(t,x,u)

sys = [];

% end mdlOutputs

%
%=============================================================================
% mdlGetTimeOfNextVarHit
% Return the time of the next hit for this block.  Note that the result is
% absolute time.  Note that this function is only used when you specify a
% variable discrete-time sample time [-2 0] in the sample time array in
% mdlInitializeSizes.
%=============================================================================
%
function sys=mdlGetTimeOfNextVarHit(t,x,u)

sampleTime = 1;    %  Example, set the next hit to be one second later.
sys = t + sampleTime;

% end mdlGetTimeOfNextVarHit

%
%=============================================================================
% mdlTerminate
% Perform any end of simulation tasks.
%=============================================================================
%
function sys=mdlTerminate(t,x,u)

sys = [];

% end mdlTerminate

S-函數的幾個概念:

 

1）  直接饋通

在編寫S-函數時，初始化函數中須要對sizes.DirFeedthrough 進行設置，若是輸出函數mdlOutputs或者對於變採樣時間的mdlGetTimeOfNextVarHit是輸入u的函數，則模塊具備直接饋通的特性sizes.DirFeedthrough=1;不然爲0。

 

2）  採樣時間

仿真步長就是整個模型的基礎採樣時間，各個子系統或模塊的採樣時間，必須以這個步長爲整數倍。

連續信號和離散信號對計算機而言其實都是採樣而來的，只是採樣時間不一樣，連續信號採樣時間可認爲趨於0且基於微分方程，離散信號採樣時間比較長基於差分方程。離散信號當前狀態由前一個時刻的狀態決定，連續信號能夠經過微分方程計算獲得。若是要將連續信號離散化還要考慮下信號可否恢復的問題，即香農定理。

 

採樣時間點的肯定：下一個採樣時間=（n*採樣間隔）+ 偏移量，n表示當前的仿真步，從0開始。

對於連續採樣時間，ts能夠設置爲[0 0]，其中偏移量爲0；

對於離散採樣時間，ts假設爲[0.25 0.1]，表示在S-函數仿真開始後0.1s開始每隔0.25s運行一次，固然每一個採樣時刻都會調用mdlOutPuts和mdlUpdate函數；

對於變採樣時間，即離散採樣時間的兩次採樣時間間隔是可變的，每次仿真步開始時都須要用mdlGetTimeNextVarHit計算下一個採樣時間的時刻值。ts能夠設置爲[-2 0]。

對於多個任務，每一個任務均可以以不一樣的採樣速率執行S-函數，假設任務A在仿真開始每隔0.25s執行一次，任務B在仿真後0.1s每隔1s執行一次，那麼ts設置爲[0.25 0.1;1.0 0.1]，具體到S-函數的執行時間爲[0 0.1 0.25 0.5 0.75 1.0 1.1…]。

若是用戶想繼承被鏈接模塊的採樣時間，ts只要設置爲[-1 0]。

 子函數的做用

(1).mdlInitializeSizes函數-初始化函數
function[sys,x0,str,ts,simStateCompliance]=mdlInitializeSizes  
sizes = simsizes;  
sizes.NumContStates  = 0;  %連續狀態個數  
sizes.NumDiscStates  = 0;  %離散狀態個數  
sizes.NumOutputs     = 0;  %輸出個數  
sizes.NumInputs      = 0;  %輸入個數  
sizes.DirFeedthrough = 1;  %是否直接饋通  
sizes.NumSampleTimes = 1;  %採樣時間個數，至少一個  
sys = simsizes(sizes);     %將size結構傳到sys中  
x0  = [];                     %初始狀態向量，由傳入的參數決定，沒有爲空  
str = [];  
ts  = [0 0];                  %設置採樣時間，這裏是連續採樣，偏移量爲0  
% Specify the blocksimStateCompliance. The allowed values are:  
%    'UnknownSimState', < The defaultsetting; warn and assume DefaultSimState  
%    'DefaultSimState', < Same sim state as abuilt-in block  
%    'HasNoSimState',   < No sim state  
%    'DisallowSimState' < Error out whensaving or restoring the model sim state  
simStateCompliance = 'UnknownSimState';  

(2).mdlGetTimeOfNextVarHit(t,x,u)函數-計算下一個採樣時間
functionsys=mdlGetTimeOfNextVarHit(t,x,u)  
sampleTime = 1;    %  Example, set the next hit to be one secondlater.  
sys = t + sampleTime;  

(3).mdlOutputs函數-計算S函數輸出
functionsys=mdlOutputs(t,x,u)  
sys = [];  

(4).mdlUpdate函數-更新
function sys=mdlUpdate(t,x,u)  
sys = [];  

(5).mdlDerivatives函數-微分函數（計算連續狀態導數）
functionsys=mdlDerivatives(t,x,u)  
sys = [];  

(6).mdlTerminate函數-終止仿真
functionsys=mdlTerminate(t,x,u)  
sys = [];  

function [sys,x0,str,ts,simStateCompliance] = sfuntmpl_c(t,x,u,flag)

%%%%Simulink中s函數模板的翻譯版
%[sys,x0,str,ts,simStateCompliance] = sfuntmpl(t,x,u,flag，p1,…pn)

% flag result 描述 
% —– —— ——————————————– 
% 0 [sizes,x0,str,Ts] 初始化，返回SYS的大小，初始狀態x0,str,採樣時間Ts 
% 1 DX 返回連續狀態微分SYS. 
% 2 DS 更新離散狀態 SYS = X(n+1) 
% 3 Y 返回輸出SYS. 
% 4 TNEXT Return next time hit for variable step sample time in SYS. 
% 5 Reserved for future (root finding). 
% 9 [] 結束 perform any cleanup SYS=[].

% 當flag=0時，如下信息必須賦值回傳 
% SYS(1) = 連續狀態個數 
% SYS(2) = 離散狀態個數 
% SYS(3) = 輸出量個數 
% SYS(4) = 輸入量個數 注：上述4個變量能夠賦值爲-1，表示其值可變 
% SYS(5) = 保留值。爲0. 
% SYS(6) = 直接饋通標誌(1=yes, 0=no).若是u在flag=3時被使用，說明S函數是直接饋通，賦值爲1. 不然爲0. 
% SYS(7) = 採樣時間個數，Ts的行數 
% 
% X0 = 初始狀態。沒有則賦值爲[].除flag=0外，被忽略。 
% STR = 系統保留，設爲[]. 
% TS = m*2 矩陣。（採樣週期，偏移量） 
% TS = [0 0, : 連續採樣 
% 0 1, : 在1個Ts後連續採樣 
% PERIOD OFFSET, : Discrete sample time where 
% PERIOD > 0 & OFFSET < PERIOD. 
% -2 0]; : 變步長離散採樣， 
% flag=4用於決定下一個採樣時刻 
% 注： 
% 若但願每一個時間步都運行，則設Ts=[0,0] 
% 若但願繼承採樣時間運行，則設Ts=[-1,0] 
% 若但願繼承採樣時間運行，且但願在微步內不變化，應該設Ts=[-1,1] 
% 若但願仿真開始0.1s後每隔0.25秒運行，則設Ts=[0.25,0.1] 
% 若但願按照不一樣速率執行不一樣任務，則Ts應按照升序排列。 
% 即：每隔0.25秒執行一個任務，同時在開始0.1秒後，每隔1秒執行另外一個任務 
% Ts=[0.25,0; 1.0,0.1],則simulink將在下列時刻執行s函數[0,0.1,0.25,0.5,0.75,1,1.1,…]

% 如下是S函數的主函數 
switch flag, 
case 0, % 初始化 
[sys,x0,str,ts,simStateCompliance]=mdlInitializeSizes;

case 1, % 連續時間導數 
sys=mdlDerivatives(t,x,u);

case 2, % 更新離散狀態量 
sys=mdlUpdate(t,x,u);

case 3, % 計算輸出 
sys=mdlOutputs(t,x,u);

case 4, % 計算下一步採樣時刻 
sys=mdlGetTimeOfNextVarHit(t,x,u);

case 9, % 結束仿真 
sys=mdlTerminate(t,x,u);

otherwise % 未知flag值 
DAStudio.error('Simulink:blocks:unhandledFlag', num2str(flag)); 
end % S函數主程序結束

%============================================================================= 
% mdlInitializeSizes 
% 返回s函數的sizes、初始條件、採樣時刻 
%============================================================================= 
function [sys,x0,str,ts,simStateCompliance]=mdlInitializeSizes 
% 調用simsizes函數爲sizes結構賦值 
% simsizes函數是S函數模塊特有的。它的結構和代碼是固定的。

sizes = simsizes; 
sizes.NumContStates = 0; %連續狀態個數 
sizes.NumDiscStates = 0; %離散狀態個數 
sizes.NumOutputs = 0; %輸出量個數 
sizes.NumInputs = 0; %輸入量個數 
sizes.DirFeedthrough = 1; %直接饋通標誌 
sizes.NumSampleTimes = 1; % 至少有一個採樣時刻 
sys = simsizes(sizes);

x0 = 0; % 狀態初始化 
str = []; % str 始終爲空 
ts = [0 0];% 初始化採樣時間

% 指定simStateCompliance的值. 
% ‘UnknownSimState’, < 默認值; warn and assume DefaultSimState 
% ‘DefaultSimState’, < Same sim state as a built-in block 
% ‘HasNoSimState’, < No sim state 
% ‘DisallowSimState’ < Error out when saving or restoring the model sim state 
simStateCompliance = 'UnknownSimState'; 
% 子函數mdlInitializeSizes 結束

%============================================================================= 
% mdlDerivatives 
% 返回連續狀態量的導數 
%============================================================================= 
function sys=mdlDerivatives(t,x,u)

sys = [];

% 子函數mdlDerivatives結束

%============================================================================= 
% mdlUpdate 
%更新離散時間狀態，採樣時刻和主時間步的要求。 
%============================================================================= 
function sys=mdlUpdate(t,x,u)

sys = []; 
% 子函數 mdlUpdate 結束

%============================================================================= 
% mdlOutputs 
% 計算並返回模塊輸出量 
%============================================================================= 
function sys=mdlOutputs(t,x,u)

sys = [];

% 子函數 mdlOutputs 結束

%============================================================================= 
% mdlGetTimeOfNextVarHit 
% 返回下一個採樣時刻。注意返回結果是一個絕對時間，只在Ts=[-2,0]時使用。 
%============================================================================= 
function sys=mdlGetTimeOfNextVarHit(t,x,u)

sampleTime = 1; % 例子。設置下一個採樣時刻爲1s後。 
sys = t + sampleTime;

% 子函數 mdlGetTimeOfNextVarHit 結束

%============================================================================= 
% mdlTerminate 
% 仿真結束 
%============================================================================= 
% 
function sys=mdlTerminate(t,x,u)

sys = [];

% 子函數 mdlTerminate結束

function [sys,x0,str,ts,simStateCompliance]=limintm(t,x,u,flag,lb,ub,xi）
%傳入的三個參數放在後面lb,ub,xi的位置  
%LIMINTM Limited integrator implementation.  
%   Example MATLAB file S-function implementing a continuous limited integrator  
%   where the output is bounded by lower bound (LB) and upper bound (UB)  
%   with initial conditions (XI).  
%     
%   See sfuntmpl.m for a general S-function template.  
%  
%   See also SFUNTMPL.  
      
%   Copyright 1990-2009 The MathWorks, Inc.  
%   $Revision: 1.1.6.2 $  
   
switch flag  
   
  %%%%%%%%%%%%%%%%%%  
  % Initialization %  
  %%%%%%%%%%%%%%%%%%  
  case 0           
    [sys,x0,str,ts,simStateCompliance] = mdlInitializeSizes(lb,ub,xi);  
   
  %%%%%%%%%%%%%%%  
  % Derivatives %  
  %%%%%%%%%%%%%%%  
  case 1  
    sys = mdlDerivatives(t,x,u,lb,ub);  
   
  %%%%%%%%%%%%%%%%%%%%%%%%  
  % Update and Terminate %  
    
  %%%%%%%%%%%%%%%%%%%%%%%%  
  case {2,9}  
    sys = []; % do nothing  
   
  %%%%%%%%%%  
  % Output %  
  %%%%%%%%%%  
  case 3  
    sys = mdlOutputs(t,x,u);   
   
  otherwise  
    DAStudio.error('Simulink:blocks:unhandledFlag', num2str(flag));  
end  
   
% end limintm  
   
%  
%=============================================================================  
% mdlInitializeSizes  
% Return the sizes, initial conditions, and sample times for the S-function.  
%=============================================================================  
%  
function [sys,x0,str,ts,simStateCompliance] = mdlInitializeSizes(lb,ub,xi)  
   
sizes = simsizes;  
sizes.NumContStates  = 1;%1個連續狀態，即積分狀態  
sizes.NumDiscStates  = 0;  
sizes.NumOutputs     = 1;  
sizes.NumInputs      = 1;  
sizes.DirFeedthrough = 0;  
sizes.NumSampleTimes = 1;  
   
sys = simsizes(sizes);  
str = [];  
x0  = xi; %積分狀態初始條件‘  
ts  = [0 0];   % sample time: [period, offset]  
   
% speicfy that the simState for this s-function is same as the default  
simStateCompliance = 'DefaultSimState';  
   
% end mdlInitializeSizes  
   
%  
%=============================================================================  
% mdlDerivatives  
% Compute derivatives for continuous states.  
%=============================================================================  
%  
function sys = mdlDerivatives(t,x,u,lb,ub)  
   
if (x <= lb & u < 0)  | (x>= ub & u>0 )  
  sys = 0;  
else  
  sys = u;  
end  
   
% end mdlDerivatives  
   
%  
%=============================================================================  
% mdlOutputs  
% Return the output vector for the S-function  
%=============================================================================  
%  
function sys = mdlOutputs(t,x,u)  
   
sys = x;  
   
% end mdlOutputs