Graphical Functions for Reusing Logic Patterns and Iterative Loops

What Is a Graphical Function?

A graphical function in a Stateflow chart is a graphical element that helps you reuse control-flow logic and iterative loops. This function is a program you write with flow graphs using connective junctions and transitions. You create a graphical function, fill it with a flow graph, and call the function in the actions of states and transitions.

Back to Top

Why Use a Graphical Function in a Stateflow Chart?

This function helps you to:

• Create modular, reusable logic that you can call anywhere in your chart.

• Track simulation behavior visually during chart animation.

Back to Top

Where to Use a Graphical Function

A graphical function can reside anywhere in a chart, state, or subchart. The location of a function determines its scope, that is, the set of states and transitions that can call the function. Follow these guidelines:

• If you want to call the function only within one state or subchart and its substates, put your graphical function in that state or subchart. That function overrides any other functions of the same name in the parents and ancestors of that state or subchart.

• If you want to call the function anywhere in that chart, put your graphical function at the chart level.

• If you want to call the function from any chart in your model, put your graphical function at the chart level and enable exporting of chart-level graphical functions. For instructions, see Exporting Chart-Level Graphical Functions.

Back to Top

Workflow for Defining a Graphical Function

Creating a Graphical Function

Use these steps to create a graphical function in your chart:

1. Click the graphical function icon in the editor toolbar:

   

2. Move your pointer to the location for the new graphical function in your chart and click to insert the function box.

3. Enter the function signature.

   The function signature specifies a name for your function and the formal names for its arguments and return values. A signature has this syntax:

   [r1, r2,..., rn] = func(a1,a2,..., an)
   

   where func is the name of your function, a₁, a₂, ..., a_n are formal names for its arguments, and r₁, r₂, ..., r_n are formal names for its return values.

   Note   You can define arguments and return values as scalars, vectors, or 2-D matrices of any data type.

4. Click outside of the function box.

The following signature is for a graphical function that has the name f1, which takes three arguments (a, b, and c) and returns three values (x, y, and z).

Note   In the chart, you can change the signature of your graphical function at any time. After you edit the signature, the Model Explorer updates to reflect the changes.

Programming a Graphical Function

To program a graphical function, follow these steps:

1. Click the default transition icon in the editor toolbar:

   

2. Move your pointer inside the function box in your chart and click to insert the default transition and its terminating junction.

3. Enter transition conditions and actions for your graphical function. If necessary, add connective junctions and transitions to your function.

   Note   Connective junctions and transitions are the only graphical elements you can use in a graphical function. Because a graphical function must execute completely when you call it, you cannot use states.

This function box shows a flow graph that returns different products of its arguments.

Defining Graphical Function Data

You must define the data in your graphical function:

1. Open the Model Explorer.

2. Expand the chart object in the Model Explorer, so that you can see the return values and arguments of the function signature as data items that belong to your graphical function.

   

   The Scope column in the Model Explorer indicates the role of each argument or return value. Arguments have the scope Input, and return values have the scope Output.

3. For each function argument and return value, right-click the data row in the Model Explorer and select Properties from the context menu.

4. In the Data properties dialog box for each argument and return value, specify the data properties.

   These rules apply:

   • Each argument and return value can be a scalar or matrix of values.

   • Arguments cannot have initial values.

5. Create any additional data items that your function must have to process its programming.

   Your function can access its own data or data belonging to parent states or the chart. The data items that you create for the function itself can have one of these scopes:

   • Local

     Local data persists from one function call to the next.

   • Temporary

     Temporary data initializes at the start of every function call.

   • Constant

     Constant data retains its initial value through all function calls.

   Note   You can initialize your function data (other than arguments and return values) from the MATLAB workspace. However, you can save only local items to this workspace.

Back to Top

Managing Large Graphical Functions

You can make your graphical function as large as you want, as shown below.

However, if your function grows too large, you can hide its contents by right-clicking inside the function box and selecting Make Contents > Subcharted from the context menu. This option makes your graphical function opaque.

To access the programming of your subcharted graphical function, double-click it. This action dedicates the entire chart window to programming your function.

To access your original chart, click the Back button .

Back to Top

Calling Graphical Functions in States and Transitions

Syntax

Syntax for a function call is the same as that of a function signature, with actual arguments replacing the formal ones specified in a signature. If the data types of the actual and formal argument differ, a function casts the actual argument to the type of the formal argument. See Creating a Graphical Function for information about syntax for a function signature.

