MATLAB的S函数简介及其仿真过程

s函数是system Function的简称，用它来写自己的simulink模块。可以用matlab、C、C++、Fortran、Ada等语言来写。用s函数可以利用matlab的丰富资源，而不仅仅局限于simulink提供的模块，而用c或c++等语言写的s函数还可以实现对硬件端口的操作，还可以操作windows API等的

二、simulink的仿真过程

simulink的仿真有两个阶段：第一个为初始化，这个阶段主要是设置一些参数，像系统的输入输出个数、状态初值、采样时间等；第二个阶段就是运行阶段，这个阶段里要进行计算输出、更新离散状态、计算连续状态等等，这个阶段需要反复运行，直至结束。

    在matlab的workspace里输入edit sfuntmpl， 便打开一个matlab自己提供的s函数模板。

s函数的结构如下：

第一行：function [sys,x0,str,ts]=sfuntmpl(t,x,u,flag)

输入与输出变量的含义：t是采样时间，x是状态变量，u是输入（是做成simulink模块的输入）,flag是仿真过程中的状态标志（以它来判断当前是初始化还是运行等）；sys输出根据flag的不同而不同（下面将结合flag来讲sys的含义），x0是状态变量的初始值，str是保留参数，一般在初始化中将它置空就可以了,str=[]，ts是一个1×2的向量，ts(1)是采样周期，ts(2)是偏移量。 

switch flag,                  %判断flag，看当前处于哪个状态

case 0,

    [sys,x0,str,ts]=mdlInitializeSizes;

flag=0表示处于初始化状态，此时用函数mdlInitializeSizes进行初始化。

在初始化状态下，sys是一个结构体，用它来设置模块的一些参数，各个参数详细说明如下

    size = simsizes;%用于设置模块参数的结构体用simsizes来生成

    sizes.NumContStates = 0;%模块连续状态变量的个数

    sizes.NumDiscStates = 0;%模块离散状态变量的个数

    sizes.NumOutputs     = 0;%模块输出变量的个数

    sizes.NumInputs      = 0;%模块输入变量的个数

    sizes.DirFeedthrough = 1;%模块是否存在直接贯通（即输入能直接控制输出）

    sizes.NumSampleTimes = 1;%模块的采样时间个数，至少是一个

    sys = simsizes(sizes);   %设置完后赋给sys输出

举个例子，考虑如下模型：dx/dt=fc(t,x,u) 也可以用连续状态方程描述：dx/dt=A*x+B*u

      x(k+1)=fd(t,x,u) 也可以用离散状态方程描述：x(k+1)=H*x(k)+G*u(k)

       y=fo(t,x,u) 也可以用输出状态方程描述：y=C*x+D*u

设上述模型连续状态变量、离散状态变量、输入变量、输出变量均为1个，我们就只需改上面那一段代码为：

（一般连续状态与离散状态不会一块用，这儿是为了方便说明）

sizes.NumContStates=1;sizes.NumDiscStates=1;sizes.NumOutputs=1;sizes.NumInputs=1;

