Documentation

Specify Initial Conditions for Bus Signals

Bus Signal Initialization

Bus signal initialization is a special kind of signal initialization. For general information about initializing signals, see Initialize Signals and Discrete States.

Bus signal initialization specifies the bus element values that Simulink® uses for the first execution of a block that uses that bus signal. By default, the initial value for a bus element is the ground value (represented by 0). Bus initialization, as described in this section, involves specifying nonzero initial conditions (ICs).

You can use bus signal initialization features to:

  • Specify initial conditions for signals that have different data types

  • Apply a different initial condition for each signal in the bus

  • Specify initial conditions for a subset of signals in a bus without specifying initial conditions for all the signals

  • Use the same initial conditions for multiple blocks, signals, or models

Blocks that Support Bus Signal Initialization

You can initialize bus signal values that input to a block, if that block meets both of these conditions:

  • It has an initial value or initial condition block parameter

  • It supports bus signals

The following blocks support bus signal initialization:

  • Data Store Memory

  • Memory

  • Merge

  • Outport (when the block is inside a conditionally executed context)

  • Rate Transition

  • Unit Delay

For example, the Unit Delay block is a bus-capable block and the Block Parameters dialog box for the Unit Delay block has an Initial conditions parameter.

Initialization Is Not Supported for Bus Signals with Variable-Size or Frame-Based Elements

You cannot initialize a bus that has:

  • Variable-size signals

  • Frame-based signals

Workflow for Initializing Bus Signals Using Initial Condition Structures

You need to set up your model properly to use initial condition structures to initialize bus signals. The general workflow involves the tasks listed in the following table. You can vary the order of the tasks, but before you update the diagram or run a simulation, you need to ensure your model is set up properly.

TaskDocumentation
Define an IC structureCreate Initial Condition (IC) Structures
Use an IC structure to specify a nonzero initial condition.Three Ways to Initialize Bus Signals Using Block Parameters
Set Configuration Parameters dialog box diagnosticsSetting Diagnostics to Support Bus Signal Initialization

Create Initial Condition (IC) Structures

You can create partial or full IC structures to represent initial values for a bus signal. Create an IC structure by either:

  • Defining a MATLAB® structure in the MATLAB base or Simulink model workspace

  • Specifying an expression that evaluates to a structure for the initial condition parameter in the Block Parameters dialog box for a block that supports bus signal initialization

For information about defining MATLAB structures, see Create a Structure Array in the MATLAB documentation.

Full and Partial IC Structures

A full IC structure provides an initial value for every element of a bus signal. This IC structure mirrors the bus hierarchy and reflects the attributes of the bus elements.

A partial IC structure provides initial values for a subset of the elements of a bus signal. If you use a partial IC structure, during simulation, Simulink creates a full IC structure to represent all of the bus signal elements, assigning the respective ground value to each element for which the partial IC structure does not explicitly assign a value.

Specifying partial structures for block parameter values can be useful during the iterative process of creating a model. Partial structures enable you to focus on a subset of signals in a bus. When you use partial structures, Simulink initializes unspecified signals implicitly.

Specifying full structures during code generation offers these advantages:

  • Generates more readable code

  • Supports a modeling style that explicitly initializes all signals

Match IC Structure Values to Corresponding Bus Element Data Characteristics

The field that you specify in an IC structure must match the following data attributes of the bus element exactly:

  • Name

  • Dimension

  • Complexity

For example, if you define a bus element to be a real [2x2] double array, then in the IC structure, define the value to initialize that bus element to be a real [2x2] double array.

You must explicitly specify fields in the IC structure for every bus element that has an enumerated (enum) data type.

When you define a partial IC structure:

  • Include only fields that are in the bus.

  • You can omit fields that are in the bus.

  • Make the field in the IC structure correspond to the nesting level of the bus element.

  • Within the same nesting level in both the structure and the bus, you can specify the structure fields in a different order than the order of the elements in the bus.

    Note:   The value of an IC structure must lie within the design minimum and maximum range of the corresponding bus element. Simulink performs this range checking during an update diagram and when you run the model.

Examples of Partial Structures

