Import Bus Data to Root-Level Input Ports

Imported Bus Data Requirements

To import bus data to a root-level input port, use a structure of MATLAB® timeseries objects. The timeseries objects represent the bus elements that you want to specify values for. Any bus elements for which you do not include a field in the structure use ground values. You can include a structure of timeseries objects as a Dataset object element.

In the root-level Inport block, set Data type to Bus and specify the name of a bus object.

A root-level input port defined by a bus object (see Simulink.Bus) can import data from a Dataset object or from that represent the bus elements for which you want to specify values. Any bus elements for which you do not include a field in the structure use ground values.

The structure of MATLAB timeseries objects must match the bus elements in terms of:

  • Hierarchy

  • Name of the structure field, which must match the bus element name. (The name property of the timeseries object does not need to match the bus element name.)

  • Data type (for tunable parameters)

  • Dimensions

  • Complexity

The order of the structure fields does not have to match the order of the bus elements.

Convert Simulink.TsArray Objects

If you use logged data from a model whose Configuration Parameters > Data Import/Export > Signal logging format parameter is set to ModelDataLogs format instead of the default Dataset format, consider converting the data to a structure of MATLAB timeseries objects. The ModelDataLogs format is supported for backwards compatibility. The ModelDataLogs format will be removed in a future release.

Convert to a Structure of Timeseries Objects

To create a structure of MATLAB timeseries objects from a Simulink.TsArray object, use Simulink.SimulationData.createStructOfTimeseries. For example, if tsa is a Simulink.TsArray object:

input = Simulink.SimulationData.createStructOfTimeseries(tsa);

    Note:   If you use a structure of MATLAB timeseries objects for a root Inport block in a model that has multiple root Inport blocks, all the root Inport blocks must use MATLAB timeseries objects. Convert any root Inport block data that uses Simulink.TsArray or Simulink.Timeseries objects to be MATLAB timeseries objects.

Import Bus Data to a Root Inport

Assume that you have a model set up as follows:

  • The TopBusObject bus object has two elements:

    • c

    • s1, which is a sub-bus that has two elements: a and b.

  • The model has two root Inport blocks: In1 and In2.

    • The In1 Inport block imports non-bus data.

    • The In2 Inport block imports bus data of type TopBusObject.

  1. Create a MATLAB timeseries object for each root Inport or Trigger block for which you want to import non-bus data.

    For example:

    N = 10;
    Ts = 1;
    t1 = ((0:N)* Ts)'; 
    d1 = sin(t1);
    in1 = timeseries(d1,t1)
  2. Create a structure of MATLAB timeseries objects, with one timeseries object for each leaf bus element for which you do not want to use ground values.

    For example, to specify non-ground values for all the elements in the s2 bus:

    in2.c = timeseries(d1,t1);
    in2.s1.a = timeseries(d2,t2);
    in2.s1.b = timeseries(d3,t3);

    The MATLAB timeseries objects that you create must match the corresponding bus elements, as described in Imported Bus Data Requirements.

    To determine the number of MATLAB timeseries objects and data type, complexity, and dimensions needed for creating a structure of timeseries objects from a bus, you can use the Simulink.Bus.getNumLeafBusElements and Simulink.Bus.getLeafBusElements methods. For example, for the bus object MyBus:

    num_el = MyBus.getNumLeafBusElements;
    el_list = MyBus.getLeafBusElements;

    To create a structure of MATLAB timeseries objects from a bus object and a cell array of timeseries or Simulink.Timeseries objects, use the Simulink.SimulationData.createStructOfTimeseries utility. For example:

    input = ...

    The number of timeseries objects in the cell array must match the number of leaf elements in the bus object (in this example, num_el). The data type, dimensions, and complexity of each timeseries object must match those attributes of the corresponding bus object leaf node (in this example, the attributes listed in el_list).

  3. Create a Dataset object and add in1 and in2 to the data set.

    ds = Simulink.SimulationData.Dataset;
  4. In the Configuration Parameters > Import/Export > Input parameter edit box, enter the Dataset object ds.

Import Array of Buses Data

To import (load) array of buses data using a root Inport block, use an array of structures of MATLAB timeseries objects.

    Note:   You cannot use an Enable, Trigger, From Workspace, or From File block to import data for an array of buses.

Full Specification of Data

You can use the logged data for an array of buses signal from a previous simulation as roundtrip input to a root-level Inport block in a subsequent simulation run. The logged data is a full specification of data for the Inport block.

If you construct an array of structures of MATLAB timeseries objects to fully specify the data to import:

  • Specify the structure fields in the same order as the signals in the bus signals.

  • Do not include more fields in the structure than there are signals in the bus.

    For leaf fields, match exactly the data type, dimensions, and complexity of the corresponding signal in the bus.

Partial Specification of Data

To specify partial data for array of buses, create a MATLAB array of structures with MATLAB timeseries objects at the leaf nodes.

The structure that you create to specify partial data must be consistent with these rules:

  • You can omit fields, including leaf nodes and sub-branches. You can also omit dimensions. If you do not specify a field, Simulink® uses the ground value for that field.

  • For sub-bus nodes, make the dimension of each field equal to, or smaller than, the dimension for the corresponding node of the array of buses.

This example shows how you can specify partial data to be imported using a root Inport block whose data type is defined as bus object MyBus. You can open the model (ex_partial_loading_aob_model) and the MATLAB code that defines the data to import (ex_partial_loading_aob_data.m).

When you simulate ex_partial_loading_aob_model, it looks like this:

The input Inport block uses the MyBus bus object as its data type.

The MyBus array of buses includes MyBus(1) and MyBus(2). The port dimension is set to 2 to reflect the two buses in the array of buses, and Output as nonvirtual bus is enabled.

Here are the elements of the array of buses, which includes MyBus(1) and MyBus(2). The color highlighting shows the nodes of the array of buses for which data is being imported.

Here is MATLAB code that defines the data to import. The color that highlights the code matches the color of the corresponding node in the array of buses. To view the code used in this model, open the MATLAB code file ex_partial_loading_aob_data.m.

In the code that defines the import data:

  • The timeseries object MyBusValue specifies the data for the highlighted nodes.

  • The timeseries object BT for MyBus(2), because BT is a leaf node, it must match exactly the dimensions, data type, and complexity of the corresponding bus element.

  • The structure specifies data for Y(2). You can skip the first and last sub-buses of Y (that is, Y(1) and Y(3)).

This example specifies data for Y(2); you can skip the first and last sub-buses of Y (that is, Y(1) and Y(3)).

After you define the MyBusValue variable for the import data, set the Configuration Parameters > Data Import/Export > Input parameter to MyBusValue.

Was this topic helpful?