Design of S-function

Design of S-function

Simulink provides many built-in basic library modules for users to establish a system model by connecting these modules. Modules that are frequently used are combined and encapsulated to build new modules that can be reused. However, they are still based on built-in modules originally provided by SIMULINK.
Simulink S-function is a powerful new tool for extending the module library.

 

I. Concept of S-function
S-function is a computer language description of a dynamic system. In Matlab, you can choose to write M files or C or Mex files, here we will only show you how to use M files to write S-function.
S-function provides a powerful tool to extend the library of the Simulink-Z module. It uses a specific call syntax to allow functions to interact with the Simulink-z- ressor.
S-function is most widely used to customize the user's own Simulink module. It is widely used and supports continuous systems, discrete systems, and hybrid systems.
2. Create M file S-function
1. Use the template file: sfuntmp1. m
The template file is located in the toolbox/Simulink/blocks directory under the MATLAB root directory.
The structure of S-function in the template file is very simple. It only specifies the M file sub-function to be called for different flag values. For example, when the flag is 3, that is, when the module is in the simulation stage of computing output, the Child function called is sys = mdloutputs (t, x, u ).
The template file uses the switch statement to complete this designation. Of course, this structure is not unique. You can also use the if statement to complete the same function. In addition, some values can be removed based on actual needs, because not every module needs to be called by all sub-functions.
The template file is only a reference format provided by SIMULINK for the convenience of users. It is not required to write the S-function syntax. You can change the name of the sub-function, you can also directly write the code in the main function, but the advantage of using the template file is that it is convenient and clear.
To write a S-function using a template, you only need to replace the S-function name with the expected function name. If you need additional input parameters, you need to add these parameters after the input parameter list, because the previous four parameters are automatically passed in when S-function is called by SIMULINK. We recommend that you do not modify the output parameters. The next step is to replace the code of each sub-function in the template with the corresponding code based on the task to be completed by the compiled S-function.
In each simulation phase, the S-function is called. During the call, the simulation phase uses the flag to input different values, in addition, different roles will be specified for the return parameter SYS. That is to say, although it is the same sys variable, it has different meanings in different simulation stages. This change is automatically completed by the simulation system.
Description of available sub-functions in the M file S-function is as follows:
Mdlinitializesizes: defines the basic features of the S-function module, including the sampling time, the initial conditions for continuous or discrete states, and the sizes array.
Mdlderivatives: a differential equation used to calculate continuous state variables.
Mdlupdate: update the discrete state, sampling time, and master time step.
Mdloutputs: calculates the output of S-function. Mdlgettimeofnextvarhit: calculates the absolute time of the next sampling point. This method only describes a variable discrete sampling time in mdlinitializesizes.
Mdlterminate: The end of the simulation task is required.

In summary, the establishment of S-function can be divided into two separate tasks:
The initialization module features the width of the input and output signals, the initial conditions of discrete continuous states, and the sampling time.
Place the algorithm in the appropriate S-function subfunction.
2. Define the initial information of S-function
In order for the Simulink S to identify an M file S-function, you must provide instructions on the S-function in the S-function, including initial conditions such as the sampling time, number of consecutive or discrete states. This part is mainly completed in the mdlinitializesizes subfunction.
The sizes array is the carrier of S-function information, and its internal field meaning is:
Numcontstates: number of consecutive States (the width of the continuous part of the state vector)
Numdiscstates: number of discrete States (the width of the discrete part of the state vector)
Numoutputs: Number of output variables (width of the output vector)
Numinputs: Number of input variables (width of the input vector)
Dirfeedthrough: whether there is direct feed
Numsampletimes: number of sampling times
If the width of the vectors represented by fields is dynamically changeable, you can assign them to-1.
Note that dirfeedthrough is a Boolean variable with values of 0 and 1. 0 indicates no direct feed, when writing the mdloutputs sub-function, you must ensure that the input variable U is not displayed in the sub-function code; 1 indicates that the sub-function is directly fed in.
Numsampletimes indicates the number of sampling times, that is, the number of rows of TS variables, which is related to the user's definition of TS.
Note that S-function ignores the port, so when there are multiple input variables or multiple output variables, the MUX module or Demux module must be used to combine multiple single inputs into one compound input vector or separate one compound output vector into multiple single outputs.
3. Description of Input and Output Parameters
The default four input parameters of S-function are t, x, u, and flag. Their order cannot be changed, meaning:
T: indicates the current simulation time. This input parameter is usually used to determine the next sampling time, or to distinguish different sampling time points in a multi-sampling rate system, and perform different processing accordingly.
X: indicates the state vector. this parameter is required, even when the system does not have a state. It can be used flexibly.
U: indicates the input vector.
Flag: it is a parameter that controls which sub-function is called in each simulation phase, and is automatically set by the value of the parameter when the simulation is called by the simulation system.
The default four return parameters of S-function are sys, x0, STR, and Ts. Their order cannot be changed, meaning:
SYS: A common return parameter. The value returned by sys depends on the flag value.
X0: it is the initial status value (when there is no status, it is an empty matrix []). This return parameter is valid only when the flag value is 0, and will be ignored in other cases.
STR: this parameter is meaningless. It is reserved by Mathworks for future applications. The M file S-function must be set as an empty matrix.
TS: a matrix of m × 2. Its two columns represent the sampling interval and offset respectively.
Example 1 csfunc. m (continuous State S-function)
Example 2 dsfunc. m (discrete State S-function)
Example 3 mixedm. m (Mixed System S-function)
Example 4 vsfunc. m (Variable Step Simulation System)
Example 5 filt. M, rect. M, rload. m (non-Template File Format)