Suppose you have a bus, Top, composed of three elements: A, B, and C, with these characteristics:

  • A is a nested bus, with two signal elements.

  • B is a single signal.

  • C is a nested bus that includes bus A as a nested bus.

The following model, ex_busic includes the nested Top bus. The screen capture below shows the model after it has been updated. Open the model.

The following diagram summarizes the Top bus hierarchy and the data type, dimension, and complexity of the bus elements .

Top
   A (sub1)
      A1 (double)
      A2 (int8, 5x1, complex)
   B (double)
   C (sub2)
      C1 (int16)
      C2 (sub1)  
         A1 (double)
         A2 (int8, 5x1, complex)

Valid partial IC structures.  In the following examples, K is an IC structure specified for the initial value of the Unit Delay block. The IC structure corresponds to the Top bus in the ex_busic model.

The following table shows valid initial condition specifications.

Valid SyntaxDescription
K.A.A1 = 3

Initializes the bus element Top.A.A1 using the value 3.

K = struct('C',struct('C1',int16(4)))

The bus element Top.C.C1 is int16. The corresponding structure field explicitly specifies int16(4). Alternatively, you could specify the field value as 4 without specifying an explicit data type.

K = struct('B',3,'A',struct('A1',4))

Bus element Top.B and Top.A are at the same nesting level in the bus. For bus elements at the same nesting level, the order of corresponding structure fields does not matter.

Invalid partial IC structures.  In the following examples, K is an IC structure specified for the initial value of the Unit Delay block. The IC structure corresponds to the Top bus in the ex_busic model.

These three initial condition specifications are not valid:

Invalid SyntaxReason the Syntax Is Invalid
K.A.A2 = 3

Value dimension and complexity do not match. The bus element Top.A.A2 is 5x1, but K.A.A2 is 1x1; Top.A.A2 is complex, but K.A.A2 is real.

K.C.C2 = 3

You cannot use a scalar value to initialize IC substructures.

K = struct('B',3,'X',4)

You cannot specify fields that are not in the bus (X does not exist in the bus).

Creating Full IC Structures Using Simulink.Bus.createMATLABStruct

Use the Simulink.Bus.createMATLABStruct function to streamline the process of creating a full MATLAB initial condition structure with the same hierarchy, names, and data attributes as a bus signal. This function fills all the elements that you do not specify with the ground values for those elements.

You can use several different kinds of input with the Simulink.Bus.createMATLABStruct function, including

  • A bus object name

  • An array of port handles

You can invoke the Simulink.Bus.createMATLABStruct function from the Bus Editor. Select the bus object for which you want to create a full MATLAB structure, and then use one of these approaches:

  • Select the File > Create a MATLAB structure menu item.

  • Click the Create a MATLAB structure icon ( ) from the toolbar.

You can then edit the MATLAB structure in the MATLAB Editor.

See the Simulink.Bus.createMATLABStruct documentation for details.

Check for Partial Structures with Model Advisor

To detect when structure parameters are not consistent in shape (hierarchy and names) with the associated bus signal, in the Simulink Editor, use the Analysis > Model Advisor > By Product > Simulink Check structure parameter usage with bus signals check. This check identifies partial IC structures.

Control Data Types of Structure Fields

If any of the signal elements of the target bus use a data type other than double, you can use different techniques to control the data types of the fields of initial condition structures. The technique that you choose can influence the efficiency and readability of the generated code. See Control Data Types of Initial Condition Structure Fields.

Three Ways to Initialize Bus Signals Using Block Parameters

Initialize a bus signal by setting the initial condition parameter for a block that receives a bus signal as input and that supports bus initialization (see Blocks that Support Bus Signal Initialization).

For example, the Block Parameters dialog box for the Unit Delay block has an Initial conditions parameter.

For a block that supports bus signal initialization, you can replace the default value of 0 using one of these approaches:

All three approaches require that you define an IC structure (see Create Initial Condition (IC) Structures). You cannot specify a nonzero scalar value or any other type of value other than 0, an IC structure, or Simulink.Parameter object to initialize a bus signal.

Defining an IC structure as a MATLAB variable, rather than specifying the IC structure directly in the block parameters dialog box offers several advantages, including:

  • Reuse of the IC structure for multiple blocks

  • Using the IC structure as a tunable parameter in the generated code

