Main Content

Simulink Functions Overview

What Are Simulink Functions?

A Simulink® function is a computational unit that calculates a set of outputs when provided with a set of inputs. The function header uses a notation similar to programming languages such as MATLAB® and C++. You can define and implement a Simulink function in several ways:

  • Simulink Function block — Function defined using Simulink blocks within a Simulink Function block.

  • Exported Stateflow® graphical function — Function defined with state transitions within a Stateflow chart, and then exported to a Simulink model.

  • Exported Stateflow MATLAB function — Function defined with MATLAB language statements within a Stateflow chart, and then exported to a Simulink model.

  • S-function — Function defined using an S-function block. For an example with an S-function, open sfcndemo_simulinkfunction_getset.

What Are Simulink Function Callers?

A Simulink function caller invokes the execution of a Simulink function from anywhere in a model or chart hierarchy.

  • Function Caller block — Call a function defined in Simulink or exported from Stateflow. See Function Caller.

  • Stateflow chart transition — In a Stateflow chart, call a function defined in Simulink or exported from Stateflow.

  • MATLAB Function block — Call a function from a MATLAB language script.

  • S-Function block — Call a function using system methods. See ssDeclareFunctionCaller and ssCallSimulinkFunction.

  • MATLAB System block — Call a function using a System object™ and the MATLAB language.

Connect to Local Signals

In addition to Argument Inport and Argument Outport blocks, a Simulink Function block can interface to signals in the local environment of the block through Inport or Outport blocks. These signals are hidden from the caller. You can use port blocks to connect and communicate between two Simulink Function blocks or connect to root Inport and Outport blocks that represent external I/O.

Simulink canvas with a Simulink Function block with input, In1, and output, Out1.

You can also connect the Outport blocks to sink blocks that include logging (To File, To Workspace) and viewing (Scope, Display) blocks. However, these blocks execute last after all other blocks.

A Simulink Function block can output a function-call event to an Outport block.

Reusable Logic with Functions

Use functions when you need reusable logic across a model hierarchy. Consider an example where a Simulink Function with reusable logic is defined in a Stateflow chart.

Simulink canvas with a Sine Wave block as input to a Stateflow chart which sends output to a Scope block.

You can move the reusable logic from inside the Stateflow chart to a Simulink Function block. The logic is then reusable by function callers in Simulink subsystems (Subsystem and Model blocks) and in Stateflow charts at any level in the model hierarchy.

Simulink canvas with a Simulink Function block and a Sine Wave block as input to a Stateflow chart which sends output to a Scope block.

The result is added flexibility for structuring your model for reuse.

Note

Input and output argument names (x2, y2) for calling a function from a Stateflow chart do not have to match the argument names in the function prototype (u, y) of a Simulink Function block.

Input/Output Argument Behavior

The function prototype for a Simulink Function block can have identical input and output arguments. For example, a function that filters noise could input a signal and then return the signal after filtering.

mySignal = filter(mySignal)

You can call the function with a Function Caller block and add noise to a test signal to verify the function algorithm.

Simulink canvas with a Sine Wave block and Band-Limited White Noise block connected to an Add block. The Add block is the input to the Function Caller block which sends output to the Scope block. There is also a Simulink Function block which defines the filter function.

When generating code for this model, the input argument for the Simulink Function block passes a pointer to the signal, not a copy of the signal value.

void filter(real_T *rtuy_mySignal)
{
		. . .
		*rtuy_mySignal = model_P.DiscreteFilter_NumCoef * DiscreteFilter_tmp; 
	}

Shared Resources with Functions

Use functions when you model a shared resource, such as a printer. The model slexPrinterExample uses Simulink Function blocks as a common interface between multiple computers and a single Stateflow chart that models a printer process.

To open slexPrinterExample, see Monitoring Ink Status on a Shared Printer Using Simulink Functions.

Simulink canvas with 3 subsystems representing computers. Each computer subsystem is connected to a Mux block which is connected to a Scope block. A Simulink Function block defining the printerInk function and another Simulink Function block defining the addPrintJob function. There is also a Stateflow chart to model the state of the printing.

How a Function Caller Identifies a Function

The function interface uses MATLAB syntax to define its input and output arguments. The name of the function is a valid ANSI® C identifier. The model hierarchy can contain only one function definition with the identified function name. Simulink verifies that:

  • The arguments in the Function prototype parameter for a Function Caller block matches the arguments specified in the function. For example, a function with two input arguments and one output argument appears as:

    y = MyFunction(u1, u2)

  • The data type, dimension, and complexity of the arguments must agree. For a Function Caller block, you can set the Input argument specifications and Output argument specifications parameters, but usually you do not need to specify these parameters manually. Simulink derives the specification from the function.

    The only case where you must specify the argument parameters is when the Function Caller block cannot find the function in the model or in any child model it references. This situation can happen when the Function Caller block and called function are in separate models that are referenced by a common parent model. See Simulink Function Blocks in Referenced Models and Argument Specification for Simulink Function Blocks.

