Comparison of Custom Block Functionality
When creating a custom block, consider:
Does the block model continuous or discrete state behavior?
Is the simulation performance important?
Do you need to generate code for a model containing the custom block?
This table shows how each custom block type addresses the three concerns.
Modelling Considerations
Custom Block Type | Model State Dynamics | Simulation Performance | Code Generation |
---|---|---|---|
Interpreted MATLAB Function | No | Less fast | Not supported |
Level-2 MATLAB S-Function | Yes | Less fast | Requires a TLC file |
MATLAB Function | No | Fast | Supported with exceptions |
MATLAB System | Yes | Fast | Supported with exceptions |
S-Function | Yes | Fast | Requires a TLC file or non-inline S-Function support |
C Caller | No | Fast | Supported |
C Function | Yes | Fast | Supported |
S-Function Builder | Yes | Fast | Supported |
Simulink Function | Yes | Fast | Supported |
Subsystem | Yes | Fast | Supported |
Fcn | No | Very fast | Supported |
For detailed design of custom blocks, consider:
Does the custom block need multiple input and output ports?
What are the callback methods to communicate with the Simulink® engine and which custom blocks let you implement all or a subset of these callback methods?
How important is the effect of the custom block on the speed of updating the Simulink diagram?
Model State Behavior
You need to model the state behavior for a block that requires some or all of its previous outputs to compute its current outputs. See State variables for more information.
Custom Block Type | Notes |
---|---|
Fcn, Interpreted MATLAB Function, C Caller | Does not allow you to model state behavior. |
MATLAB Function, C Function | Allows you to model a discrete state using persistent
variables. |
Level-2 MATLAB® S-Function | Allows you to model both continuous and discrete state
behavior using the ContStates or
Dwork run-time object methods in
combination with block callback methods. For a list of supported
methods, see Level-2 MATLAB S-Function Callback Methods
in Write Level-2 MATLAB S-Functions. |
MATLAB System | Allows you to model discrete state behavior using
DiscreteState properties of the
System object™, in combination with block callback methods. This
block uses System object methods for callback methods:
mdlOutputs
(stepImpl ,
outputImpl ),
mdlUpdate
(updateImpl ),
mdlInitializeConditions
(resetImpl ),
mdlStart
(setupImpl ),
mdlTerminate
(releaseImpl ). For more information see
What Are System Objects?. |
C MEX S-Function, S-Function Builder | Allows you to model both continuous and discrete state behavior in combination with block callback methods. For more information, see Callback Methods for C MEX S-Functions |
Simulink Function | Communicates directly with the engine. You can model the state behavior using appropriate blocks from the continuous and discrete Simulink block libraries. When multiple calls to this function originate from different callers, the state values are also persistent between these calls. For more information, see Call a Simulink Function Block from Multiple Sites. |
Subsystem | Communicates directly with the engine. You can model the state behavior using appropriate blocks from the continuous and discrete Simulink block libraries. |
Simulation Performance
For most applications, all custom block types provide satisfactory simulation performance. Use the Simulink profiler to get the actual performance indication. See How Profiler Captures Performance Data for more information.
The two categories of performance indication are the interface cost and the algorithm cost. The interface cost is the time it takes to move data from the Simulink engine into the block. The algorithm cost is the time it takes to perform the algorithm that the block implements.
Custom Block Type | Notes |
---|---|
Fcn | Has the highest simulation performance. The block is tightly integrated with the Simulink engine and optimized for simulation and code generation. |
Interpreted MATLAB Function | Has a slower performance due to the interface, but has the
same algorithm cost as a MATLAB function. When block data (such as inputs and outputs) is accessed or returned from an Interpreted MATLAB Function block, the Simulink engine packages this data into MATLAB arrays. This packaging takes additional time and causes a temporary increase in memory during communication. If you pass large amounts of data across this interface, such as frames or arrays, the performance can be substantially slow. Once the data has been converted, the MATLAB execution engine executes the algorithm. As a result, the algorithm cost is the same as for MATLAB function. |
Level-2 MATLAB S-Function | Incurs the same algorithm costs as the Interpreted
MATLAB Function block, but with a slightly higher
interface cost. Since MATLAB S-Functions can handle multiple inputs and
outputs, the packaging is more complicated than for the
Interpreted MATLAB Function block. In
addition, the Simulink engine calls the MATLAB execution engine for each block method you
implement, whereas the Interpreted MATLAB
Function block calls the MATLAB execution engine only for the
Outputs method. |
MATLAB Function | Performs simulation through code generation and incurs the
same interface cost as other Simulink built-in blocks. The algorithm cost of this block is harder to analyze because of the block's implementation. On average, a function for this block and the MATLAB function run at about the same speed. If the MATLAB Function block has code that uses coder.extrinsic to call
out to the MATLAB execution engine, it incurs all the costs that the
MATLAB S-Function or Interpreted MATLAB
Function block incur. Calling out to the MATLAB execution engine from a MATLAB
Function block produces a warning to prevent you
from doing so unintentionally. To reduce the algorithm cost, you can disable debugging for all MATLAB Function blocks. |
MATLAB System | In the interpreted execution mode, performance is similar to that of the Level-2 MATLAB S-function because the model simulates the block using the MATLAB execution engine. In the code generation mode, performance is similar to that of the MATLAB Function because the model simulates the block using the generated code. For more information, see the MATLAB Function entry in this table. |
C Caller, C Function | First time model simulation with could be slower due to parsing and building of the custom code. To speed up the simulation after the first compile, from Configuration parameters, select Faster Builds for faster compile and select Faster Runs for faster simulation. |
C MEX S-Function | Simulates via the compiled code and incurs the same interface cost as Simulink built-in blocks. The algorithm cost depends on the complexity of the S-Function. |
S-Function Builder | This block only builds an S-Function from the specifications and C code you supply. You can also use this block as a wrapper for the generated S-Function in models. The algorithm cost of this block compared to C MEX S-Function is incurred only from the wrapper. |
Simulink Function, Subsystem | If included in a library, introduces no interface or
algorithm costs beyond what would normally be incurred if the
block existed as a regular subsystem in the model.
Performance is proportional to the complexity of the algorithm implemented in the subsystem. If the subsystem is contained in a library, some cost is incurred when Simulink loads any unloaded libraries the first time the diagram is updated or readied for simulation. If all referenced library blocks remain unchanged, Simulink does not subsequently reload the library. Compiling the model becomes faster than if the model did not use libraries. |
Code Generation
You need code generation if your model is part of a bigger system. Not all custom block types support code generation with Simulink Coder™.
Custom Block Type | Notes |
---|---|
Fcn | Supports code generation. |
Interpreted MATLAB Function | Does not support code generation. |
C Caller, C Function | Supports code generation. |
Level-2 MATLAB S-Function | Generates code only if you implement the algorithm using a
Target Language Compiler (TLC) function. In accelerated and
external mode simulations, you can choose to execute the
S-Function in the interpretive mode by calling back to the
MATLAB execution engine without implementing the
algorithm in TLC. If the MATLAB S-Function is SimViewingDevice , the
Simulink
Coder product automatically omits the block during code
generation. |
MATLAB Function, MATLAB System | Supports code generation. However, if your block calls out to the MATLAB execution engine, it will build with the Simulink Coder product only if the calls to the MATLAB execution engine do not affect the block outputs. Under this condition, the Simulink Coder product omits these calls from the generated C code. This feature allows you to leave visualization code in place, even when generating embedded code. |
C MEX S-Function, S-Function Builder | Both supports code generation.
See S-Functions and Code Generation (Simulink Coder) for more information. |
Simulink Function | Supports code generation. |
Subsystem | Supports code generation as long as the blocks contained within the subsystem support code generation. For more information, see Subsystems (Simulink Coder). |
Multiple Input and Output Ports
These types of custom blocks support multiple input and output ports.
Custom Block Type | Notes |
---|---|
Fcn, Interpreted MATLAB Function | Supports only a single input and a single output port. |
MATLAB Function | Supports multiple input and output ports, including buses. For more information, see Create Structures in MATLAB Function Blocks and Attach Buses to MATLAB Function Blocks. |
MATLAB System | Supports multiple input and output ports, including buses. In
addition, you can modify the number of input and output ports
based on System object properties using the
getNumInputs and
getNumOutputs methods. |
C Caller, C Function | Supports multiple input and output ports, including buses. |
Level-2 MATLAB S-Function, C MEX S-Function, S-Function Builder | Supports multiple input and output ports. In addition, you can modify the number of input and output ports based on user-defined parameters. The C MEX S-Function and S-Function Builder support buses. |
Simulink Function | Supports multiple input and output ports, including buses. |
Subsystem | Supports multiple input and output ports, including buses. In addition, you can modify the number of input and output ports based on user-defined parameters. See Self-Modifiable Linked Subsystems for more information. |
Speed of Updating the Simulink Diagram
Simulink updates the diagram before every simulation and when requested by the user. Every block introduces some overhead into the diagram update process.
Custom Block Type | Notes |
---|---|
Fcn, Interpreted MATLAB Function | Low diagram update cost. |
MATLAB Function, C Caller, C Function | Simulation is performed through code generation, so this blocks can take a significant amount of time when first updated. However, because code generation is incremental, Simulink does not repeatedly update the block if the block and the signals connected to it have not changed. |
MATLAB System | Faster than MATLAB Function because code is not generated to update the diagram. Since, code generation is incremental, Simulink does not repeatedly update the block if the block and the signals connected to it have not changed. |
C MEX S-Function, Level-2 MATLAB S-Function | Incurs greater costs than other Simulink blocks only if it overrides methods executed when
updating the diagram. If these methods become complex, they can
contribute significantly to the time it takes to update the diagram.
For a list of methods executed when updating the diagram, see the
process view in Simulink Engine Interaction with C S-Functions. When
updating the diagram, Simulink invokes all relevant methods in the model
initialization phase up to, but not including,
mdlStart . |
Simulink Function, Subsystem | The speed is proportional to the complexity of the algorithm implemented in the subsystem. If the subsystem is contained in a library, some cost is incurred when Simulink loads any unloaded libraries the first time the diagram is updated or readied for simulation. If all referenced library blocks remain unchanged, Simulink does not subsequently reload the library. Compiling the model becomes faster than if the model does not use libraries. |
Callback Methods
Simulink blocks communicate with the Simulink engine through block callback methods, which fully specify the behavior of blocks (except the Simulink Function block). Each custom block type allows you to implement a different set of callback methods. To learn how blocks interact with Simulink engine, see Simulink Engine Interaction with C S-Functions. This table uses S-Function Callback Methods names as equivalents.
Custom Block Type | Notes |
---|---|
Fcn, Interpreted MATLAB Function, MATLAB Function, C Caller | All create a mdlOutputs method to
calculate the value of outputs given the value of inputs. You
cannot implement any other callback methods using one of these
blocks and, therefore, cannot model state behavior. |
C Function | Allows implementation of start, output, and terminate callback methods. Allows modeling of discrete states with persistent data. |
Level-2 MATLAB S-Function | Allows implementation of a larger subset of callback methods, including methods you can use to model continuous and discrete states. For a list of supported methods, see Level-2 MATLAB S-Function Callback Methods in Write Level-2 MATLAB S-Functions. |
MATLAB System | Uses System object methods for callback methods:
mdlOutputs
(stepImpl ,
outputImpl ),
mdlUpdate
(updateImpl ),
mdlInitializeConditions
(resetImpl ),
mdlStart
(setupImpl ),
mdlTerminate
(releaseImpl ). For more information,
see Simulink Engine Interaction with System Object Methods |
C MEX S-Function | Allows implementation of a complete set of callback methods. |
S-Function Builder | Allows implementation of mdlOutputs ,
mdlDerivatives and
mdlUpdate . |
Simulink Function | Packaged as a standalone function. Any caller to this function becomes part of one of the callback methods based on the caller’s location. |
Subsystem | Communicates directly with the engine. You can model state behaviors using appropriate blocks from the continuous and discrete Simulink block libraries. |
Comparing MATLAB S-Functions to MATLAB Functions for Code Generation
MATLAB S-functions and MATLAB functions for code generation have some fundamental differences.
The Simulink Coder product can generate code for both MATLAB S-functions and MATLAB functions for code generation. However, MATLAB S-functions require a Target Language Compiler (TLC) file for code generation. MATLAB functions for code generation do not require a TLC file.
MATLAB S-functions can use any MATLAB function whereas MATLAB functions for code generation are a subset of the MATLAB language. For a list of supported functions for code generation, see Functions and Objects Supported for C/C++ Code Generation.
MATLAB S-functions can model discrete and continuous state dynamics whereas MATLAB functions for code generation cannot model state dynamics.
Expanding Custom Block Functionality
You can expand the functionality of any custom block using callbacks and MATLAB graphics.
Block callbacks perform user-defined actions at specific points in the simulation. For example, the callback can load data into the MATLAB workspace before the simulation or generate a graph of simulation data at the end of the simulation. You can assign block callbacks to any of the custom block types. For a list of available callbacks and more information on how to use them, see Block Callbacks.
App Designer, the MATLAB graphical user interface development environment, provides tools for easily creating custom user interfaces. See App Building for more information on using App Designer.
See Also
Fcn | Interpreted MATLAB Function | Level-2 MATLAB S-Function | MATLAB Function | MATLAB System | S-Function | S-Function Builder | Simulink Function | Subsystem | C Caller | C Function