S-Function C S-Function Concepts Understanding these key concepts should enable you to build S-functions correctl · Direct feedthrough Dynamically sized inputs Setting sample times and offsets Direct Feedthrough Direct feedthrough means that the output (or the variable sample time for variable sample time blocks )is controlled directly by the value of an input port a good rule of thumb is that an S-function input port has direct feedthrough if The output function(md1outputs or flag==3)is a function of the input u That is, there is direct feedthrough if the input u is accessed in mdloutputs Outputs can also include graphical outputs, as in the case of an XY graph The"time of next hit" function(md1GetTimeofNextVarHit or flag==4)of a variable sample time S-function accesses the input u An example of a system that requires its inputs i.e. has direct feedthrough)is the operationy k xu, where u is the input, k is the gain, and y is the output An example of a system that does not require its inputs(i.e, does not have direct feedthrough) is this simple integration algorithm Outputs: y =x Derivative: x= u where x is the state x is the state derivative with respect to time, u is the input, andy is the output. Note that x is the variable that Simulink integrates It is very important to set the direct feedthrough fla affects the execution order of the blocks in your model and is used to detect Dynamically Sized Arrays S-functions can be written to support arbitrary input dimensions. In this case the actual input dimensions are determined dynamically when a simulation is
S-Function Concepts 1-13 S-Function Concepts Understanding these key concepts should enable you to build S-functions correctly: • Direct feedthrough • Dynamically sized inputs • Setting sample times and offsets Direct Feedthrough Direct feedthrough means that the output (or the variable sample time for variable sample time blocks) is controlled directly by the value of an input port. A good rule of thumb is that an S-function input port has direct feedthrough if • The output function (mdlOutputs or flag==3) is a function of the input u. That is, there is direct feedthrough if the input u is accessed in mdlOutputs. Outputs can also include graphical outputs, as in the case of an XY Graph scope. • The “time of next hit” function (mdlGetTimeOfNextVarHit or flag==4) of a variable sample time S-function accesses the input u. An example of a system that requires its inputs (i.e., has direct feedthrough) is the operation , where u is the input, k is the gain, and y is the output. An example of a system that does not require its inputs (i.e., does not have direct feedthrough) is this simple integration algorithm Outputs: Derivative: where x is the state, is the state derivative with respect to time, u is the input, and y is the output. Note that is the variable that Simulink integrates. It is very important to set the direct feedthrough flag correctly because it affects the execution order of the blocks in your model and is used to detect algebraic loops. Dynamically Sized Arrays S-functions can be written to support arbitrary input dimensions. In this case, the actual input dimensions are determined dynamically when a simulation is y ku = × y x = x · = u x · x ·
1 Overview of s-functions started by evaluating the dimensions of the input vector driving the S-function The input dimensions can also be used to determine the number of continuous states, the number of discrete states, and the number of outputs M-file S-functions can have only one input port and that input port can accept only one-dimensional(vector) signals. However, the signals can be of varying widths. Within an M-file S-function, to indicate that the input width is dynamically sized, specify a value of-1 for the appropriate fields in the sizes structure, which is returned during the mdlInitializesizes call. You can determine the actual input width when your S-function is called by using length(u). If you specify a width of 0, the input port is removed from the S-function block A S-function can have multiple l/o ports and the ports can have different dimensions. The number of dimensions and the size of each dimension can be determined dynamically. For example, the following illustration shows two instances of the same S-Function block in a model Clodk The upper S-Function block is driven by a block with a three-element output vector. The lower S-Function block is driven by a block with a scalar output. B pecifying that the S-Function block has dynamically sized inputs, the same S-function can accommodate both situations. Simulink automatically calls the block with the appropriately sized input vector Similarly, if other block characteristics, such as the number of outputs or the number of discrete or continuous states, are specified as dynamically sized, Simulink defines these vectors to be the same length as the input vector C S-functions give you more flexibility in specifying the widths of input and output ports. See"Creating Input and Output Ports"on page 7-8 1-14
1 Overview of S-Functions 1-14 started by evaluating the dimensions of the input vector driving the S-function. The input dimensions can also be used to determine the number of continuous states, the number of discrete states, and the number of outputs. M-file S-functions can have only one input port and that input port can accept only one-dimensional (vector) signals. However, the signals can be of varying widths.Within an M-file S-function, to indicate that the input width is dynamically sized, specify a value of -1 for the appropriate fields in the sizes structure, which is returned during the mdlInitializeSizes call. You can determine the actual input width when your S-function is called by using length(u). If you specify a width of 0, the input port is removed from the S-function block. A C S-function can have multiple I/O ports and the ports can have different dimensions. The number of dimensions and the size of each dimension can be determined dynamically. For example, the following illustration shows two instances of the same S-Function block in a model. The upper S-Function block is driven by a block with a three-element output vector. The lower S-Function block is driven by a block with a scalar output. By specifying that the S-Function block has dynamically sized inputs, the same S-function can accommodate both situations. Simulink automatically calls the block with the appropriately sized input vector. Similarly, if other block characteristics, such as the number of outputs or the number of discrete or continuous states, are specified as dynamically sized, Simulink defines these vectors to be the same length as the input vector. C S-functions give you more flexibility in specifying the widths of input and output ports. See “Creating Input and Output Ports” on page 7-8
S-Function C 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 andor 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. ined by th TimeHit =(n period ) offset where n, an integer, is the current simulation step. The first value of n is always zer 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 eqt 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 1-15
S-Function Concepts 1-15 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
1 Overview of s-functions The fastest sample time in the system To set a block's sample time as inherited, use-l 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 I 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 pa [INHERITED SAMPLE TIME, 0.0] [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. 1-16
1 Overview of S-Functions 1-16 - 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
S-Function C a discrete S-function that changes at a specified rate should register the discrete sample time pair, [discrete sample time period, offset], te sample period >0.0 0≤ offset< discrete A discrete S-function that changes at a variable rate should register the [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 twe An S-function that changes as its input changes, even during minor ntegration steps, should register the INHERITED SAMPLE_ TIME ample time An s-function that changes as its input changes, but doesnt change during ninor 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 ofits 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 17
S-Function Concepts 1-17 • 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