Tip   If the formal arguments of a function signature are scalars, verify that inputs and outputs of function calls follow the rules of scalar expansion. For more information, see How Scalar Expansion Works for Functions.

Example

In this example, a state entry action calls a graphical function that returns three products.

Back to Top

Exporting Chart-Level Graphical Functions

Why Export Graphical Functions?

When you export chart-level graphical functions, you extend the scope of your functions to all other charts in your model.

How to Export Chart-Level Graphical Functions

To export graphical functions to your main model:

1. Open the chart where your graphical function resides.

2. Open the Chart properties dialog box.

3. Select Export Chart Level Graphical Functions (Make Global).

4. If your graphical function resides in a library chart, link that chart to your main model.

Rules for Exporting Chart-Level Graphical Functions

 Link library charts to your main model to export graphical functions from libraries

 Do not export graphical functions that contain unsupported inputs or outputs

Example of Exporting Chart-Level Graphical Functions

This example describes how to export graphical functions in library charts to your main model.

1. Create these objects:

   • Add a model named main_model, with a chart named modChart.

     

   • Add a library model named lib1, with a chart named lib1Chart.

     

   • Add a library model named lib2, with a chart named lib2Chart.

     

2. Create these graphical functions in the library charts:

   • For lib1Chart, add this graphical function.

     

   • For lib2Chart, add this graphical function.

     

3. For modChart, add a graphical function and a default transition with a lib1_func action.

   

4. For each chart, follow these steps:

   1. Open the Chart properties dialog box.

   2. In the Chart properties dialog box, select Export Chart Level Graphical Functions (Make Global).

   3. Click OK.

5. Drag lib1Chart and lib2Chart into main_model from lib1 and lib2, respectively. Your main model should look something like this:

   

   Each chart now defines a graphical function that any chart in main_model can call.

6. Open the Model Explorer.

7. In the Model Hierarchy pane of the Model Explorer, navigate to main_model.

8. Add the data x and y to the Stateflow machine:

   1. Select Add > Data.

   2. In the Name column, enter x.

   3. In the Initial Value column, enter 0.

   4. Use the default settings for other properties of x.

   5. Select Add > Data.

   6. In the Name column, enter y.

   7. In the Initial Value column, enter 1.

   8. Use the default settings for other properties of y.

   This step ensures that input and output data are defined globally to support exported graphical functions.

9. Open the Configuration Parameters dialog box.

10. In the Configuration Parameters dialog box, go to the Solver pane.

11. In the Solver options section, make these changes:

    1. For Type, select Fixed-step.

    2. For Solver, select Discrete (no continuous states).

    3. For Fixed-step size, enter 1.

    4. Click OK.

    This step ensures that when you simulate your model, a discrete solver is used. For more information, see Solvers in the Simulink documentation.

What Happens During Simulation.  When you simulate the model, these actions take place during each time step.

How to View the Simulation Results.  To view the simulation results, add a scope to your model. Follow these steps:

1. Open the Simulink Library Browser.

2. From the Simulink/Sinks Library, select the Scope block and add it to main_model.

3. Open the Model Explorer.

4. In the Model Hierarchy pane, navigate to modChart.

5. Add the output data z to the chart:

   1. Select Add > Data.

   2. In the Name column, enter z.

   3. In the Scope column, select Output.

   4. Use the default settings for other properties.

6. For modChart, update the default transition action to read as follows:

   {x = lib1_func(x,y); z = x;}

7. In the model window, connect the outport from modChart to the inport of the Scope block.

   

8. Double-click the Scope block to open the display.

9. Start simulation.

10. After the simulation ends, right-click in the scope display and select Autoscale.

    The results look something like this:

    

Back to Top

Specifying Graphical Function Properties

You can set general properties for your graphical function through its properties dialog box:

1. Right-click your graphical function box.

2. Select Properties from the context menu.

   The properties dialog box for your graphical function appears.

   

The fields in the properties dialog box are:

Back to Top

Maintaining Transition Shapes with Smart Behavior

Grouping Chart Objects with Boxes

Free Stateflow Interactive Kit

Learn how engineers use Stateflow to model state machines in their Simulink models.

Get free kit

Trials Available

Try the latest version of Stateflow.

Get trial software