Simulink.SimulationData.DatasetRef class

Package: Simulink.SimulationData
Superclasses:

Create Simulink.SimulationData.DatasetRef object

expand all in page

Description

To use a reference for accessing a Simulink.SimulationData.Dataset object stored in a MAT-file, create a Simulink.SimulationData.DatasetRef object. You can use this reference to avoid running out of memory, by retrieving data signal by signal, for data that you log to persistent storage. You can stream a DatasetRef object into a root-level input port or you can use it to create a SimulationDatastore object to use for streaming. For details, see Load Big Data for Simulations.

For parallel simulations, for which you specify an array of Simulink.SimulationInput objects, if you are logging to file, Simulink®:

  • Creates Simulink.SimulationData.DatasetRef objects to access output data in the MAT-file and includes those objects in the SimulationOutput object data

  • Enables the CaptureErrors argument for simulation

Construction

DSRefObj = Simulink.SimulationData.DatasetRef(location,identifier) creates a reference to the contents of a Simulink.SimulationData.Dataset variable stored in a MAT-file.

Input Arguments

expand all

MAT-file containing Simulink.SimulationData.Dataset object to reference, specified as a character vector. The character vector is a path to the MAT-file. Do not use a file name from one locale in a different locale.

Name of a Simulink.SimulationData.Dataset variable in MAT-file, specified as a character vector. When you log to persistent storage, Simulink uses the variable names specified for each kind of logging.

Suppose that you use the default variable name for signal logging (logsout) and default MAT-file name for persistent storage logging (mat.out), After you simulate the model, then to create a reference to the Dataset object for signal logging, at the MATLAB® command line, enter:

sigLogRef = Simulink.SimulationData.DatasetRef('out.mat','logsout');

Output Arguments

expand all

Reference to logging dataset, returned as a Simulink.SimulationData.DatasetRef object.

Properties

expand all

MAT-file containing Simulink.SimulationData.Dataset object to reference, specified as a character vector. The character vector is a path to the MAT-file. Include the .mat extension in the file name. Do not use a file name from one locale in a different locale.

Name of a Simulink.SimulationData.Dataset variable in MAT-file, specified as a character vector. When you log to persistent storage, Simulink uses the variable names specified for each kind of logging (for example, 'logsout' for signal logging data).

Methods

Use the numElements, getElement, and getElementNames methods for a Simulink.SimulationData.DatasetRef object the same way that you use those methods for a Simulink.SimulationData.Dataset object.

Method

Purpose

numElements

Get number of elements from dataset

getElementNames

Return names of all elements in dataset

get

The get method is an alias for the getElement method.

Note

You can use curly braces to streamline indexing syntax to access elements in a dataset reference, instead of using get or getElement methods. To get an element using curly braces, the index must be a scalar that is not greater than the number of elements in the variable. The get and getElement methods support specifying an element by name or block path, as well as by index.

Get element from dataset

getAsDatastore

Get matlab.io.datastore.SimulationDatastore representation of element from a DatasetRef object

getDatasetVariableNames

List names of Dataset variables in MAT-file

plot

Plot data in the Simulation Data Inspector

Tip

To get the names of Dataset variables in the MAT-file, using the Simulink.SimulationData.DatasetRef.getDatasetVariableNames function processes faster than using the who or whos functions.

Copy Semantics

You can copy DatasetRef object properties by value. However, copying the DatasetRef object produces a handle object. Copying the DatasetRef object does not copy the data in the MAT-file that the object references. For details about copy operations, see Copying Objects in the MATLAB documentation.

Examples

collapse all

This example shows how to construct and use Simulink.SimulationData.DatasetRef objects to access data for a model that logs to persistent storage. This simple example shows the basic steps for logging to persistent storage. This example does not represent a realistic situation for logging to persistent storage, because it shows a short simulation with small memory requirements.

Open the vdp model.

In the Configuration Parameters > Data Import/Export pane, select these parameters:

  • States

  • Log Dataset data to file

Set the Format parameter to Dataset.

Leave the other parameter settings as they are and click Apply.

In the model, click a signal and from the action bar, select Enable Data Logging.

Simulate the model.

Get a list of Dataset variable names in the out.mat file.

varNames = Simulink.SimulationData.DatasetRef.getDatasetVariableNames('out.mat')
varNames = 

  1x2 cell array

  'logsout'   'xout'

Create a reference to the logged states data that is stored in out.mat. The variable for the logged states data is xout.

statesLogRef = Simulink.SimulationData.DatasetRef('out.mat','xout')
statesLogRef = 

  Simulink.SimulationData.DatasetRef
  Characteristics:
          Location: out.mat (/my_files/out.mat)
        Identifier: xout

  Resolved Dataset: 'xout' with 2 elements

       Name  BlockPath 
       ____  _________ 
    1  ''    vdp/x1   
    2  ''    vdp/x2

Create a reference to the signal logging data that is stored in out.mat. The variable for the signal logging data is logsout.

sigLogRef = Simulink.SimulationData.DatasetRef('out.mat','logsout')
sigLogRef = 

  Simulink.SimulationData.DatasetRef
  Characteristics:
          Location: out.mat (/my_files/out.mat)
        Identifier: logsout

  Resolved Dataset: 'logsout' with 1 element

       Name  BlockPath 
       ____  _________ 
    1  x1    vdp/x1

Use the numElements to access the number of elements in the logged states dataset.

statesLogRef.numElements
ans =

     2

Use the DatasetRef to access the first element of the signal logging dataset.

sigLogRef{1}
ans = 

  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'x1'
    PropagatedName: ''
         BlockPath: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1x1 timeseries]


  Methods, Superclasses

Delete the persistent storage MAT-file and try to use one of the DatasetRef objects.

delete('out.mat');
statesLogRef.get(1)
File does not exist.

The statesLogRef still exists, but it is a reference to a Dataset object that is in a file that no longer exists.

See Also

| |

Topics

Introduced in R2016a

Simulink Documentation

Support