matlab.io.datastore.SimulationDatastore class

Package: matlab.io.datastore

Datastore for inputs and outputs of Simulink models

Description

A matlab.io.datastore.SimulationDatastore object enables a Simulink^® model to interact with big data. You can load big data as simulation input and log big output data from a simulation. To simulate models with big data, you store the data in a MAT-file and refer to the data through a SimulationDatastore object. See Work with Big Data for Simulations.

A SimulationDatastore object refers to big simulation data (which a MAT-file stores) for one signal. If the MAT-file stores simulation data for a bus signal, a SimulationDatastore object refers to the data for one leaf signal element in the bus. You can use the datastore object to inspect and access the data and, through a parent object such as Simulink.SimulationData.Signal, simulate a Simulink model with the data.

To analyze the datastore data, you can use the methods and properties of the SimulationDatastore object as well as MATLAB^® tools such as the tall function. For more information about the MATLAB tools, see Getting Started with Datastore.

Construction

After you store big simulation data in a Simulink.SimulationData.Dataset object in a MAT-file, a signal element in the Dataset object points to the big data. To create a matlab.io.datastore.SimulationDatastore object that refers to the big data:

1. At the command prompt or in a script, create a Simulink.SimulationData.DatasetRef object that refers to the Dataset object in the MAT-file.

2. Use one of these techniques:

   • Use one-based, curly-brace indexing (for example, {1}) to return an object that represents the target signal element, such as Simulink.SimulationData.Signal or Simulink.SimulationData.State. For example, for a DatasetRef object named logsout_ref, to create a Signal object that refers to the second signal element, use this code:

     myLoggedSig = logsout_ref{2}

   • Use the getAsDatastore method of the DatasetRef object to return an object that represents the target signal element. For more information, see getAsDatastore.

The SimulationDatastore object resides in the Values property of the returned object.

Properties

FileName — Name and path of file that contains big data

character vector

Name and path of the file that contains the big data, returned as a character vector. This property is read-only.

Data Types: char

NumSamples — Total number of samples (time steps) in the datastore

integer

Total number of samples (time steps) in the datastore, returned as an integer. The readall method extracts this many samples from the big data. This property is read-only.

Data Types: uint64

ReadSize — Amount of data to read at a time

100 (default) | scalar double

Amount of data to read at a time, in number of samples (time steps), specified as a scalar double. The read method extracts this many samples from the big data.

Data Types: double

Methods

hasdata	Determine if data is available to read
isPartitionable	Determine whether datastore is partitionable
isShuffleable	Determine whether datastore is shuffleable
preview	Return subset of data from datastore
progress	Return percentage of data that you have read from a datastore
read	Read data in datastore
readall	Read all data in datastore
reset	Reset datastore to initial state

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Limitations

• SimulationDatastore does not support using a parallel pool with Parallel Computing Toolbox™ installed. To analyze data using tall arrays or run MapReduce algorithms, set the global execution environment to be the local MATLAB session using mapreducer. Enter this code:

  mapreducer(0)

  For information about controlling parallel resources, see Run mapreduce on a Parallel Pool (Parallel Computing Toolbox).

• You cannot use a MATLAB tall variable as simulation input data.

Examples

Inspect and Analyze Data in Simulation Datastore

This example shows how to log big data from a simulation and inspect and analyze portions of that data by interacting with a matlab.io.datastore.SimulationDatastore object.

Log Big Data from Model

Open the example model sldemo_fuelsys.

open_system('sldemo_fuelsys')

Select Configuration Parameters > Data Import/Export > Log Dataset data to file.

set_param('sldemo_fuelsys','LoggingToFile','on')

Simulate the model.

sim('sldemo_fuelsys')

The MAT-file out.mat appears in your current folder. The file contains data for logged signals such as fuel (which is at the root level of the model).

At the command prompt, create a DatasetRef object that refers to the logging variable by name, sldemo_fuelsys_output.

DSRef = Simulink.SimulationData.DatasetRef('out.mat','sldemo_fuelsys_output');

Preview Big Data

