addElement

Add element to end of Simulink.SimulationData.Dataset object

Syntax

ds = addElement(ds,el)

ds = addElement(ds,el,name)

Description

ds = addElement(ds,el) adds an element to the end of the Simulink.SimulationData.Dataset object ds.

ds = addElement(ds,el,name) gives the element the name that you specify with the name argument.

Examples

Add Elements to Data Set

You can use the addElement function to add elements to a data set. First, create an empty Simulink.SimulationData.Dataset object.

time = 0.1*(0:100)';
ds = Simulink.SimulationData.Dataset;

Create three elements to add to the data set.

element1 = Simulink.SimulationData.Signal;
element1.Name = "A";
element1.Values = timeseries(sin(time),time);

element2 = Simulink.SimulationData.Signal;
element2.Name = "B";
element2.Values = timeseries(2*sin(time),time);

element3 = Simulink.SimulationData.Signal;
element3.Name = "C";
element3.Values = timeseries(3*sin(time),time);

Add the elements to the data set using the addElement function. You can rename the elements using the name argument.

ds = addElement(ds,element1,"Element A");
ds = addElement(ds,element2,"Element B");
ds = addElement(ds,element3,"Element C")

ds = 
Simulink.SimulationData.Dataset '' with 3 elements

                         Name       BlockPath 
                         _________  _________ 
    1  [1x1 Signal]      Element A  ''       
    2  [1x1 Signal]      Element B  ''       
    3  [1x1 Signal]      Element C  ''       

  - Use braces { } to access, modify, or add elements using index.

Group Simulation Inputs Using Dataset Object

Create data for three simulation input signals and group them in a Dataset object. A simple model loads the contents of the Dataset object using three root-level Inport blocks. Dashboard Scope blocks in the model display each signal created using the loaded input data.

First, create the signal data to load into the model. Use the expression in this example to create the evenly-spaced time vector for an input signal, especially when modeling discrete input signals. MATLAB® supports several other methods for creating an evenly-spaced vector, but other methods can introduce double-precision rounding errors in the time data, which can lead to unexpected simulation results.

sampleTime = 0.01;
numSteps = 1001;
time = sampleTime*(0:numSteps-1);
time = time';

Create signal data for a sine signal, a cosine signal, and a linear signal.

sineVals = sin(2*pi/3*time);
cosVals = cos(2*pi/3*time);
lineVals = time;

Create a timeseries object to contain the data for each signal. Give each timeseries object a descriptive name so signals are easy to identify once they are grouped in the Dataset object.

sineTS = timeseries(sineVals,time,'Name','Sine Wave');
cosTS = timeseries(cosVals,time,'Name','Cosine Wave');
lineTS = timeseries(lineVals,time,'Name','Line');

Create a Dataset object and use the addElement function to add each timeseries object to the Dataset object.

inputData = Simulink.SimulationData.Dataset;
inputData.Name = 'inputData';
inputData = addElement(inputData,sineTS);
inputData = addElement(inputData,cosTS);
inputData = addElement(inputData,lineTS)

inputData = 
Simulink.SimulationData.Dataset 'inputData' with 3 elements

                             Name         BlockPath 
                             ___________  _________ 
    1  [1x1 timeseries]      Sine Wave    ''       
    2  [1x1 timeseries]      Cosine Wave  ''       
    3  [1x1 timeseries]      Line         ''       

  - Use braces { } to access, modify, or add elements using index.

When you load external input data using root-level Inport blocks, you specify the data to load using the Input parameter in the Model Configuration Parameters on the Data Import/Export pane. Open the model LoadInputDataset and see that the Input parameter is specified as inputData.

open_system('LoadInputDataset.slx');

Simulate the model. The Dashboard Scope block connected to the first Inport block shows the sine signal, the Dashboard Scope block connected to the second Inport block shows the cosine signal, and the Dashboard Scope block connected to the third Inport block shows the linear signal.

out = sim('LoadInputDataset.slx');

You can swap the order of elements in the Dataset object and see the change reflected in how the elements are mapped to the Inport blocks.

inputData{1} = lineTS;
inputData{3} = sineTS

inputData = 
Simulink.SimulationData.Dataset 'inputData' with 3 elements

                             Name         BlockPath 
                             ___________  _________ 
    1  [1x1 timeseries]      Line         ''       
    2  [1x1 timeseries]      Cosine Wave  ''       
    3  [1x1 timeseries]      Sine Wave    ''       

  - Use braces { } to access, modify, or add elements using index.

Simulate the model again. The Dashboard Scope block that displays the first element now shows the line, and the Dashboard Scope block that displays the third element shows the sine wave, reflecting the new order of elements in the Dataset object.

out = sim('LoadInputDataset.slx');

Input Arguments

ds — Dataset object

Simulink.SimulationData.Dataset object

Dataset object to which to add the element, specified as a Simulink.SimulationData.Dataset object.

el — Element to add

Simulink.SimulationData.Dataset object element

Element to add to the data set, specified as a Simulink.SimulationData.Dataset object element.

When a Dataset object is created by logging simulation data, each element contains data for one logged signal, output, data store, or state. Each element is an object, and the type of the object depends on the data it contains.

• Signals and output — Simulink.SimulationData.Signal object

• States and final states — Simulink.SimulationData.State object

• Data stores — Simulink.SimulationData.DataStoreMemory object

When you create a Dataset object that groups simulation input data, each element contains data for a signal, bus, or array of buses. You can add data in any format supported by the loading method you use.

Type of Input	Data Formats
Scalar, vector, or multidimensional signal	timeseries timetable Simulink.SimulationData.Signal matlab.io.datastore.SimulationDatastore matlab.io.datastore.sdidatastore Structure with one field called signals.values that contains data for a single signal and a field called time that optionally includes time data Array where the first column contains time data and subsequent columns contain data for a signal
Bus	Structure of timeseries, timetable, or matlab.io.datastore.SimulationDatastore objects that matches the hierarchy of the bus Simulink.SimulationData.Signal
Array of buses	Array of structures Simulink.SimulationData.Signal
Function-call signal	N-by-1 vector Simulink.SimulationData.Signal

name — Name for element

string | character vector

Name for element, specified as a string or character vector. If the object already has a name, the element instead uses the name you specify.

Alternatives

To streamline indexing syntax, you can use curly braces ({}) to add an element to a Dataset object instead of using addElement. For the index, use an integer that is greater than the number of elements by one. The new element becomes the last element of the dataset.

time = 0.1*(0:100)';
ds = Simulink.SimulationData.Dataset;
element1 = Simulink.SimulationData.Signal;
element1.Name = "A";
element1.Values = timeseries(sin(time),time);
ds{1} = element1;
element2 = Simulink.SimulationData.Signal;
element2.Name = "B";
element2.Values = timeseries(2*sin(time),time);
ds{2} = element2;
element3 = Simulink.SimulationData.Signal;
element3.Name = "C";
element3.Values = timeseries(3*sin(time),time);
ds{3} = element3;

Version History

Introduced in R2011a