MATLAB Function Block Editor

Customizing the MATLAB Function Block Editor

Use the toolbar icons to customize the appearance of the MATLAB Function Block Editor in the same manner as the MATLAB® editor. See Basic Settings.

MATLAB Function Block Editor Tools

Use the following tools to work with the MATLAB Function block:

Tool ButtonDescription

Edit Data

Opens the Ports and Data Manager dialog to add or modify arguments for the current MATLAB Function block (see Ports and Data Manager).

View Report

Opens the MATLAB Function report for the MATLAB Function block. For more information, see MATLAB Function Reports.

Simulation Target

Opens the Simulation Target pane in the Configuration Parameters dialog to enable debugging or include custom code. See Enabling and Disabling Debugging for more information on debugging

Go To Diagram

Displays the MATLAB function in its native diagram without closing the editor.

See Defining Inputs and Outputs for an example of defining an input argument for a MATLAB Function block.

Editing and Debugging MATLAB Function Block Code

Manual Indenting

To indent a block of code manually:

  1. Highlight the text that you would like to indent.

  2. Select one of the Indent tools on the Editor tab:

    ToolDescription
    Applies smart indenting to selected text.
    Move selected text right one indent level.
    Move selected text left one indent level.

Opening a Selection

You can open a local function, function, file, or variable from within a file in the MATLAB Function Block Editor.

To open a selection:

  1. Position the cursor in the name of the item you would like to open.

  2. Right-click and select Open <selection> from the context menu.

The Editor chooses the appropriate tool to open the selection. For more information, refer to Manage Files and Folders.

    Note:   If you open a MATLAB Function block input or output parameter, the Ports and Data Manager opens with the selected parameter highlighted. You can use the Ports and Data Manager to modify parameter attributes. For more information, refer to Ports and Data Manager.

Evaluating a Selection

You can use the Evaluate a Selection menu option to report the value for a MATLAB function variable or equation in the MATLAB window during simulation.

To evaluate a selection:

  1. Highlight the variable or equation that you would like to evaluate.

  2. Hold the mouse over the highlighted text and then right-click and select Evaluate Selection from the context menu. (Alternatively, select Evaluate Selection from the Text menu).

When you reach a breakpoint, the MATLAB command Window displays the value of the variable or equation at the Command Line Debugger prompt.

debug>> stdev
 
	1.1180

debug>> 

    Note:   You cannot evaluate a selection while MATLAB is busy, for example, running a MATLAB file.

Setting Data Scope

To set the data scope of a MATLAB Function block input parameter:

  1. Highlight the input parameter that you would like to modify.

  2. Hold the mouse over the highlighted text and then right-click and select Data Scope for <selection> from the context menu.

  3. Select:

    • Input if your input data is provided by the Simulink® model via an input port to the MATLAB Function block.

    • Parameter if your input is a variable of the same name in the MATLAB or model workspace or in the workspace of a masked subsystem containing this block.

For more information, refer to Setting General Properties.

Ports and Data Manager

The Ports and Data Manager provides a convenient method for defining objects and modifying their properties in a MATLAB Function block that is open and has focus.

The Ports and Data Manager provides the same data definition capabilities for individual MATLAB Function blocks as the Model Explorer provides across the model hierarchy (see Model Explorer Overview).

Ports and Data Manager Dialog Box

The Ports and Data Manager dialog box allows you to add and define data arguments, input triggers, and function call outputs for MATLAB Function blocks. Using this dialog, you can also modify properties for the MATLAB Function block and the objects it contains.

The dialog box consists of two panes:

  • The Contents (left) pane lists the objects that have been defined for the MATLAB Function block.

  • The Dialog (right) pane displays fields for modifying the properties of the selected object.

Properties vary according to the scope and type of the object. Therefore, the Ports and Data Manager properties dialogs are dynamic, displaying only the property fields that are relevant for the object you add or modify.

When you first open the dialog box, it displays the properties of the MATLAB Function block.

Opening the Ports and Data Manager

To open the Ports and Data Manager from the MATLAB Function Block Editor, select Edit Data on the Editor tab. The Ports and Data Manager appears for the MATLAB Function block that is open and has focus.

Ports and Data Manager Tools

The following tools are specific to the Ports and Data Manager:

Tool ButtonDescription

Go to Block Editor

Displays the MATLAB function in the MATLAB Function Block Editor.