Use curly braces ({ and }) to extract the signal element fuel, which is the tenth element in DSRef, as a Simulink.SimulationData.Signal object that contains a SimulationDatastore object.

SimDataSig = DSRef{10};

To more easily interact with the SimulationDatastore object that resides in the Values property of the Signal object, store a handle in a variable named DStore.

DStore = SimDataSig.Values;

Use the preview method to inspect the first five samples of logged data for the fuel signal.

preview(DStore)

ans =

  10x1 timetable

         Time          Data 
    ______________    ______

    0 sec              1.209
    0.00056199 sec     1.209
    0.0033719 sec      1.209
    0.01 sec          1.1729
    0.02 sec          1.1409
    0.03 sec          1.1124
    0.04 sec          1.0873
    0.05 sec          1.0652
    0.055328 sec      1.0652
    0.055328 sec      1.0652

Inspect Specific Sample

Inspect the 603rd sample of logged fuel data.

Set the ReadSize property of DStore to a number that, considering memory resources, your computer can tolerate. For example, set ReadSize to 200.

DStore.ReadSize = 200;

Read from the datastore three times. Each read operation advances the reading position by 200 samples.

read(DStore);
read(DStore);
read(DStore);

Now that you are very close to the 603rd sample, set ReadSize to a smaller number. For example, set ReadSize to 5.

DStore.ReadSize = 5;

Read from the datastore again.

read(DStore)

ans =

  5x1 timetable

      Time       Data 
    ________    ______

    5.79 sec    1.6097
    5.8 sec     1.6136
    5.81 sec    1.6003
    5.82 sec    1.5904
    5.83 sec    1.5832

The third sample of read data is the 603rd sample in the datastore.

Inspect Earlier Sample

Inspect the 403rd sample of logged fuel data. Due to previous read operations, the datastore now reads starting from the 606th sample, so you must reset the datastore. Then, you can read from the first sample up to the 403rd sample.

Use the reset method to reset DStore.

reset(DStore);

Set ReadSize to 200 again.

DStore.ReadSize = 200;

Read from the datastore twice to advance the read position to the 401st sample.

read(DStore);
read(DStore);

Set ReadSize to 5 again.

DStore.ReadSize = 5;

Read from the datastore.

read(DStore)

ans =

  5x1 timetable

      Time       Data  
    ________    _______

    3.85 sec      0.999
    3.86 sec    0.99219
    3.87 sec    0.98538
    3.88 sec    0.97858
    3.89 sec    0.97179

Extract Multiple Samples

Extract samples 1001 through 1020 (a total of 20 samples).

Reset the datastore.

reset(DStore)

Advance to sample 1001.

DStore.ReadSize = 200;

for i = 1:5
    read(DStore);
end

Prepare to extract 20 samples from the datastore.

DStore.ReadSize = 20;

Extract samples 1001 through 1020. Store the extracted data in a variable named targetSamples.

targetSamples = read(DStore)

targetSamples =

  20x1 timetable

      Time       Data 
    ________    ______

    9.7 sec     1.5828
    9.71 sec    1.5733
    9.72 sec    1.5664
    9.73 sec    1.5614
    9.74 sec    1.5579
    9.75 sec    1.5553
    9.76 sec    1.5703
    9.77 sec     1.582
    9.78 sec    1.5913
    9.79 sec    1.5988
    9.8 sec      1.605
    9.81 sec    1.6101
    9.82 sec    1.6145
    9.83 sec    1.6184
    9.84 sec    1.6049
    9.85 sec     1.595
    9.86 sec    1.5877
    9.87 sec    1.5824
    9.88 sec    1.5785
    9.89 sec    1.5757

Find Maximum Value of Data in Datastore

Reset the datastore.

reset(DStore)

Write a while loop, using the hasdata method, to incrementally analyze the data in chunks of 200 samples.

DStore.ReadSize = 200;
runningMax = [];
while hasdata(DStore)
    tt = read(DStore);
    rawChunk = tt.Data;
    runningMax = max([rawChunk; runningMax]);
end

Now, the variable runningMax stores the maximum value in the entire datastore.

runningMax

runningMax =

    1.6423