其他的可以不变。继续在mdlInitializeSizes函数中往下看：

     x0 = [];    %状态变量设置为空，表示没有状态变量，以我们上面的假设，可改为x0=[0,0](离散和连续的状态

            %变量我们都设它初值为0

     str = [];    %保留参数

     ts = [0 0]; %采样周期设为0表示是连续系统，如果是离散系统在下面的mdlGetTimeOfNextVarHit函数中具体介绍

在sfuntmpl的106行继续往下看：

    case 1,

      sys=mdlDerivatives(t,x,u);

flag=1表示此时要计算连续状态的微分，即上面提到的dx/dt=fc(t,x,u)中的dx/dt,找到mdlDerivatives函数（在193行）

如果设置连续状态变量个数为0，此处只需sys=[];就可以了，按我们上述讨论的那个模型，此处改成

sys=fc(t,x(1),u)或sys=A*x(1)+B*u %我们这儿x(1)是连续状态变量，而x(2)是离散的，这儿只用到连续的，此时的输出sys就是微分 

在sfuntmpl的112行：

    case 2,

       sys=mdlUpdate(t,x,u);

flag=2表示此时要计算下一个离散状态，即上面提到的x(k+1)=fd(t,x,u)，找到mdlUpdate函数（在206行）

它这儿sys=[];表示没有离散状态，我们这而可以改成sys=fd(t,x(2),u)或sys=H*x(2)+G*u;%sys即为x(k+1) 

在sfuntmpl的118行

    case 3,

       sys=mdlOutputs(t,x,u);

flag=3表示此时要计算输出，即y=fo(t,x,u),找到mdlOutputs函数（在218行），如上，如果sys=[]表示没有输出，我们

改成sys=fo(t,x,u)或sys=C*x+D*u %sys此时为输出y 

在sfuntmpl的124行

    case 4,

        sys=mdlGetTimeOfNextVarHit(t,x,u);

flag=4表示此时要计算下一次采样的时间，只在离散采样系统中有用(即上文的mdlInitializeSizes中提到的ts设置ts(1)不为0)

连续系统中只需在mdlGetTimeOfNextVarHit函数中写上sys=[];这个函数主要用于变步长的设置，具体实现大家可以用edit vsfunc

看vsfunc.m这个例子 

最后一个，在sfuntmpl的130行

    case 9,

       sys=mdlTerminate(t,x,u);

flag=9表示此时系统要结束，一般来说写上在mdlTerminate函数中写上sys=[]就可，如果你在结束时还要设置什么，就在此函数中写 

s函数还可以带用户参数，下面给个例子，和simulink下的gain模块功能一样， 

function [sys,x0,str,ts] = sfungain(t,x,u,flag,gain)

switch flag,

case 0,

      sizes = simsizes;

      sizes.NumContStates = 0;

      sizes.NumDiscStates = 0;

      sizes.NumOutputs     = 1;

      sizes.NumInputs      = 1;

      sizes.DirFeedthrough = 1;

      sizes.NumSampleTimes = 1; 

      sys = simsizes(sizes);

      x0=[];

      str=[];

      ts=[0,0];

case 3,      

      sys=gain*u;

case {1,2,4,9},

    sys = [];

end 

做好了s函数后，simulink--user-defined function下拖一个S-Function到你的模型，就可以用了

在simulink----user-defined function还有个s-Function Builder，他可以生成用c语言写的s函数

在matlab的workspace下打sfundemos，可以看到很多演示s函数的程序。

三、具体用法

创建一个有1输入（2维），2输出（1维），3个参数，还有全局变量的s-function。

 1.新建sfunction的C语言文件

     打开simulink，点击User-Defined Functions里面的S-Function Examples。这个里面有多个语言版本的模板，有C，C++，Ada，Fortran和M语言的版本，其实都大同小异，只要了解几个函数就很容易使用了。

选择C语言的版本：从S-function模块中选择C-file S-functions里面的Basic C-MEX template。打开后，另存为自己的模块名字，如test.c。

下面我们来分析代码： 

#define S_FUNCTION_NAME  test//这里把文件名sfuntmpl_basic修改为test

#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

//程序里面要用到的头文件在这里引用，如“math.h”等。

float global_var; //定义全局变量

static void mdlInitializeSizes(SimStruct *S)

{

 //这个函数用来设置输入、输出和参数的。

    ssSetNumSFcnParams(S, 3);  /*设置参数个数，这里为3 */

    if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {

        return;

    }

    ssSetNumContStates(S, 0);//设置连续状态的个数，缺省为0；

    ssSetNumDiscStates(S, 0);//设置离散状态的个数，缺省为0；

    if (!ssSetNumInputPorts(S, 1)) return;//设置输入变量的个数，这里为1

    ssSetInputPortWidth(S, 0, 2); //设置输入变量0的维数为2

ssSetInputPortRequiredContiguous(S, 0, true); //设置input0的访问方式，true就是临近访问，这样指针的增量后就可以直接访问下个input端口了。

ssSetInputPortDirectFeedThrough(S, 0, 1);// 设置输入端口的信号是否mdlOutputs函数中使用，这儿设置为true。

    if (!ssSetNumOutputPorts(S, 2)) return;//设置输出变量的个数

ssSetOutputPortWidth(S, 0, 1);//设置输出变量0的维数为1维

    ssSetOutputPortWidth(S, 1, 1);//设置输出变量1的维数为1维

ssSetNumSampleTimes(S, 1); //设置采样时间，此处为1s。

    ssSetNumRWork(S, 0);//不管

    ssSetNumIWork(S, 0);

    ssSetNumPWork(S, 0);

    ssSetNumModes(S, 0);

    ssSetNumNonsampledZCs(S, 0);

ssSetOptions(S, 0);

//下面可以写全局变量的初始化程序

global_var=1;

}

static void mdlInitializeSampleTimes(SimStruct *S)//暂时不管

{

    ssSetSampleTime(S, 0, CONTINUOUS_SAMPLE_TIME);

    ssSetOffsetTime(S, 0, 0.0);

}

#define MDL_INITIALIZE_CONDITIONS   /* Change to #undef to remove function */

#if defined(MDL_INITIALIZE_CONDITIONS)

  static void mdlInitializeConditions(SimStruct *S)//暂时不管

  {

  }

#endif /* MDL_INITIALIZE_CONDITIONS */

#define MDL_START  /* Change to #undef to remove function */

#if defined(MDL_START) 

  static void mdlStart(SimStruct *S)//暂时不管

  {

  }

#endif /*  MDL_START */

static void mdlOutputs(SimStruct *S, int_T tid)//这里填入相关的运算、算法等

{

real_T *para1 = mxGetPr(ssGetSFcnParam(S,0));

real_T *para2 = mxGetPr(ssGetSFcnParam(S,1));

real_T *para3 = mxGetPr(ssGetSFcnParam(S,2));

const real_T *u = (const real_T*) ssGetInputPortSignal(S,0);

real_T       *y1 = ssGetOutputPortSignal(S,0);

real_T       *y2 = ssGetOutputPortSignal(S,1);

y1[0]=u[0]*para1[0]+u[1]*para2[0];

y2[0]=u[1]*para3[0]+u[0]*para1[0];

}

#define MDL_UPDATE  /* Change to #undef to remove function */

#if defined(MDL_UPDATE)

  static void mdlUpdate(SimStruct *S, int_T tid)

  {

  }

#endif /* MDL_UPDATE */

#define MDL_DERIVATIVES  /* Change to #undef to remove function */

#if defined(MDL_DERIVATIVES)

  static void mdlDerivatives(SimStruct *S)

  {

  }

#endif /* MDL_DERIVATIVES */

static void mdlTerminate(SimStruct *S)//这里需要把global变量全部初始化，否则下次运行程序时，全局变量还是之前的值。

{

}

#ifdef  MATLAB_MEX_FILE    /* Is this file being compiled as a MEX-file? */

#include "simulink.c"      /* MEX-file interface mechanism */

#else

#include "cg_sfun.h"       /* Code generation registration function */

#endif

2.编译

在matlab的command window 里面输入“mex test.c”，即可将test.c编译为mex文件。

3.调用sfunction

在simulink空间里面拉入sfunction，在s-function name里面填入test，参数里面填入要设定的参数，然后仿真即可。