Reuse Functions by Using Atomic Boxes

An atomic box is a graphical object that helps you encapsulate graphical, truth table, MATLAB^®, and Simulink^® functions in a separate namespace. Atomic boxes are not supported in standalone Stateflow^® charts in MATLAB. Atomic boxes allow for:

Faster simulation after making small changes to a function in a chart with many states or levels of hierarchy
Reuse of the same functions across multiple charts and models
Ease of team development for people working on different parts of the same chart
Manual inspection of generated code for a specific function in a chart

An atomic box looks opaque and includes the label Atomic in the upper left corner. If you use a linked atomic box from a library, the label Link appears in the upper left corner.

Example of an Atomic Box

This example uses:

Open Model

This example shows how to use a linked atomic box to reuse a graphical function across multiple charts and models.

The function GetTime is defined in a chart in the library model sf_timer_utils_lib. The graphical function returns the simulation time in C charts where the equivalent MATLAB® function getSimulationTime is not available.

The model sf_timer_function_calls consists of two charts with a similar structure. Each chart contains a pair of states (A and B) and an atomic box (Time) linked from the library chart. The entry action in state A calls the function GetTime and stores its value as t0. The condition guarding the transition from A to B calls the function again and compares its output with the parameter T.

The top model sf_timer_modelref reuses the timer function in multiple referenced blocks. Because there are no exported functions, you can use more than one instance of the referenced block in the top model.

Benefits of Using Atomic Boxes

An atomic box is an atomic subchart applied to a box. It combines the functionality of both features. Atomic boxes:

Improve the organization and clarity of complex charts.
Support usage as library links.
Support the generation of reusable code.
Allow mapping of inputs, outputs, parameters, data store memory, and input events.

Atomic boxes contain only functions. They cannot contain states. Adding a state to an atomic box results in a compilation-time error.

To call a function that resides in an atomic box from a location outside the atomic box, use dot notation to specify its full path:

atomic_box_name.function_name

Using the full path for the function call:

Makes clear the dependency on the function in the linked atomic box.
Avoids pollution of the global namespace.
Does not affect the efficiency of generated code.

Create an Atomic Box

You can create an atomic box by converting an existing box or by linking a chart from a library model. After creating the atomic box, update the mapping of variables by right-clicking the atomic box and selecting Subchart Mappings. For more information, see Map Variables for Atomic Subcharts and Boxes.

Convert a Normal Box to an Atomic Box

To create a container for your functions that allows for faster debugging and code generation workflows, convert an existing box into an atomic box. In your chart, right-click a normal box and select Group & Subchart > Atomic Subchart. The label Atomic appears in the upper left corner of the box.

The conversion process gives the atomic box its own copy of every data object that the box accesses in the chart. Local data is copied as data store memory. The scope of other data, including input and output data, does not change.

Note

If a box contains any states or messages, you cannot convert it to an atomic box.

Link an Atomic Box from a Library

To create a collection of functions for reuse across multiple charts and models, create a link from a library model. Copy a chart in a library model and paste it to a chart in another model. If the library chart contains only functions and no states, it appears as a linked atomic box with the label Link in the upper left corner.

This modeling method minimizes maintenance of reusable functions. When you modify the atomic box in the library, your changes propagate to the links in all charts and models.

If the library chart contains any states, then it appears as a linked atomic subchart in the chart. For more information, see Create Reusable Subcomponents by Using Atomic Subcharts.

Convert an Atomic Box to a Normal Box

Converting an atomic box back to a normal box removes all of its variable mappings by merging subchart-parented data objects with the chart-parented data to which they map.

If the atomic box is a library link, right-click the atomic box and select Library Link > Disable Link.
To convert an atomic box to a subcharted box, right-click the atomic box and clear the Group & Subchart > Atomic Subchart check box.
To convert the subcharted box back to a normal box, right-click the subchart and clear the Group & Subchart > Subchart check box.
If necessary, rearrange graphical objects in your chart.

You cannot convert an atomic box to a normal box if:

The atomic box maps a parameter to an expression other than a single variable name. For example, mapping a parameter data1 to one of these expressions prevents the conversion of an atomic box to a normal box:
- 3
- data2(3)
- data2 + 3
Both of these conditions are true:
- The atomic box contains MATLAB functions or truth table functions that use MATLAB as the action language.
- The atomic box does not map each variable to a variable of the same name in the main chart.

When to Use Atomic Boxes

Debug Functions Incrementally

Suppose that you want to test a sequence of changes to a library of functions. The functions are part of a chart that contains many states or several levels of hierarchy, so recompiling the entire chart can take a long time. If you define the functions in an atomic box, recompilation occurs for only the box and not for the entire chart. For more information, see Reduce the Compilation Time of a Chart.

Reuse Functions

Suppose that you have a set of functions for use in multiple charts and models. The functions reside in the library model to enable easier configuration management. To use the functions in another model, you can either:

Configure the library chart to export functions and create a link to the library chart in the model.
Link the library chart as an atomic box in each chart of the model.

Models that use these functions can appear as referenced blocks in a top model. When the functions are exported, you can use only one instance of that referenced block for each top model. For more information, see Model Reference Requirements and Limitations (Simulink).

With atomic boxes, you can avoid this limitation. Because there are no exported functions in the charts, you can use more than one instance of the referenced block in the top model.

Develop Charts Used by Multiple People

Suppose that multiple people are working on different parts of a chart. If you store each library of functions in a linked atomic box, different people can work on different libraries without affecting the other parts of the chart. For more information, see Divide a Chart into Separate Units.

Inspect Generated Code

Suppose that you want to inspect code generated by Simulink Coder™ or Embedded Coder^® manually for a specific function. You can specify that the code for an atomic box appears in a separate file to avoid searching through unrelated code. For more information, see Generate Code from Atomic Subcharts.