Show Block Dialog

Displays the default MATLAB function properties (see MATLAB Function Block Properties). Use this button to return to the settings used by the block after viewing data associated with the block arguments.

MATLAB Function Block Properties

This section describes each property of a MATLAB Function block.

Name.  Name of the MATLAB Function block, following the same naming conventions as for Simulink blocks (see Manipulate Block Names).

Update method.   Method for activating the MATLAB Function block. You can choose from the following update methods:

Update MethodDescription
Inherited
(default)
Input from the Simulink model activates the MATLAB Function block.

If you define an input trigger, the MATLAB Function block executes in response to a Simulink signal or function-call event on the trigger port. If you do not define an input trigger, the MATLAB Function block implicitly inherits triggers from the model. These implicit events are the sample times (discrete or continuous) of the signals that provide inputs to the chart.

If you define data inputs, the MATLAB Function block samples at the rate of the fastest data input. If you do not define data inputs, the MATLAB Function block samples as defined by its parent subsystem's execution behavior.
DiscreteThe MATLAB Function block is sampled at the rate you specify as the block's Sample Time property. An implicit event is generated at regular time intervals corresponding to the specified rate. The sample time is in the same units as the Simulink simulation time. Note that other blocks in the model can have different sample times.
ContinuousThe Simulink software wakes up (samples) the MATLAB Function block at each step in the simulation, as well as at intermediate time points that can be requested by the solver. This method is consistent with the continuous method.

Saturate on integer overflow.  Option that determines how the MATLAB Function block handles overflow conditions during integer operations:

SettingAction When Overflow Occurs
Enabled
(default)
Saturates an integer by setting it to the maximum positive or negative value allowed by the word size. Matches MATLAB behavior.
DisabledIn simulation mode, generates a run-time error. For Simulink Coder™ code generation, the behavior depends on your C language compiler.

    Note:   The Saturate on integer overflow option is relevant only for integer arithmetic. It has no effect on fixed-point or double-precision arithmetic.

When you enable Saturate on integer overflow, MATLAB adds additional checks during code generation to detect integer overflow or underflow. Therefore, it is more efficient to disable this option if you are sure that integer overflow and underflow will not occur in your MATLAB Function block code.

Even when you disable this option, the code for a simulation target checks for integer overflow and underflow. If either condition occurs, simulation stops and an error is generated. If you enable debugging for the MATLAB Function block, the debugger displays the error and lets you examine the data.

If you did not enable debugging, the block generates a run-time error:

Overflow detected. Enable debugging for more information.

Note that the code generated by Simulink Coder does not check for integer overflow or underflow and, therefore, may produce unpredictable results when Saturate on integer overflow is disabled. In this situation, it is recommended that you simulate first to test for overflow and underflow before generating code.

Lock Editor.  Option for locking the MATLAB Function Block Editor. When enabled, this option prevents users from making changes to the MATLAB Function block.

Treat these inherited Simulink signal types as fi objects.  

Setting that determines whether to treat inherited fixed-point and integer signals as Fixed-Point Designer™ fi objects (Ways to Construct fi Objects).

  • When you select Fixed-point, the MATLAB Function block treats all fixed-point inputs as Fixed-Point Designer fi objects.

  • When you select Fixed-point & Integer, the MATLAB Function block treats all fixed-point and integer inputs as Fixed-Point Designer fi objects.

MATLAB Function block fimath.   Setting that defines fimath properties for the MATLAB Function block. The block associates the fimath properties you specify with the following objects:

  • All fixed-point and integer input signals to the MATLAB Function block that you choose to treat as fi objects.

  • All fi and fimath objects constructed in the MATLAB Function block.

You can select one of the following options for the MATLAB Function block fimath.

SettingDescription
Same as MATLAB

When you select this option, the block uses the same fimath properties as the current default fimath. The edit box appears dimmed and displays the current global fimath in read-only form.

Specify other

When you select this option, you can specify your own fimath object in the edit box. You can do so in one of two ways:

  • Constructing the fimath object inside the edit box.

  • Constructing the fimath object in the MATLAB or model workspace and then entering its variable name in the edit box. If you use this option and plan to share your model with others, make sure you define the variable in the model workspace. See Sharing Models with Fixed-Point MATLAB Function Blocks.

For more information on fimath objects, see fimath Object Construction.

