Create Custom Blocks Using MATLAB System Block and System objects

This topic introduces the MATLAB System block, explains how to use the block to implement your System object™, and describes how to configure the block for your Simulink^® model.

System Objects

System objects let you implement algorithms using the MATLAB^® language. The MATLAB System block enables you to use System objects in Simulink.

Before you use a MATLAB System block, you must have a System object to associate with the MATLAB System block. A System object is a specialized kind of MATLAB class. System objects are designed specifically for implementing and simulating dynamic systems with inputs that change over time. For more information on creating System objects, see Customize System Objects for Simulink.

Why Use the MATLAB System Block?

The MATLAB System block lets you:

Integrate your System objects with Simulink
Share the same System object in MATLAB and Simulink
Unit test your algorithm in MATLAB before using it in Simulink
Customize dialog box customization
Simulate efficiently with better initialization
Handle states
Customize block icons with port labels
Access two simulation modes

System objects exist in other MATLAB products. MATLAB System block supports only the System objects written in the MATLAB language. In addition, if a System object has a corresponding Simulink block, you cannot implement a MATLAB System block for it.

Note

To use your System object in the Simulink environment with MATLAB System block, it must have a constructor that you can call with no arguments. By default, the System object constructor has this capability and you do not need to define your own constructor. However, if you create your own System object constructor, you must be able to call it with no arguments.

Choose the Right Block Type to Include MATLAB Algorithms in Simulink

There are several mechanisms for including MATLAB algorithms in Simulink, such as:

MATLAB System block
MATLAB Function block
Interpreted MATLAB Function block
Level-2 MATLAB S-Function block

For help on choosing the right block, see Comparison of Custom Block Functionality.

Implement a System object in Simulink Using MATLAB System Block

To implement your System object with a custom block behavior in Simulink use the MATLAB System Block and follow these steps:

Create a new model and add the MATLAB System block to your model.
In the block dialog box, from the New list, select Basic, Advanced, or Simulink Extension if you want to create a new System object from a template. Modify the template according to your needs and save the System object.
Enter the full path name for the System object in the System object name. Click the list arrow. If valid System objects exist in the current folder, the names appear in the list.
The MATLAB System block icon and port labels update to those of the corresponding System object. For example, suppose you selected a System object named lmsSysObj in your current folder. The block updates as shown in the figure:
Double-click the block. The MATLAB System block dialog box reflects the System object parameters. The dialog box includes a Source code if the System object uses MATLAB language.
It does not appear if you have:
- Converted the System object to P-code.
- Overridden the default behavior using the getHeaderImpl method.
Click Source code and observe that the public and active properties in the System object appear in the MATLAB System block dialog box as block parameters.
Select how you want the model to simulate the block using the Simulate using parameter. (This parameter appears at the bottom of each MATLAB System block if there is only one tab, or the bottom of the first of multiple tabs.)

Note

After you associate the block with a System object class name, you cannot assign a new System object using the same MATLAB System block dialog box. Instead, right-click the MATLAB System block, select Block Parameters (MATLABSystem) and enter a new class name in System object name.

To implement a block with another System object, right-click the MATLAB System block and select Block Parameters (MATLABSystem). Then, use the block dialog box to identify a new class name in System object name. For more information, see Implement a System object in Simulink Using MATLAB System Block.

Change Block Icon and Port Labels

You can customize the MATLAB System icon, port labels, and dialog box using the Mask Editor or by adding specific methods to your System object.

To design a MATLAB System icon and dialog box, use the Mask Editor (Since R2023b). You can also migrate existing mask customizations to the Mask Editor. This capability eliminates the need to develop or maintain methods in a System object file. For more information, see Customize MATLAB System Icon and Dialog Box Using Mask Editor.

Alternatively, you can add methods to your System object to change the block icon appearance and the block dialog:

When you change the icon appearance and port labels of your block:
- To define the icons, implement the getIconImpl method.
- To define the port labels, implement the getInputNamesImpl method to change the input and getOutputNamesImpl method to change the output port labels.
For an example, see Customize MATLAB System Block Appearance.
If you do not implement these methods, by default the System object uses the input and output port names from the stepImpl method. If you are using nondirect feedthrough, by default the System object uses the input names from updateImpl and the output port names from outputImpl.