MATLAB Structure for Initialization

You can initialize a bus signal using a MATLAB structure that explicitly defines the initial conditions for the bus signal.

For example, in the Initial conditions parameter of the Unit Delay block, you could type in a structure such as shown below:

MATLAB Variable for Initialization

You can initialize a bus signal using a MATLAB variable that you define as an IC structure with the appropriate values.

For example, you could define the following partial structure in the base workspace:

K = struct('A', struct('A1', 3), 'B', 4);

You can then specify the K structure as the Initial conditions parameter of the Unit Delay block:

Simulink.Parameter for Initialization

You can initialize a bus signal using a Simulink.Parameter object that uses an IC structure for the Value property.

For example, you could define the partial structure P in the base workspace (reflecting the ex_busic model discussed in the previous section):

P = Simulink.Parameter;
P.DataType = 'Bus: Top';
P.Value = Simulink.Bus.createMATLABStruct('Top');
P.Value.A.A1 = 3;
P.Value.B = 5; 

You can then specify the P structure as the Initial conditions parameter of the Unit Delay block:

Initialize Arrays of Buses

To specify a unique initial value for each of the individual signals in an array of buses, you can use an array of initial condition structures. Each structure in the array initializes one of the buses.

Initialize an Array of Buses

Suppose that you define the bus types MyData and PressureBus.

Suppose that you set the data type of the signal element temperature to int16, and the data type of the elements s1 and s2 to double.

To specify initial conditions for an array of buses, you can create a variable whose value is an array of initial condition structures.

initValues(1).temperature = int16(5);
initValues(1).pressure.s1 = 9.87;
initValues(1).pressure.s2 = 8.71;

initValues(2).temperature = int16(20);
initValues(2).pressure.s1 = 10.21;
initValues(2).pressure.s2 = 9.56;

initValues(3).temperature = int16(35);
initValues(3).pressure.s1 = 8.98;
initValues(3).pressure.s2 = 9.17;

The variable initValues provides initial conditions for a signal that is an array of three buses. You can use initValues to specify the Initial condition parameter of a block such as Unit Delay.

Alternatively, you can use a single scalar structure to specify the same initial conditions for all of the buses in the array.

initStruct.temperature = int16(15);
initStruct.pressure.s1 = 10.32;
initStruct.pressure.s2 = 9.46;

If you specify initStruct in the Initial condition parameter of a block, each bus in the array uses the same initial value, 15, for the signal element temperature. Similarly, the buses use the initial value 10.32 for the element pressure.s1 and the value 9.46 for the element pressure.s2.

To create an array of structures for a bus that uses a large hierarchy of signal elements, consider using the function Simulink.Bus.createMATLABStruct.

Initialize Nested Arrays of Buses

Create an initial condition structure for a complicated signal hierarchy that includes nested arrays of buses.

  1. In the Bus Editor, create the bus objects MyData and PressureBus.

  2. In the hierarchy pane, select the bus element pressure. Set the Dimensions property to [1 3].

  3. Create an array of four initialization structures by using the function Simulink.Bus.createMATLABStruct. Store the array in the variable initStruct. Initialize all of the individual signals to the ground value, 0.

    initStruct=Simulink.Bus.createMATLABStruct('MyData',[],[1 4]);

  4. In the base workspace, double-click the variable initStruct to view it in the variable editor.

    The four structures in the array each have the fields temperature and pressure.

  5. Double-click one of the pressure fields to inspect it.

    The value of each of the four pressure fields is an array of three substructures. Each substructure has the fields s1 and s2.

  6. To provide unique initialization values for the signals in an array of buses, you can specify the values manually using the variable editor.

    Alternatively, you can write a script. For example, to access the field s1 of the second substructure pressure in the third structure of initStruct, use this code:

    initStruct(3).pressure(2).s1 = 15.35;

Setting Diagnostics to Support Bus Signal Initialization

To enable bus signal initialization, before you start a simulation, set the following two Configuration Parameter diagnostics as indicated:

The documentation for these diagnostics explains how convert your model to handle error messages the diagnostics generate.

See Also

Blocks

Functions

Classes

Related Examples

More About

Was this topic helpful?