Main Content

Specify S-Function Sample Times

About Sample Times

You can specify the sample-time behavior of your S-functions in mdlInitializeSampleTimes. Your S-function can inherit its rates from the blocks that drive it or define its own rates.

You can specify your S-function rates (i.e., sample times) as

  • Block-based sample times

  • Port-based sample times

  • Hybrid block-based and port-based sample times

With block-based sample times, the S-function specifies a set of operating rates for the block as a whole during the initialization phase of the simulation. With port-based sample times, the S-function specifies a sample time for each input and output port individually during initialization. During the simulation phase, with block-based sample times, the S-function processes all inputs and outputs each time a sample hit occurs for the block. By contrast, with port-based sample times, the block processes a particular port only when a sample hit occurs for that port.

For example, consider two sample rates, 0.5 and 0.25 seconds, respectively:

  • In the block-based method, selecting 0.5 and 0.25 directs the block to execute inputs and outputs at 0.25 second increments.

  • In the port-based method, setting the input port to 0.5 and the output port to 0.25 causes the block to process inputs at 2 Hz and outputs at 4 Hz.

You should use port-based sample times if your application requires unequal sample rates for input and output execution or if you do not want the overhead associated with running input and output ports at the highest sample rate of your block.

In some applications, an S-Function block might need to operate internally at one or more sample rates while inputting or outputting signals at other rates. The hybrid block- and port-based method of specifying sample rates allows you to create such blocks.

In typical applications, you specify only one block-based sample time. Advanced S-functions might require the specification of port-based or multiple block sample times.

Block Based Sample Times

Level-2 MATLAB® S-functions specify block-based sample times in their setup method. Use the line

block.SampleTimes = [sampleTime offsetTime];

to specify the sample time. Use a value of [-1 0] to indicate an inherited sample time. See Specify Sample Time in Using Simulink® for a complete list of valid sample times.

Specifying Port-Based Sample Times

To use port-based sample times in a Level-2 MATLAB S-function:

  • Specify the sample and offset times for each S-function port in the setup method. For example: 

    block.InputPort(1).SampleTime = [-1 0];
block.OutputPort(1).SampleTime = [-1 0];

    The setup method must not specify a sample time for the block when using port-based sample times.

  • Provide SetInputPortSampleTime and SetOutputPortSampleTime methods, even if your S-function does not inherit its port-based sample times.

Specifying Inherited Sample Time for a Port

In a Level-2 MATLAB S-function, use a value of [-1 0] for the SampleTime property of each port to specify that the port inherits its sample time.

Specifying Constant Sample Time (Inf) for a Port

If your S-function uses port-based sample times, it can set a sample time of Inf on any of its ports. A port-based sample time of Inf means that the signal entering or leaving the port stays constant.

In a Level-2 MATLAB S-function, use this code to specify a sample time of Inf for a port:

block.OutputPort(1).SampleTime = [inf 0];
block.SetAllowConstantSampleTime(true);

Configuring Port-Based Sample Times for Use in Triggered Subsystems

Level-2 MATLAB S-functions with port-based sample times cannot be placed in a triggered subsystem. You must modify your S-function to use block-based sample times if you need to include it in a triggered subsystem.

Hybrid Block-Based and Port-Based Sample Times

Level-2 MATLAB S-functions support port-based sample times, but do not support hybrid block-based sample times. See Specifying Port-Based Sample Times for more information.

Multirate S-Function Blocks

In a Level-2 MATLAB S-function, use the IsSampleHit method to determine whether the current simulation time is one at which a task handled by this block is active.

If you write TLC code to generate inlined code from an S-function, and if the TLC code contains an Outputs function, you must modify the TLC code if all of these conditions are true:

  • The output port has a constant value. It uses or inherits a sample time of Inf.

  • The S-function is a multi-rate S-function.

In this case, the TLC code must generate code for the constant-valued output port by using the function OutputsForTID instead of the function Outputs. For more information, see Specifying Constant Sample Time (Inf) for a Port.

Synchronizing Multirate S-Function Blocks

If tasks running at different rates need to share data, you must ensure that data generated by one task is valid when accessed by another task running at a different rate.

Suppose, for example, that your model has an input port operating at one rate (with a sample time index of 0) and an output port operating at a slower rate (with a sample time index of 1). Further, suppose that you want the output port to output the value currently on the input. Note that higher-rate tasks always run before slower-rate tasks. Thus, the input task always runs before the output task, ensuring that valid data is always present at the output port.

In a Level-2 MATLAB S-function, use the IsSpecialSampleHit method to determine whether the current simulation time is one at which multiple tasks implemented by this block are active.

See Also

| | |

Related Topics