Reasons to Use a Simulink Function Block

Function-Call Subsystem blocks with direct signal connections for triggering provide better signal traceability than Simulink Function blocks, but Simulink Function blocks have other advantages.

  • Eliminate routing of signal lines. The Function Caller block allows you to execute functions defined with a Simulink Function block without a connecting signal line. In addition, functions and their callers can reside in different models or subsystems. This approach eliminates signal routing problems through a hierarchical model structure and allows greater reuse of model components.

  • Use multiple callers to the same function. Multiple Function Caller blocks or Stateflow charts can call the same function. If the function contains state (for example, a Unit Delay block), the state is shared between the different callers.

  • Separate function interface from function definition. Functions separate their interface (input and output arguments) from their implementation. Therefore, you can define a function using a Simulink Function block, an exported graphical function from Stateflow, or an exported MATLAB function from Stateflow. The caller does not need to know how or where the function was implemented.

Choose a Simulink Function or Reusable Subsystem

A consideration for using a Simulink Function block or a Subsystem block has to do with shared state between function calls. A Simulink Function block has shared state while a Subsystem block, even if specified as a reusable function, does not.

  • For a Simulink Function block, when one block has multiple callers, code is always generated for one function. If the Simulink Function block contains blocks with state (for example, Delay or Memory), the state is persistent and shared between function callers. In this case, the order of calls is an important consideration.

  • For a Subsystem block, when a block has multiple instances and is configured as a reusable function, code is usually generated for one function as an optimization. If the Subsystem block contains blocks with state, code is still generated for one function, but a different state variable is passed to the function. State is not shared between the instances.

When Not to Use a Simulink Function Block

Simulink Function blocks allow you to implement functions graphically, but sometimes using a Simulink Function block is not the best solution.

For example, when modeling a PID controller or a digital filter and you have to model the equations defining the dynamic system. Use an S-Function, Subsystem, or Model block to implement systems of equations, but do not use a Simulink Function block, because these conditions can occur:

  • Persistence of state between function calls. If a Simulink Function block contains any blocks with state (for example, Unit Delay or Memory), then their state values are persistent between calls to the function. If there are multiple calls to that function, the state values are also persistent between the calls originating from different callers.

  • Inheriting continuous sample time. A Simulink Function block cannot inherit a continuous sample time. Therefore, do not use this block in systems that use continuous sample times to model continuous system equations.

Tracing Simulink Functions

Visually display connections between a Simulink function and their callers with lines that connect callers to functions:

  • Turning on/off tracing lines — On the Debug tab, under Information Overlays , click Connectors. Select Function Connectors option from the Connectors pane that appears on the Simulink canvas.

  • Direction of tracing lines — Lines connected at the bottom of a block are from a function caller. Lines connected at the top of a block are to a Simulink function or a subsystem containing the function.

    After you turn on tracing lines, a line is displayed connecting the Simulink Function block to the Function Caller block.

    When the Simulink Function block is contained in a subsystem, the line is connected to the Subsystem block.

  • Navigation to functions — A function caller can be within a subsystem.

    When the Function Caller block is contained in a subsystem, the line is connected to the Subsystem block.

    Navigate from a caller in a subsystem to a function by first opening the subsystem, and then clicking a link to the function.

    Simulink canvas with a Sine Wave block connected as input to a Function Caller block which sends output to a Scope block. Below the Function Caller block is a link to the function.

    If the function is at the root level of a model, the function opens. If the function is within a subsystem, the subsystem containing the function opens.

Monitor Ink Status on a Shared Printer Using Simulink Functions

After selecting Function Connectors, the model slexPrinterExample shows the relationships between callers and functions.

In this example, the Function Caller in the Simulink Function block addPrintJob, calls the exported Stateflow function queuePrintJob. The subchart Busy calls the Simulink Function block printerInk. Tracing lines are drawn into and out of the Stateflow chart.

To open slexPrinterExample, see Monitoring Ink Status on a Shared Printer Using Simulink Functions.

In the slexPrinterExample, the tracing lines connect each computer to the addPrintJob Simulink Function block. The printerInk function and the addPrintJob function also have lines connecting to the Stateflow chart.

Highlight and Animate Function Calls

Use animation to highlight function calls.

This example shows a still of an animated Simulink function call.

To access animation, in the toolstrip, on the Debug tab, in the Event Animation section, set the animation speed to Slow, Medium, or Fast.

Event Animation is visible when you have event blocks in your model, such as blocks from the Messages & Events library, Stateflow charts, Function-Call Subsystem blocks, Simulink functions, or SimEvents® blocks.

See Also

| | | |

Related Topics