To change the MATLAB System block dialog, implement the getPropertyGroupsImpl method in the System object code of the MATLAB System block. Inside the method, implement these classes.

Description	matlab.system.display Method
Define header text for property group.	`matlab.system.display.Header`
Group properties together.	`matlab.system.display.Section`
Group properties into a separate tab.	`matlab.system.display.SectionGroup`

Change the MATLAB System Block Icon to an Image

You can change the image of MATLAB System block in MATLAB Editor. For a list of accepted image files, see image. To use an existing image file for the MATLAB System block:

Double-click your MATLAB System block.
In the block dialog box, click the Source code. The MATLAB Editor that contains the System object code opens.
In the MATLAB Editor, from the System Block drop-down list, select Add Image Icon.
In the Add image icon dialog box, click Browse to select an image of your choice.
Click OK to insert the corresponding code for the getIconImpl method in your System object.

For more information, see Customize System Block Appearance Programmatically.

Specify Sample Time for MATLAB System Block

The sample time of a block is a parameter that indicates when the block produces an output, and eventually updates its internal state. To specify sample time for a MATLAB System block, implement the getSampleTimeImpl method with a call to createSampleTime method. To query the MATLAB System block for current sample time and simulation time, use the getSampleTime and getCurrentTime methods. For more information, see Specify Sample Time for MATLAB System Block System Objects.

To specify a discrete sample time, in the createSampleTime method, set 'Type' to 'Discrete' and set the 'SampleTime' property.
To specify an inherited sample time, in the createSampleTime, set 'Type' to 'Inherited'. When using an inherited sample time, you can alter or error out on specific sample times by specifying the 'AlternatePropagation' or 'ErrorOnPropagation' Name-Value pair.
To specify the fixed-in-minor-step sample time, in the createSampleTime, set 'Type' to 'Fixed In Minor Step'.
To configure a block to specify controllable sample time with a resolution T_base, where T_base is the smallest allowable time interval between block executions. A block using controllable sample time can be dynamically set to execute at n multiples of T_base, then the block's next execution is
T_next = n T_base + T (1)
To specify T_base in MATLAB System block, in the createSampleTime method, set 'Type' to 'Controllable' and set the 'TickTime' property to T_base. You can set the n in your MATLAB System block using setNumTicksUntilNextHit.

For more information, see Types of Sample Time. To see an example on how to control the sample time of the MATLAB System block using System object methods, see Specify Sample Time for MATLAB System Block System Objects.

Block Simulation Modes

You can use MATLAB System blocks in Simulink models for simulation via interpreted execution or code generation.

With interpreted execution, the model simulates the block using the MATLAB execution engine.
Note
With interpreted execution, if you set the Use division for fixed-point net slope computation parameter to On or Use division for reciprocals of integers only in the Configuration Parameters dialog box, you might get unoptimized numeric results. These unoptimized numeric results are because MATLAB code does not support this parameter.
With code generation, the model simulates the block using the generated code (requires the use of the subset of MATLAB code supported for code generation). For a list of supported functions, see Functions and Objects Supported for C/C++ Code Generation.

Interpreted Execution vs. Code Generation

Implementing a MATLAB System block with a valid System object class name enables the Simulate using parameter. This parameter appears at the bottom of the MATLAB System block dialog if there is only one tab, or the bottom of the first of multiple tabs. Use the Simulate using parameter to control how the block simulates. This table describes how to choose the right value for your purpose.

Action	Select	Pros	Cons
Upon first model run, simulate and generate code for MATLAB System using only the subset of MATLAB functions supported for code generation. Choosing this option causes the simulation to run the generated code.	`Code generation` (default)	Potentially better performance.	System object is limited to the subset of MATLAB functions supported for code generation. Simulation may start more slowly.
Simulate model using all supported MATLAB functions. Choosing this option can slow simulation performance.	`Interpreted execution`	System object can contain any supported MATLAB function. Faster startup time.	Potentially slower performance. If the MATLAB functions in the System object do not support code generation, the System object must contain propagation methods.

