Main Content

Action Node

Process object tokens through MATLAB function or nested activity diagram

Since R2024a

expand all in page
  • Action Node

Description

An action node represents a specific action to execute within an activity diagram. This action is realized either through a MATLAB® function or a nested activity diagram.

Action nodes process incoming object tokens to produce new object tokens. Input object tokens are consumed through input pins, and newly generated object tokens exit through the output pins of an action node.

Action nodes begin execution only when all preconditions are met. That is, input pins must hold a minimum number of object tokens specified by the token multiplicity parameter, and all incoming control flows must offer a control token.

For a roadmap of the activity diagram topics, see Describe System Behavior Using Activity Diagrams.

Action Node Pins

An action node has input and output pins that act as buffers for object tokens.

When an action node begins execution, it consumes object tokens from its input pins. Based on the value of the token multiplicity parameter, an action node executes only after it receives a certain number of tokens at each input pin. The MATLAB function or nested activity diagram uses input object tokens to generate new output object tokens. Output object tokens exit through the output pin.

Action nodes can have two types of input and output pins:

  • Streaming pins

  • Non-streaming pins

Note

Streaming pins can only be configured for action nodes with a nested activity diagram.

Action nodes with both types of pins begin execution only once all pins hold the minimum number of object tokens.

Streaming Pins

A nested activity with streaming input pins starts executing when the token multiplicity for all input pins, including non-streaming pins, is satisfied.

Once the nested activity starts executing, streaming input pins continue to accept all tokens that arrive at the pin and buffer them. Upon arrival, the tokens are forwarded to the corresponding input activity parameter node. An input activity parameter node is a type of object node (a node that directs the flow of object tokens) that routes tokens into a nested activity diagram. When an input pin is created for the action node with a nested activity, a corresponding input activity parameter node is created inside the nested activity.

During execution, the nested activity continues to consume tokens from all the available streaming pins through the corresponding input activity parameters.

Any outputs from the nested activity are accepted by output activity parameter nodes, and then forwarded to the output pin.

A nested activity is considered complete when the following conditions are satisfied:

  • An output activity parameter node receives object tokens, or any final activity node within the nested activity receives a control token.

  • All output pin requirements are met.

Once the multiplicity condition of the streaming input pins is met, the condition will not be reevaluated until the nested activity is restarted. Until then, the upper bound of streaming pins is infinite.

When a nested activity completes execution, all tokens at the output activity parameter nodes are moved to the corresponding output pins. The remaining tokens in the nested activity are destroyed, and the states of all the nodes are reset.

After the nested activity ends, it can restart once again if the same token multiplicity conditions are met as described above.

Non-Streaming Pins

Non-streaming input pins block any incoming object tokens while the action node is executing, causing output object tokens to go into a pending state in the output pins of the previous nodes.

Non-streaming output pins deliver output object tokens only when the action node finishes execution.

Create an Action Node

You can create an action node on the activity diagram canvas in two ways:

  • Drag and drop the Action Node block from the palette on the left to any location on the canvas.

  • Hold down the left mouse button at the desired location on the canvas and drag in any direction. A blue outline of a node appears on the canvas. Select Create Action from the horizontal menu that appears below the outline.

Examples

expand all

Open Live Script

This example shows how you can use an activity diagram containing a nested activity with streaming input pins to model a simple weather station.

Streaming pins enable a nested activity to continue accepting tokens even as it is executing. For more information about streaming pin semantics, see Action Node Pins.

Explore the Model

Open the model. 

modelname = "weatherforecast_ad";
open_system(modelname);

Snapshot of Weather Station activity diagram

The activity diagram contains three main areas:

  • Atmospheric Pressure — Simulates generation of barometer readings for a region. The readings indicate the general weather conditions.

  • Weather Satellite Images — Simulates generation of satellite images over a region. The images display cloud cover that can help predict short-term weather.

  • Weather Station — Receives atmospheric pressure and image data as input and determines a weather forecast.

The behavior of the action nodes in the activity diagram is dictated by the functions in the MATLAB class file, ws, that is included with the example.

Input Generation for Weather Station

The weather station receives inputs from action nodes in the areas, Atmospheric Pressure and Weather Satellite Images.

The Atmospheric Pressure area contains an action node Barometer Data that simulates the continuous generation of barometer readings. After the action node generates a barometer reading, control is passed back to it immediately through a Merge node and the action node generates the next barometer reading and so on. The next action node, Barometer Data Evaluation, outputs a signal based on different threshold values for the input barometer data.

The Weather Satellite Images area contains action node Satellite Image that simulates continuous generation of grayscale images depicting cloud cover over a certain region. Grayscale images are represented by a 3-by-3 matrix assigned to the structure GrayPixel in the Types Editor.

Types Editor showing the GrayPixel structure

The next action node, Image Processing, calculates the mean of the grayscale values of the pixels in an image and outputs a signal based on different threshold values for this mean value.

Execution of Weather Station

The Weather Station nested activity in the Weather Station area accepts inputs representing barometer evaluation data and image evaluation data through streaming pins.

