S function is used to develop new Simulink general function modules and is a tool for extending the module library. S functions can be written in MATLAB language, C, C++, FORTRAN, Ada and other languages. Using text mode to input formulas and equations in the S function is very suitable for mathematical description of complex dynamic systems, and allows more precise control of the simulation during the simulation process.
The S function is called a system function and describes the function block in a non-graphical way. S functions written in MATLAB language can make full use of the rich resources provided by MATLAB and conveniently call various toolbox functions and graphics functions; S functions written in C language can achieve access to the operating system, such as communication with other processes and sync etc. S functions written in non-MATLAB languages need to use a compiler to generate MEX files. This article introduces the method of designing S function using MATLAB language, and introduces the application of S function through examples.
01, Write S function in MATLAB language
The S function has a fixed program format, and you can build your own S function starting from the S function template program provided by Simulink.
1. Main program
The guide statement of the S function main program is as follows:
Among them, fname is the function name of the S function, t, x, u, and flag are the simulation time, state vector, input vector, and subroutine call flag respectively. The flag controls which subroutine of the S function is called at each stage of the simulation. Its meaning and related information are shown in Table 1. Each time Simulink calls the S function, these four parameters must be given. sys, x0, str and ts are the return parameters of the S function. sys is a universal symbol that returns parameters. What parameters it gets depends on the flag value. For example, when flag = 3, sys gets the output vector value of the S function. x0 is the initial state value. If there are no state variables in the system, x0 will get an empty array. str is only used to check the consistency between the system model and the S function API (Application Programming Interface). For the M-file S function, it will be set to an empty array. ts is a two-column matrix, one column is the sampling period of each state variable in the S function, and the other column is the offset of the corresponding sampling time. The sampling periods are arranged in increasing order, and one row in ts corresponds to one sampling period. For continuous systems, both the sampling period and offset should be set to 0. If the sampling period is -1, the sampling period of the input signal will be inherited.
■ Table 1 Meaning of flag parameter
In addition, the main program input parameters can also include user-defined parameter tables: p1, p2,..., pn, which are the optional variables that you want to assign to the S function, and their values are set through the parameter dialog box of the corresponding S function. You can also assign values in the command line window. So the boot statement of the S function main program can be written as:
The main program uses a switch statement to guide Simulink to the correct subroutine.
2. Subroutine
The S function M file has a total of 6 subroutines, which are called by Simulink at different stages of simulation. The prefix of these subroutines is mdl. Every time the S function is called, a flag value must be given, and the subroutine corresponding to the flag value in the S function is actually executed. Simulink needs to call different subroutines in the S function at different stages of simulation.
(1) Initialize subroutine mdlInitializeSizes. The subroutine mdlInitializeSizes defines S function parameters, such as sampling time, input volume, output volume, number of state variables and other characteristics. In order to provide this information to Simulink, the simsizes function should be called at the beginning of the subroutine mdlInitializeSizes. This function returns a sizes structure. The members of the structure sizes.NumContStates, sizes.NumDiscStates, sizes.NumOutputs and sizes.NumInputs respectively represent the continuous state variables. number, the number of discrete state variables, the number of outputs and the number of inputs. These 4 values can be set to -1 to make their sizes dynamically change. The member sizes.DirFeedthrough is the pass-through flag, that is, whether the input signal appears directly at the output end. Whether it is set to pass-through depends on whether the output is a function of the input, or whether the sampling time is a function of the input. 1 means yes, 0 means no. The member sizes.NumSampleTimes is the number of module sampling periods, usually 1.
The structure sizes set as required are assigned to the sys parameter using the sys = simsizes(sizes) statement. In addition to sys, the system's initial state variable x0, description variable str and sampling period variable ts should also be set.
(2) Other subroutines. The dynamic update of status uses two subroutines, mdlDerivatives and mdlUpdate. The former is used for status update of continuous modules, and the latter is used for update of discrete status. The output values of these functions, that is, the corresponding status, are returned by the sys variable. For a hybrid system that contains both continuous and discrete states, these two functions need to be written at the same time to describe the continuous and discrete states respectively.
The module output signal is calculated using the mdlOutputs subroutine, and the system output is still returned by the sys variable.
In general applications, flags 4 and 9 are rarely used, and the two subroutines mdlGetTimeOfNextVarHit and mdlTerminate are rarely used.
02,Application of S function
Let's look at an example of writing an S function using an M file.
[Example 1]Use the S function to implement y=k(1+x), that is, add 1 to an input signal and amplify it by k times.
(1) Write S function, the procedure is as follows:
S函数 timek.m,其输出是输入加1的k倍
function[sys,x0,str,ts]= timek(t,x,uflag,k)
switch flag,
case 0
[sys,x0,str,ts]= mdlInitializeSizes;//初始化
case 3
sys = mdlOutputs(t,x,u,k);//计算输出量
case{1,2,4,9)
sys =[];
otherwise
error(num2str(flag));//出错处理
end
//mdlInitializeSizes:当 flag 为0时进行整个系统的初始化
functionsys,x0,str,ts]= mdlInitializeSizes()
//调用函数 simsizes 以创建结构 sizes
sizes = simsizes;
//用初始化信息填充结构 sizes
sizes.NumContStates = 0;//无连续状态
sizes.NumDiscStates = 0://无离散状态
sizes.NumOutputs = 1;//有一个输出量
sizes.NumInputs = 1;//有一个输入量
sizes.DirFeedthrough = 1;//有一个输入量
sizes.NumSampleTimes =1;//输出量中含有输入量
//根据上面的设置设定系统初始化参数
sys = simsizes(sizes);
//给其他返回参数赋值
x0[];
//设置初始状态为零状
str=[];
ts=[-1,0];//将 str 变量设置为空字符串%假定继承输入信号的采样周期
//mdlOutputs当 flag 值为3 时,计算输出量
function sys = mdlOutputs(t,x,u,k)
sys=k*(1+u)Save the program with the file name timek.m. After programming the S function, the module can be tested.
(2) Test of S function module. Establish the connection between the S-Function module and the written S-function file. Create a new model, add the S-Function module in the User-Defined Functions module library, as well as the Sine Wave module and Scope module to the model editing window to build a simulation model as shown in Figure 1.
Double-click the S-Function module in the model editing window to open its parameter dialog box. Fill in the S-function name timek in the "S-function name" box, and fill in the external parameter k in the "S-function parameter" box, as shown in the figure 2 shown. If there are multiple external parameters, separate them with commas. k can be defined with commands in the MATLAB workspace. When the value of input k is 5, the simulation results obtained by running are shown in Figure 3.
