Load Data Using the From Workspace Block

This example shows how to create and format data to load from the base workspace using the From Workspace block. To load data using the From Workspace block, you must create or save the data using a format the From Workspace block supports in the base, model, or mask workspace. You could programmatically create the data you load, load data logged in another simulation, or load real-world data collected from sensors or in a lab. You can use the code from each format section as a template to understand how to format your own simulation input data.

Examine the Model

This example uses a simple model. Two From Workspace blocks load data from the base workspace and send that data to two Outport blocks. One From Workspace block uses default values for all block settings, and the other is configured to load data for a bus. Two Dashboard Scope blocks in the model display the data loaded by each From Workspace block. The model also contains several Callback Button blocks you can use to generate the data in the base workspace using different formats supported by the From Workspace block.

The model uses the PreLoadFcn callback to define the simin variable using the timeseries format and the busin variable using a structure of timeseries objects when you open the model. Use one of the Callback Button blocks to create data in the desired format prior to simulating the model. To create the data, click to select the Callback Button block and click again to run the code. You can view the code for each Callback Button block in the block dialog or Property Inspector.

Create Time and Signal Data

Most data formats supported by the From Workspace block fundamentally consist of a time vector paired with signal values. You can use the Structure without time format to load only input data values with no corresponding time values, which is sometimes required for discrete simulations. (For more information, see Load Data to Test a Discrete Algorithm.) This example creates and loads ten seconds of data that represents a sine wave.

To create an evenly spaced time vector, start with an array that counts from zero to the desired number of time steps minus one (for the first time step, which is already defined). Multiply the array by your desired sampling interval. Finally, transpose the resulting time variable so that it is a column vector, rather than a row vector.

sampleRate = 0.01;
numSteps = 1001;
time = sampleRate*[0:(numSteps-1)];
time = time';

Note

MATLAB^® supports several other methods for creating an evenly spaced time vector, but other methods can introduce double-precision rounding errors in the time data, which can lead to unexpected simulation results. For example, do not use the linspsace function or this form of MATLAB expression to create an evenly-spaced time vector for simulation input data:

time = [startTime:stepSize:endTime]';

The resulting time vector is not equivalent to the vector created using this expression:

time = stepSize*[startTime:(numSteps-1)]

When your time vector consists of unevenly spaced time values, you can use any valid MATLAB expression to create the time data.

Now, create the signal data using the sin function. This example creates a sine wave with a period of 3.

data = sin(2*pi/3*time);

Load timeseries Data

Simulink^® loading and logging both commonly use MATLAB timeseries objects to pass time series data into and out of simulations. The code for the Callback Button block labeled Create timeseries data to load creates the time and signal data, uses it to create a timeseries object, and assigns the timeseries object to the loading variable simin.

sampleRate = 0.01;
numSteps = 1001;
time = sampleRate*[0:(numSteps-1)];
time = time';
data = sin(2*pi/3*time);
simin = timeseries(data,time);

To load the timeseries data, you can run the code to create the simin loading variable in the MATLAB Command Window or select then press the Create timeseries data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

Load timetable Data

The MATLAB timetable object is another format used to store time series data. As the name suggests, the data is formatted as a table. When you load data using a timetable object, the timetable object can only contain data in one column, for a single signal.

The code for the Callback Button block labeled Create timetable data to load creates the time and signal data, uses it to create a timetable object, and assigns the timetable object to the loading variable simin. The timetable object requires that the input times are a datetime or duration vector. This example creates a duration vector, secs, using the seconds function.

sampleRate = 0.01;
numSteps = 1001;
time = sampleRate*[0:(numSteps-1)];
time = time';
data = sin(2*pi/3*time);
secs = seconds(time);
simin = timetable(secs,data);

To load the timetable data, you can run the code to create the simin loading variable in the MATLAB Command Window or select then press the Create timetable data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

Load Structure Data

The From Workspace block supports loading data for a signal using a structure that matches the Structure or Structure with time logging formats. The model contains a Callback Button block that creates data that matches the Structure with time format. The Structure format matches to the Structure with time format, except the Structure format does not have a time field.

The structure has two top-level fields, time and signals. When you log data using the Structure with time format, the signals field may be an array of structures that contain data for several signals. When you load data using the Structure with time format, the signals field can only contain one structure with data for a single signal. The structure for the signals field contains a values field and must contain a dimensions field when the signal is not scalar.

The code for the Callback Button block labeled Create structure with time data to load creates the time and signal data and uses it to build the structure with the required fields and hierarchy. The code starts by clearing any existing variable with the name simin which could be an object with property names that match the names for the fields of the structure.

clear simin;
sampleRate = 0.01;
numSteps = 1001;
time = sampleRate*[0:(numSteps-1)];
time = time';
data = sin(2*pi/3*time);
simin.time = time;
simin.signals.values = data;

To load the structure data, you can run the code to create the simin loading variable in the MATLAB Command Window or select then press the Create structure data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

When you load data for a multidimensional signal, add one more line of code to assign the signal dimensions to simin.signals.dimensions. When the signal data is scalar, set the dimensions field to 1, if you include it. When each signal value is a row vector, you can specify the dimensions as [1 n] or as n, where n is the number of columns. When each signal value is an M-by-N matrix, specify the dimensions field value as [M N].

When you want to load simulation input data without time data, use the Structure format, which does not include the time field and specify the desired sample rate in the Sample time parameter. For more information, see Load Data to Test a Discrete Algorithm.

