Writing S-Functions

Setting Sample Times and Offsets

Both M-file and C MEX S-functions allow a high degree of flexibility in specifying when an S-function executes. Simulink provides the following options for sample times:

• Continuous sample time -- For S-functions that have continuous states and/or nonsampled zero crossings (see "How Simulink Works" in Using Simulink for explanation of zero crossings). For this type of S-function, the output changes in minor time steps.
• Continuous but fixed in minor time step sample time -- For S-functions that need to execute at every major simulation step, but do not change value during minor time steps.
• Discrete sample time -- If your S-Function block's behavior is a function of discrete time intervals, you can define a sample time to control when Simulink calls the block. You can also define an offset that delays each sample time hit. The value of the offset cannot exceed the corresponding sample time.

• A sample time hit occurs at time values determined by the formula

  • TimeHit = (n * period) + offset
    

  where n, an integer, is the current simulation step. The first value of n is always zero.

  If you define a discrete sample time, Simulink calls the S-function mdlOutput and mdlUpdate routines at each sample time hit (as defined in the above equation).

• Variable sample time -- A discrete sample time where the intervals between sample hits can vary. At the start of each simulation step, S-functions with variable sample times are queried for the time of the next hit.
• Inherited sample time -- Sometimes an S-Function block has no inherent sample time characteristics (that is, it is either continuous or discrete, depending on the sample time of some other block in the system). You can specify that the block's sample time is inherited. A simple example of this is a Gain block that inherits its sample time from the block driving it.

• A block can inherit its sample time from:
  • The driving block
  • The destination block
  • The fastest sample time in the system

  To set a block's sample time as inherited, use -1 in M-file S-functions and INHERITED_SAMPLE_TIME in C S-functions as the sample time. For more information on the propagation of sample times, see "Sample Time Colors" in Using Simulink.

S-functions can be either single or multirate; a multirate S-function has multiple sample times.

Sample times are specified in pairs in this format: [sample_time, offset_time]. The valid sample time pairs are

• [CONTINUOUS_SAMPLE_TIME, 0.0]
  [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
  [discrete_sample_time_period, offset]
  [VARIABLE_SAMPLE_TIME, 0.0]
  

where

• CONTINUOUS_SAMPLE_TIME = 0.0
  FIXED_IN_MINOR_STEP_OFFSET = 1.0
  VARIABLE_SAMPLE_TIME = -2.0
  

and the italics indicate that a real value is required.

Alternatively, you can specify that the sample time is inherited from the driving block. In this case the S-function can have only one sample time pair

• [INHERITED_SAMPLE_TIME, 0.0]
  

or

• [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
  

where

• INHERITED_SAMPLE_TIME = -1.0
  

The following guidelines might help you specify sample times:

• A continuous S-function that changes during minor integration steps should register the [CONTINUOUS_SAMPLE_TIME, 0.0] sample time.
• A continuous S-function that does not change during minor integration steps should register the
  [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.
• A discrete S-function that changes at a specified rate should register the discrete sample time pair, [discrete_sample_time_period, offset],
  where

• discrete_sample_period > 0.0 
  

• and

  • 0.0  offset < discrete_sample_period
    

• A discrete S-function that changes at a variable rate should register the variable step discrete sample time.

• [VARIABLE_SAMPLE_TIME, 0.0]
  

• The mdlGetTimeOfNextVarHit routine is called to get the time of the next sample hit for the variable step discrete task.

If your S-function has no intrinsic sample time, you must indicate that your sample time is inherited. There are two cases:

• An S-function that changes as its input changes, even during minor integration steps, should register the [INHERITED_SAMPLE_TIME, 0.0] sample time.
• An S-function that changes as its input changes, but doesn't change during minor integration steps (that is, remains fixed during minor time steps), should register the
  [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET] sample time.

• The Scope block is a good example of this type of block. This block should run at the rate of its driving block, either continuous or discrete, but should never run in minor steps. If it did, the scope display would show the intermediate computations of the solver rather than the final result at each time point.

S-Function Concepts

S-Function Examples