The presence of streaming pins allows the nested activity to consume input data while it executes, unlike nonstreaming pins that wait for an action node or nested activity to finish executing for its designated duration.

Streaming pins allow for a nested activity to execute until a desired outcome is achieved, given that the value provided for Stop Time is sufficient. In this example, Weather Station executes until the final weather forecast has a confidence level of 85% or greater, or until the stop time is reached.

In this example, if you use nonstreaming pins instead, then the nested activity can execute only one round before it requires more inputs for confidence evaluation (unless the first forecast has high confidence). At this point, nonstreaming input pins will not admit more input tokens because the nested activity has not completed execution. Hence, the activity diagram cannot proceed to completion.

The Weather Station nested activity uses its inputs to determine the short-term weather forecast for a region. For example, if the barometer reading is high and the mean of the image pixel values is low, indicating more brightness and less cloudiness, then the weather forecast is Partly Sunny.

Each weather forecast is also associated with a confidence level in a structure named ConfidenceLevel. If the generated confidence level is low or medium, then the corresponding forecast is not displayed. If the confidence generated for a forecast is greater than 0.85, then the forecast is considered final. The final forecast is displayed in the Diagnostic Viewer.

The nested activity terminates when it receives a representative object token at its output activity parameter node. The activity diagram also terminates. At this point, any remaining tokens that arrived to the nested activity are destroyed, and the states of all the nodes are reset.

Run the Model

Simulate the model.

sim("weatherforecast_ad");
    0.6557

Confidence Level for Forecast: Low or Medium.
    0.0318

Confidence Level for Forecast: Low or Medium.
    0.7655

Confidence Level for Forecast: Low or Medium.
    0.1626

Confidence Level for Forecast: Low or Medium.
    0.8909

Confidence Level: High!
Forecast: Partly Sunny.

To clearly view the flow of tokens, you can slow down the animation speed by changing the Animation speed in the Debug tab.

Parameters

expand all

Action Node Parameters

Name of the action node. By default, the activity diagram editor names the first action node placed on the canvas as Action. As more action nodes are added, the editor attaches increasing numerical suffixes to the name Action.

Example: Action2

Indicate how an action node is set up for operation.

  • MATLAB — Contains a pre-existing MATLAB function such as rand or a custom function written in a .m file.

  • Activity — Contains another activity diagram that consumes and produces tokens.

When you select this check box, the names of all input and output pins to the selected action node are displayed.

Name of the MATLAB function that an action node implements. The function can either be a pre-existing MATLAB function or a custom function that you have authored in a .m file.

Example: customfunction_add

Dependencies

To enable this parameter, set Behavior Type to MATLAB in the Property Inspector.

The number of time units an activity diagram spends on the execution of an action node. An activity diagram executes MATLAB functions of an action node at the end of the duration period.

Pin Parameters

Action node pins act as buffers for object tokens during execution of an activity diagram.

Each pin is associated with a certain data type. All tokens of a pin must have the data type associated with the pin.

These are the pin parameters:

Name of the input or output pin. By default, the pin is called InputPin or OutputPin depending on its configuration. As more input or output pins are added to action nodes, increasing numerical suffixes are added to InputPin or OutputPin, respectively.

The number of tokens required at an input pin for the corresponding action node to begin execution. If an input pin has a multiplicity greater than one, it can hold multiple tokens. Upon execution, an action node takes in exactly the number of object tokens specified by the multiplicity parameter.

Token multiplicity applies only to input pins of an action node.

In a MATLAB function defined for an action node, each input and output argument corresponds to an input or output pin, respectively, specified by the argument order of the pin.

For example, if the argument order of an input pin is 2, then this pin represents the second input argument of the MATLAB function.

Enable or disable streaming for the input or output pin of an action node with a nested activity. The value of this streaming control automatically applies to the corresponding input or output activity parameter nodes in the nested activity.

For more information about streaming, see Streaming Pins in Action Node Pins.

Object Type Parameters

An input or output pin can handle object tokens of a certain type. In the Property Inspector, the Object Type section for a pin allows you to specify the type and other properties of an object token.

The type of object held by an action node pin.

  • <owned> — Select properties for an object token, such as type, dimension, complexity, and unit from the Property Inspector.

  • <inherit> — Inherit the object type from the previous pin.

  • custom type — Choose from the list of custom types you created using the Types Editor.

The direction of token flow through a pin of an action node. This parameter is automatically set to Input or Output, depending on whether you create an input pin or output pin, respectively.

Data type of the token. For more information on using MATLAB class type, see Model Complex Objects in Activity Diagrams Using MATLAB Class Tokens.

Dependencies

To enable this parameter, set Name to <owned>.

Dimensions of the token.

Dependencies

To enable this parameter, set Name to <owned>.

Custom unit that you assign to the token.

Dependencies

To enable this parameter, set Name to <owned>.

Complexity of the token.

Dependencies

To enable this parameter, set Name to <owned>.

Version History

Introduced in R2024a

expand all

See Also

Functions

Tools

Blocks

Topics