Load Array Data

You can use the From Workspace block to load signal data formatted as an array, where the first column of the array contains time data and subsequent columns contain the signal data. When you load data in the array format, the signal values can only contain one row.

The code for the Callback Button block named Create array data to load creates the time and signal data and concatenates the two row vectors into an array.

sampleRate = 0.01;
numSteps = 1001;
time = sampleRate*[0:(numSteps-1)];
time = time';
data = sin(2*pi/3*time);
simin = [time,data];

To load the array data, you can run the code to create the simin loading variable in the MATLAB Command Window or select then press the Create array data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

Load Bus Data

When you load bus data using the From Workspace block, you must specify the Output data type parameter as the Simulink.Bus object that defines the bus. The From Workspace block that loads bus data has its Output data type setting configured as Bus: SinusoidBus. The PreLoadFcn callback for the model and the code for the Create bus data to load Callback Button block both define the SinusoidBus object.

A Bus object defines the bus hierarchy as well as properties of the elements in the bus, such as name and data type. The Bus object in this example defines the bus hierarchy, the names for the signals contained in the bus, and the data type for a nested bus. The bus, SinusoidBus, contains one signal, Cosine, and a nested bus called SineBus, which contains two signals, Sine and BigSine.

elems(1) = Simulink.BusElement;
elems(1).Name = 'Sine';
elems(2) = Simulink.BusElement;
elems(2).Name = 'BigSine';
SineBus = Simulink.Bus;
SineBus.Elements = elems;

clear elems;
elems(1) = Simulink.BusElement;
elems(1).Name = 'SineBus';
elems(1).DataType = 'Bus: SineBus';
elems(2) = Simulink.BusElement;
elems(2).Name = 'Cosine';
SinusoidBus = Simulink.Bus;
SinusoidBus.Elements = elems;

For more information about defining buses with Simulink.Bus objects, see Specify Bus Properties with Simulink.Bus Object Data Types.

The Create bus data to load Callback Button block creates a structure of timeseries objects with a hierarchy and field names that match the hierarchy and element names of the SinusoidBus object. You can also create a structure of timetable objects to load as input data for a bus.

sampleRate = 0.01;
numSteps = 1001;

time = sampleRate*[0:(numSteps-1)];
time = time';

data = sin(2*pi/3*time);
cosdata = cos(2*pi/3*time);
ampdata = 2*data;

busin.Cosine = timeseries(cosdata,time);
busin.SineBus.Sine = timeseries(data,time);
busin.SineBus.BigSine = timeseries(ampdata,time);

To load the bus data, you can run the code to create the busin loading variable in the MATLAB Command Window or select then press the Create bus data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

Load Partially Specified Bus Data

When you load input data for a bus using the From Workspace block, you do not need to provide data for every bus element. To partially specify input data for a bus, you can omit the corresponding field in the structure or specify its value as [].

The Create partially specified bus data to load Callback Button block creates a structure of timeseries objects with a hierarchy and field names that match the hierarchy and element names of the SinusoidBus object. It does not specify data for the Cosine bus element.

sampleRate = 0.01;
numSteps = 1001;

time = sampleRate*[0:(numSteps-1)];
time = time';

data = sin(2*pi/3*time);
ampdata = 2*data;

busin.Cosine = [];
busin.SineBus.Sine = timeseries(data,time);
busin.SineBus.BigSine = timeseries(ampdata,time);

To load the bus data, you can run the code to create the busin loading variable in the MATLAB Command Window or select then press the Create partially specified bus data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.

When you partially specify data for a bus that includes a nested bus or nested array of buses, you can specify the entire nested bus or nested array of buses as [] and the From Workspace block provides ground values for all elements of the nested bus or array of buses. You can also partially specify data for an array of buses by omitting data for one or more of the buses contained in the array of buses.

Load Array of Buses Data

When you use the From Workspace block to load data for an array of buses, you must specify the Output data type parameter as the Simulink.Bus object that defines the buses the array of buses contains. All buses in an array of buses must be defined by the same Simulink.Bus object. The From Workspace block that loads data for the array of buses has its Output data type set to Bus: SinusoidBus. For details about defining the Bus object, see Load Bus Data.

The Create array of buses data to load Callback Button block creates an array that contains two structures of timeseries objects with hierarchy and field names that match the hierarchy and element names of the SinusoidBus object. The second structure, bus2, uses the same data as the first, shifted down by one so that you can see all six signals on the Dashboard Scope block.

sampleRate = 0.01;
numSteps = 1001;

time = sampleRate*[0:(numSteps-1)];
time = time';

data = sin(2*pi/3*time);
cosdata = cos(2*pi/3*time);
ampdata = 2*data;

bus1.Cosine = timeseries(cosdata,time);
bus1.SineBus.Sine = timeseries(data,time);
bus1.SineBus.BigSine = timeseries(ampdata,time);

bus2.Cosine = timeseries((cosdata-1),time);
bus2.SineBus.Sine = timeseries((data-1),time);
bus2.SineBus.BigSine = timeseries((ampdata-1),time);

busin = [bus1,bus2];

To load the array of buses data, you can run the code to create the busin loading variable in the MATLAB Command Window or select then press the Create array of buses data to load Callback Button block. Then, simulate the model and view the loaded data on the Dashboard Scope block.