Simulink.SimulationData.DatasetRef

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 a DatasetRef object 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, the software:

  • 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

Tip

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

Creation

Syntax

DSRefObj = Simulink.SimulationData.DatasetRef(location,identifier)

Description

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

example

Input Arguments

expand all

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

Example: "out.mat"

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

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

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

Example: "logsout"

Output Arguments

expand all

Reference to Dataset object, returned as a Simulink.SimulationData.DatasetRef object.

Properties

expand all

This property is read-only.

MAT file containing Simulink.SimulationData.Dataset object to reference, returned as a character vector. The character vector is a path to the MAT file.

This property is read-only.

Name of a Simulink.SimulationData.Dataset variable in MAT file, return as character vector. When you log to persistent storage, the software uses the variable names specified for each kind of logging. For example, signal logging data has the default variable name logsout.

Object Functions

getGet element or collection of elements from Simulink.SimulationData.Dataset object
getElementNamesReturn names of all elements in Simulink.SimulationData.Dataset object
numElementsGet number of elements in Simulink.SimulationData.Dataset object
plotPlot data in Simulation Data Inspector
getAsDatastoreGet matlab.io.datastore.SimulationDatastore representation of element from referenced Dataset object
Simulink.SimulationData.DatasetRef.getDatasetVariableNamesList names of variables in MAT file that contain Simulink.SimulationData.Dataset objects

Examples

collapse all

Open Live Script

You can construct and use Simulink.SimulationData.DatasetRef objects to access data for a model that logs to persistent storage. This 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.

mdl = "vdp";
open_system(mdl)

In the model, mark the signal x1 for signal logging.

  1. Right-click the signal x1.

  2. Select Log Selected Signals.

Alternatively, you can mark the signal for logging programmatically.

Simulink.sdi.markSignalForStreaming("vdp/x1",1,"on")

Configure the model to log data to persistent storage.

In the Configuration Parameters > Data Import/Export pane:

  1. Select the States parameter.

  2. Select the Log Dataset data to file parameter.

  3. Click OK.

Click Run to simulate the model.

Alternatively, you can select the parameters programmatically using name-value arguments.

sim(mdl,"SaveState","on","LoggingToFile","on")
ans = 
  Simulink.SimulationOutput:

                   tout: [87x1 double] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char]

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

varNames = Simulink.SimulationData.DatasetRef.getDatasetVariableNames("out.mat")
varNames = 1×3 cell
    {'logsout'}    {'xout'}    {'yout'}

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 (/tmp/Bdoc25b_2988451_1128248/tp5e22c684/simulink-ex68096319/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 (/tmp/Bdoc25b_2988451_1128248/tp5e22c684/simulink-ex68096319/out.mat)
        Identifier: logsout

  Resolved Dataset: 'logsout' with 2 elements

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

Use the numElements function to access the number of elements in the logged states Datasetref object.

numElements(statesLogRef)
ans = 
2

Use curly braces to access the first element of the signal logging Datasetref object.

sigLogRef{1}
ans = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'x1'
    PropagatedName: ''
         BlockPath: [1×1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1×1 matlab.io.datastore.SimulationDatastore]


  Methods, Superclasses

If you delete the persistent storage MAT file and try to use one the DatasetRef objects, the software returns an error because the file does not exist. The statesLogRef variable still exists, but it is a reference to a Dataset object that is in a file that no longer exists.

Version History

Introduced in R2016a

See Also

Objects

Functions

Topics