Stateflow®

Using Graphical Functions to Extend Actions

What Is a Graphical Function?

A graphical function is a program that you write with flow graphs using connective junctions and transitions. You create a graphical function, fill it with a flow graph, and call it many times in the actions of states and transitions.

Back to Top

Why Use a Graphical Function?

A graphical function is easier to create, access, and manage than a textual function, such as a C or MATLAB function that you must define externally. Like a textual function, a graphical function can accept arguments and return values. Unlike a textual function, a graphical function is a native Stateflow object. You use the Stateflow Editor to create a graphical function that resides in your model along with the charts that invoke the function.

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. In particular, graphical functions are visible to the chart, to the parent state and its parents, and to sibling transitions and states. These exceptions apply:

• If the chart containing the function exports its graphical functions, the scope of the function is the entire Stateflow machine, which encompasses all the charts in the model. See Exporting Chart-Level Graphical Functions for more information.

• A function that you define in a state or subchart overrides any functions of the same name in the parents and ancestors of that state or subchart.

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 Stateflow 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   You can use the Stateflow Editor to 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 Stateflow 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. In the Stateflow Editor, select View > Model Explorer.

   The signature for your function appears as a property of its parent chart in the Contents pane of the Model Explorer.

   

2. Expand the parent 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 Stateflow Action Language

Description

To call your graphical function, use Stateflow action language. Any state or transition action in the scope of your function can perform a function call.

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.

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

Perform these steps to export graphical functions to your main model:

1. Open the chart where your graphical function resides.

2. In the Stateflow Editor, select File > Chart Properties.

3. In the Chart properties dialog box, 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 inputs or outputs of enumerated data type

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:

   • For modChart, add this graphical function.

     

   • For lib1Chart, add this graphical function.

     

   • For lib2Chart, add this graphical function.

     

3. For modChart, add a default transition with this action.

   

4. For each chart, follow these steps:

   1. Select File > Chart Properties in the Stateflow Editor.

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

   3. Click OK.

5. Drag lib1Chart and lib2Chart into main_model from lib1 and lib2, respectively.

   

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

6. In the Stateflow Editor, select View > Model Explorer.

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

8. Add the data x to the Stateflow machine as follows:

   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.

9. Add the data y to the Stateflow machine as follows:

   1. Select Add > Data.

   2. In the Name column, enter y.

   3. In the Initial Value column, enter 1.

   4. Use the default settings for other properties.

10. In the Stateflow Editor, select Simulation > Configuration Parameters.

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

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

    1. For Type, choose Fixed-step.

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

    3. For Fixed-step size, enter 1.

    4. Click OK.

    These actions ensure that when you simulate your model, a discrete solver is used. For more information, see Solvers in the Simulink software 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. In the Simulink model window, select View > Library Browser.

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

3. Open the Model Explorer.

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

5. Add the output data z to the Stateflow chart as follows:

   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 Simulink 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

Extending Transitions with Smart Behavior

Using Boxes to Extend Charts