|On this page…|
When creating a custom block, you may want to consider the following.
Does the custom block need multiple input and output ports?
Does the block need to model continuous or discrete state behavior?
Will the block inputs and outputs have various data attributes, such as data types or complexity?
Do you need to generate code for a model containing the custom block?
The following two tables provide an overview of how each custom block type addresses the previous questions. More detailed information for each consideration follows these two tables.
|Custom Block Type||Supports Multiple Inputs and Outputs||Models State Dynamics||Supports Various Data Attributes|
|Subsystem||Yes, including bus signals.||Yes.||Yes, including all data types, numeric types, and dimensions supported by the Simulink software. Also supports frame-based signals.|
|Fcn||No. Must have a single vector input and scalar output.||No.||Supports only real scalar signals with a data type of double or single.|
|Interpreted MATLAB Function||No. Must have a single vector input and output.||No.||Supports only n-D, real, or complex signals with a data type of double.|
|MATLAB Function||Yes, including bus signals.||No.||Yes, including all data types, numeric types, and dimensions supported by the Simulink software. Also supports frame-based signals.|
|MATLAB System||Yes, excluding bus signals.||Yes.||Yes, including all data types (except buses and enumerated), numeric types, and dimensions supported by the Simulink software. Also supports frame-based signals.|
|Level-2 MATLAB® S-function||Yes.||Yes, including limited access to other S-function APIs.||Yes, including all data types, numeric types, and dimensions supported by the Simulink software. Also supports frame-based signals.|
|C MEX S-function||Yes, including bus signals if using the Legacy Code Tool to generate the S-function.||Yes, including full access to all S-function APIs.|
Speed and Code Generation Requirements
|Custom Block Type||Speed of Updating the Diagram||Simulation Overhead||Code Generation Support|
|Subsystem||Proportional to the complexity of the subsystem. For library blocks, can be slower the first time the library is loaded.||Proportional to the complexity of the subsystem. Library blocks introduce no additional overhead.||Natively supported.|
|Fcn||Very fast.||Minimal, but these blocks also provide limited functionality.||Natively supported.|
|Interpreted MATLAB Function||Fast.||High and incurred when calling out to the MATLAB interpreter. These calls add overhead that should be avoided if simulation speed is a concern.||Not supported.|
|MATLAB Function||Can be slower if code must be generated to update the diagram.||Minimal if the MATLAB interpreter is not called. Simulation speed is equivalent to C MEX S-functions when the MATLAB interpreter is not called.||Natively supported, with exceptions. See Code Generation for more information.|
|MATLAB System||Faster than MATLAB Function because code is not generated to update the diagram.||In interpreted execution mode, the simulation has the overhead of calling the MATLAB interpreter. In code generation mode, the first simulation incurs code generation overhead. However, in subsequent runs, the block simulation speed is equivalent to C MEX S-functions.||Natively supported, with exceptions.|
|Level-2 MATLAB S-function||Can be slower if the S-function overrides methods executed when updating the diagram.||Higher than for Interpreted MATLAB Function blocks because the MATLAB interpreter is called for every S-function method used. Very flexible, but very costly.||MATLAB S-functions initialized as a SimViewingDevice do not generate code. Otherwise, MATLAB S-functions require a TLC-file for code generation.|
|C MEX S-function||Can be slower if the S-function overrides methods executed when updating the diagram.||Minimal, but proportional to the complexity of the algorithm and the efficiency of the code.||Might require a TLC-file.|
The diagram shows how to decide which block to use. One deciding factor is whether you need the block for a function or a system. In this context:
A function defines the relationship between a set of inputs and outputs.
A system defines the relationship between a set of inputs and outputs. It can also define a set of states, parameters, and System object™ processing methods for initialization, output, update, termination, and so forth.
The following types of custom blocks support multiple input and output ports.
|Custom Block Type||Multiple Input and Output Port Support|
|Subsystem||Supports multiple input and output ports, including bus signals. In addition, you can modify the number of input and output ports based on user-defined parameters. See Self-Modifying Linked Subsystems for more information.|
|Fcn, Interpreted MATLAB Function||Supports only a single input and a single output port. You must use a Mux block to combine the inputs and a Demux block to separate the outputs if you need to pass multiple signals into or out of these blocks.|
|MATLAB Function||Supports multiple input and output ports, including bus signals. See How Structure Inputs and Outputs Interface with Bus Signals for more information.|
|MATLAB System||Supports multiple input and output ports, excluding bus signals. See Define System Objects for more information.|
|S-function (MATLAB or C MEX)||Supports multiple input and output ports. In addition, you can modify the number of input and output ports based on user-defined parameters. S-functions generated using the Legacy Code Tool also accept Simulink bus signals. See Integrate C Functions Using Legacy Code Tool for more information.|
Simulink blocks communicate with the Simulink engine through the S-function API, a set of methods that fully specifies the behavior of blocks. Each custom block type accesses a different sets of the S-function APIs, as follows.
|Custom Block Type||S-Function API Support|
|Subsystem||Communicates directly with the engine. You can model state behaviors using appropriate blocks from the Continuous and Discrete Simulink block libraries.|
|Fcn, Interpreted MATLAB Function, MATLAB Function||All create an mdlOutputs method to calculate the value of the outputs given the value of the inputs. You cannot access any other S-function API methods using one of these blocks and, therefore, cannot model state behavior.|
|MATLAB System||Uses System object methods for S-function APIs: mdlOutputs (stepImpl, outputImpl), mdlUpdate (updateImpl), mdlInitializeConditions (resetImpl), mdlStart (setupImpl), mdlTerminate (releaseImpl).|
|MATLAB S-function||Accesses a larger subset of the S-function APIs, including the methods needed to model continuous and discrete states. For a list of supported methods, see Level-2 MATLAB S-Function Callback Methods in "Writing S-Functions".|
|C MEX S-function||Accesses the complete set of S-function APIs.|
All custom block types support real scalar inputs and outputs with a data type of double.
|Custom Block Type||Data Attribute Support|
|Subsystem||Supports any data type supported by the Simulink software, including fixed-point types. Also supports complex, 2-D, n-D, and frame-based signals.|
|Fcn||Supports only double or single data types. In addition, the input and output cannot be complex and the output must be a scalar signal. Does not support frame-based signals.|
|Interpreted MATLAB Function||Supports 2-D, n-D, and complex signals, but the signal must have a data type of double. Does not support frame-based signals.|
|MATLAB Function||Supports any data type supported by the Simulink software, including fixed-point types. Also supports complex, 2-D, n-D, and frame-based signals.|
|MATLAB System||Supports any data type supported by the Simulink software, including fixed-point types. Also supports complex, 2-D, n-D, and frame-based signals.|
|S-function (MATLAB or C MEX)|
The Simulink software updates the diagram before every simulation and whenever requested by the user. Every block introduces some overhead into the "update diagram" process.
|Custom Block Type||Speed of Updating the Diagram|
|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 the Simulink software loads any unloaded libraries the first time the diagram is updated or readied for simulation. If all referenced library blocks remain unchanged, the Simulink software does not subsequently reload the library and compiling the model becomes faster than if the model did not use libraries.|
|Fcn, Interpreted MATLAB Function||Does not incur greater update cost than other Simulink blocks.|
|MATLAB Function||Performs simulation through code generation, so these blocks might take a significant amount of time when first updated. However, because code generation is incremental, if the block and the signals connected to it have not changed, Simulink does not repeatedly update the block.|
|MATLAB System||Faster than MATLAB Function because code is not generated to update the diagram. However, because code generation is incremental, if the block and the signals connected to it have not changed in subsequent iterations, Simulink does not repeatedly update the block.|
|S-function (MATLAB or C MEX)||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, the Simulink software invokes all relevant methods in the model initialization phase up to, but not including, mdlStart.|
For most applications, any of the custom block types provide acceptable simulation performance. Use the Simulink profiler to obtain an indication of the actual performance. SeeHow Profiler Captures Performance Data for more information.
You can break simulation performance into two categories. The interface cost is the time it takes to move data from the Simulink engine into the block. The algorithm cost is the time needed to perform the algorithm that the block implements.
|Custom Block Type||Simulation Overhead|
|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.|
|Fcn||Has the least simulation overhead. The block is tightly integrated with the Simulink engine and implements a rudimentary expression language that is efficiently interpreted.|
|Interpreted MATLAB Function||Has a higher interface cost than most blocks and 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, this overhead can be substantial.
Once the data has been converted, the MATLAB interpreter executes the algorithm. As a result, the algorithm cost is the same as for MATLAB function. Efficient code can be competitive with C code if MATLAB is able to optimize it, or if the code uses the highly optimized MATLAB library functions.
|MATLAB Function||Performs simulation through code generation and so incurs the
same interface cost as standard 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 a MATLAB function run at about the same speed. To further reduce the algorithm cost, you can disable debugging for all the MATLAB Function blocks in your model.
If the MATLAB Function block uses simulation-only capabilities to call out to the MATLAB interpreter, it incurs all the costs that a MATLAB S-function or Interpreted MATLAB Function block incur. Calling out to the MATLAB interpreter from a MATLAB Function block produces a warning to prevent you from doing so unintentionally.
|MATLAB System||Performs simulation through one of the following:|
|MATLAB S-function||Incurs the same algorithm costs as the Interpreted MATLAB Function block, but with a slightly higher interface cost. Because 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 interpreter for each block method you implement whereas for the Interpreted MATLAB Function block, it calls the MATLAB interpreter only for the mdlOutputs method.|
|C MEX S-function||Simulates via the compiled code and so incurs the same interface cost as standard blocks. The algorithm cost depends on the complexity of the S-function.|
Not all custom block types support code generation with Simulink Coder™.
|Custom Block Type||Code Generation Support|
|Subsystem||Supports code generation.|
|Fcn||Supports code generation.|
|Interpreted MATLAB Function||Does not support code generation.|
|MATLAB Function||Supports code generation. However, if your MATLAB Function block calls out to the MATLAB interpreter, it will build with the Simulink Coder product only if the calls to the MATLAB interpreter 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.|
|MATLAB System||Supports code generation. However, if your MATLAB System block calls out to the MATLAB interpreter, it will build with the Simulink Coder product only if the calls to the MATLAB interpreter 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.|
|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 interpretive mode by calling back to the MATLAB interpreter without implementing the algorithm in TLC. If the MATLAB S-function is a SimViewingDevice, the Simulink Coder product automatically omits the block during code generation.|
|C MEX S-function||Supports code generation. For noninlined S-functions, the Simulink Coder product uses the C MEX function during code generation. However, you must write a TLC-file for the S-function if you need to either inline the S-function or create a wrapper for hand-written code. See Insert S-Function Code in the Simulink Coder User's Guide for more information.|