Description.  Description of the MATLAB Function block.

Document link.  Link to documentation for the MATLAB Function block. To document a MATLAB Function block, set the Document link property to a Web URL address or MATLAB expression that displays documentation in a suitable format (for example, an HTML file or text in the MATLAB Command Window). The MATLAB Function block evaluates the expression when you click the blue Document link text.

Adding Data to a MATLAB Function Block

You can define data arguments for MATLAB Function blocks using the following methods:

MethodFor DefiningReference
Define data directly in the MATLAB Function block codeInput and output dataSee Defining Inputs and Outputs.
Use the Ports and Data ManagerInput, output, and parameter data in the MATLAB Function block that is open and has focusSee Defining Data in the Ports and Data Manager.
Use the Model ExplorerInput, output, and parameter data in MATLAB Function blocks at all levels of the model hierarchySee Model Explorer Overview

Defining Data in the Ports and Data Manager.  To add a data argument and modify its properties, follow these steps:

  1. In the Ports and Data Manager, select Add > Data

    The Ports and Data Manager adds a default definition of the data to the MATLAB Function block.

  2. Modify data properties.

  3. Return to the MATLAB Function block properties at any time by selecting Tools > Block Dialog.

Setting General Properties.  You can set the following properties in the General tab:

PropertyDescription
NameName of the data argument, following the same naming conventions used in MATLAB.
Scope

Where data resides in memory, relative to its parent. Scope determines the range of functionality of the data argument. You can set scope to one of the following values:

  • Parameter— Specifies that the source for this data is a variable of the same name in the MATLAB or model workspace or in the workspace of a masked subsystem containing this block. If a variable of the same name exists in more than one of the workspaces visible to the block, the variable closest to the block in the workspace hierarchy is used (see Model Workspaces).

  • Input— Data provided by the model via an input port to the MATLAB Function block.

  • Output— Data provided by the MATLAB Function block via an output port to the model.

  • Data Store Memory— Data provided by a Data Store Memory block in the model.

For more information, see Defining Inputs and Outputs and Add Parameter Arguments.

PortIndex of the port associated with the data argument. This property applies only to input and output data.
TunableIndicates whether the parameter used as the source of this data item is tunable (see Tunable Parameters). This property applies only to parameter data. Clear this option if the parameter must be a constant expression, such as for MATLAB toolbox functions supported for code generation (see Functions and Objects Supported for C and C++ Code Generation — Alphabetical List).
Data must resolve to Simulink signal objectSpecifies that the data argument must resolve to a Simulink signal object. This property applies only to output data. See Symbol Resolution for more information.
SizeSize of the data argument. Size can be a scalar value or a MATLAB vector of values. Size defaults to –1, which means that it is inherited, as described in Inheriting Argument Sizes from Simulink. This property does not apply to Data Store Memory data. For more details, see Size Function Arguments.
Variable SizeIndicates whether the size of this data item is variable. This property does not apply to Data Store Memory data.
ComplexityIndicates real or complex data arguments. You can set complexity to one of the following values:
  • Off— Data argument is a real number

  • On— Data argument is a complex number

  • Inherited— Data argument inherits complexity based on its scope. Input and output data inherit complexity from the Simulink signals connected to them; parameter data inherits complexity from the parameter to which it is bound.

Sampling modeSpecifies how an output signal propagates through a model. This property applies only to data with scope equal to Output. You can set sampling mode to one of the following values:
  • Sample based: Propagate the signal sample by sample (default)

  • Frame based: Propagate the signal in batches of samples

TypeType of data object. You can specify the data type by:
  • Selecting a built-in type from the Type drop down list.

  • Entering an expression in the Type field that evaluates to a data type (see Data Types).

  • Using the Data Type Assistant to specify a data Mode, then specifying the data type based on that mode.

      Note:   To display the Data Type Assistant, click the Show data type assistant button:

For more information, see Specifying Argument Types.
Limit range

Specify the range of acceptable values for input or output data. The MATLAB Function block uses this range to validate the input or output as it enters or leaves the block. You can enter an expression or parameter that evaluates to a numeric scalar value.

  • Minimum — The smallest value allowed for the data item during simulation. The default value is -inf.

  • Maximum — The largest value allowed for the data item during simulation. The default value is inf.

Setting Description Properties.  You can set the following properties on the Description tab:

PropertyDescription
Save final value to base workspaceThe MATLAB Function block assigns the value of the data argument to a variable of the same name in the MATLAB base workspace at the end of simulation.
DescriptionDescription of the data argument.
Document linkLink to documentation for the data argument. You can enter a Web URL address or a MATLAB command that displays documentation in a suitable format, such as an HTML file or text in the MATLAB Command Window. When you click the blue text, Document link, displayed at the bottom of the Data properties dialog, the MATLAB Function block evaluates the link and displays the documentation.

Adding Input Triggers to a MATLAB Function Block

An input trigger is an event on the input port that causes the MATLAB Function block to execute. See Create a Triggered Subsystem.

You can define the following types of triggers in MATLAB Function blocks:

  • Rising

  • Falling

  • Either (rising or falling)

  • Function call

For a description of each trigger type, see Setting Input Trigger Properties.

Use the Ports and Data Manager to add input triggers to a MATLAB Function block that is open and has focus. To add an input trigger and modify its properties, follow these steps:

  1. In the Ports and Data Manager, select Add > Input Trigger.

    The Ports and Data Manager adds a default definition of the new input trigger to the MATLAB Function block and displays the Trigger properties dialog.

  2. Modify trigger properties.

  3. Return to the MATLAB Function block properties at any time by selecting Tools > Block Dialog.

The Trigger Properties Dialog.  The Trigger properties dialog in the Ports and Data Manager allows you to set and modify the properties of input triggers in MATLAB Function blocks.

To open the Trigger properties dialog, select an input trigger in the Contents pane.

Setting Input Trigger Properties.  You can set the following properties in the Trigger properties dialog:

PropertyDescription
NameName of the input trigger, following the same naming conventions used in MATLAB.
PortIndex of the port associated with the input trigger. The default value is 1.
TriggerType of event that triggers execution of the MATLAB Function block. You can select one of the following types of triggers:
  • Rising (default) — Triggers execution of the MATLAB Function block when the control signal rises from a negative or zero value to a positive value (or zero if the initial value is negative).

  • Falling— Triggers execution of the MATLAB Function block when the control signal falls from a positive or zero value to a negative value (or zero if the initial value is positive).

  • Either— Triggers execution of the MATLAB Function block when the control signal is either rising or falling.

  • Function call— Triggers execution of the MATLAB Function block from a block that outputs function-call events, or from an S-function

DescriptionDescription of the input trigger.
Document linkLink to documentation for the input trigger. You can enter a Web URL address or a MATLAB command that displays documentation in a suitable format, such as an HTML file or text in the MATLAB Command Window. When you click the blue text that reads Document link displayed at the bottom of the Trigger properties dialog, the MATLAB Function block evaluates the link and displays the documentation.

Adding Function Call Outputs to a MATLAB Function Block

A function call output is an event on the output port of a MATLAB Function block that causes a function-call subsystem in the Simulink model to execute. A function-call subsystem is a subsystem that another block can invoke directly during a simulation. See Create a Function-Call Subsystem.

Use the Ports and Data Manager to add and modify function call outputs to a MATLAB Function block that is open and has focus. To add a function call output and modify its properties, follow these steps:

  1. In the Ports and Data Manager, select Add > Function Call Output.

    The Ports and Data Manager adds a default definition of the new function call output to the MATLAB Function block and displays the Function Call properties dialog.

  2. Modify function call output properties.

  3. Return to the MATLAB Function block properties at any time by selecting Tools > Block Dialog.

The Function Call Properties Dialog.  The Function Call properties dialog in the Ports and Data Manager allows you to edit the properties of function call outputs in MATLAB Function blocks.

To open the Function Call properties dialog, select a function call output in the Contents pane.

Setting Function Call Output Properties.  You can set the following properties in the Function Call properties dialog:

PropertyDescription
NameName of the function call output, following the same naming conventions used in MATLAB.
PortIndex of the port associated with the function call output. Function call output ports are numbered sequentially after input and output ports.
DescriptionDescription of the function call output.
Document linkLink to documentation for the function call output. You can enter a Web URL address or a MATLAB command that displays documentation in a suitable format, such as an HTML file or text in the MATLAB Command Window. When you click Document link displayed at the bottom of the Function Call properties dialog, the MATLAB Function block evaluates the link and displays the documentation.

Was this topic helpful?