To take advantage of faster performance, consider using propagation methods in your System object. For more information, see Add and Implement Propagation Methods.

Note

If your Simulink model is set up to simulate in Normal mode and if you use MATLAB System block via code generation, individual MATLAB System blocks can take advantage of acceleration via code generation. If the Simulink model is set up to simulate in accelerator mode or any of the other target modes, MATLAB System block's Simulate using parameter does not have any effect. However, there is one exception, if the model is set up to simulate in accelerator mode and you use MATLAB System block with interpreted execution mode, the block will run in interpreted execution mode.

Simulation Using Code Generation

Simulating the MATLAB System block using code generation requires that you have a compatible compiler installed in your system. To see a list of supported compilers, open Supported and Compatible Compilers, click the tab that corresponds to your operating system, find the Simulink Product Family table, and go to the For Model Referencing, Accelerator mode, Rapid Accelerator mode, and MATLAB Function blocks column.

A model can have multiple copies of the same MATLAB System block. Blocks are considered the same if they:

Use the same System object.
Have inputs and tunable parameters that have identical signals, data types, and complexities.
Have nontunable parameters that have the same value.

When the model has multiple copies of the same block, the software does not regenerate the code for each block. The model reuses the code from the first time code was generated for the block.

Default Input Signal Attributes of MATLAB System Block

If a MATLAB System block has one or more inputs that are not connected to another block’s output port or connected to a port that has underspecified attributes, the default input signal attributes for the unspecified attributes are:

Data Attribute	Default
Data Type	double
Size	[1 1] scalar
Complexity	real

Use Nonvirtual Buses with MATLAB System Block

The MATLAB System block supports nonvirtual buses as input and output signals. The corresponding System object input or output must be a MATLAB structure whose fields match those defined by the nonvirtual bus. If the System object output is a MATLAB structure, it must define propagator methods. In addition, the getOutputDataTypeImpl method must return the name of the corresponding bus object. This bus object must exist in the base workspace or a data dictionary linked to the model. For an example, see Using Buses with MATLAB System Blocks.

Note

If the output is the same bus type as the input, do not use the propagatedInputDataType method to obtain the name of the bus object. Instead, you must return the name of the bus object directly.

MATLAB System Block Limitations

These capabilities are not supported.

Category	Limitation	Workaround
System Objects	Tunable character vector properties of the System object are nontunable parameters in the MATLAB System block.	—
Data Types	The MATLAB System block does not support virtual buses as input or output. System objects cannot use user-defined opaque data types.	—
Sample Time	Cannot use MATLAB System blocks to model continuous time or multirate systems.	—
Linearizations	Cannot use Jacobian based linearization.	—
Global Variables	Global variables defined in the model Configuration Parameters Simulation Target > Custom Code pane and referenced by the System object are not shared with Stateflow^® and the MATLAB Function block.	Turn on the Import custom code option in the Simulation Target pane of the Configuration Parameters dialog box.
Debugging	MATLAB debugging for code-generation-based simulation.	Set the MATLAB System block Simulate using parameter to `Interpreted execution`, and then debug. When you are done, set Simulate using back to `Code generation`.
Fixed-Point Tool	The Fixed-Point Tool does not return design min/max, min/max logging, or autoscaling information for MATLAB System blocks.	—
Model coverage analysis (Simulink Coverage™ software)	Simulink Coverage cannot perform model analysis for MATLAB System block with Simulate using parameter set to `Interpreted execution`.	—

MATLAB System Block and System Objects Examples

For examples of MATLAB System and System objects, see:

Example	Description
Define System Object for Use in Simulink	This example shows how to develop a System object to use in a MATLAB System block and interactively preview the block dialog box.
Customize MATLAB System Block Appearance	This example shows how to customize the appearance of the MATLAB System block.
Customize MATLAB System Block Dialog	This example shows how to customize the MATLAB System block dialog.
Specify Output Characteristics of MATLAB System Block	This example shows how to specify output size, data type and complexity of a MATLAB System block.
Specify Sample Time for MATLAB System Block System Objects	This example shows how to control the sample time of the MATLAB System block using System object methods.
Create Moving Average Filter Block with System Object	This example shows how to extend a System object to use in Simulink®.