Format

Format for logged states, output, and final states data

Model Configuration Pane: Data Import/Export

Description

Specify format for logged states, output, and final states data. Signal logging and data store logging always use the Dataset format.

The choice of format does not affect the simulation results in terms of the system behavior but can affect the content of the logged data. The Dataset format logs time data for each signal, so logged values reflect the sample rate for each output and state. The Structure, Structure with time, and Array formats share a single time vector for all outputs and states, so the output and state data is logged using the fundamental sample time for the model.

Settings

Dataset (default) | Array | Structure | Structure with time

Dataset

Logged outputs, states, and final states are each stored in a Simulink.SimulationData.Dataset object. Each Dataset object contains an element for each individual state or output. By default, the data for each state or output is stored in a timeseries object except variable-size signal data. Logged data for variable-size signals is always stored in a timetable that contains a cell array of signal values for each time step. To specify whether to store data as a timeseries object or as a timetable, use the Dataset signal format parameter.

You can process data logged using the Dataset format in MATLAB^® without a Simulink^® license.

When you log states and output data using the Dataset format:

• Logging supports saving multiple data values for a given time step, which can be required for logging data in a For Iterator Subsystem, a While Iterator Subsystem, and Stateflow^®.

• Logged data automatically streams to the Simulation Data Inspector during simulation.

• You can log variable-size signals using top-level Outport blocks.

• You can use state and operating point data as the initial state for simulation of a model that contains bus-valued states.

Dataset format does not support:

• Code generation.

• Logging states inside a function-call subsystem.

• Logging states during rapid accelerator simulations.

• Logging states in simulations deployed using Simulink Compiler™

• Logging final states in rapid accelerator and deployed simulations if one or more states in the model has any of these data types:

  • half

  • string

  • Character vector

  • Fixed-point

• Logging final states if a referenced model that simulates in a mode other than normal contains one or more states that have any of these data types:

  • half

  • string

  • Character vector

  • Fixed-point

Array

Logged outputs, states, and final states are each stored as a matrix. Each row in the matrix corresponds to a simulation time step, and each column corresponds to a state or output.

The order of the states and outputs in the matrix depends on the block sorted order, which can change from one simulation to the next. Do not use Array format to log bus data.

To use Array format, all logged states and outputs must be:

• All scalars or all vectors (or all matrices for states)

• All real or all complex

• The same data type

Use another format if the outputs and states in your model do not meet these conditions.

Structure

Outputs, states, and final states are each stored as a structure. The states structure contains a structure for each block in the model that has a state. The outputs structure contains a structure for each top-level output port.

Structure with time

Outputs, states, and final states are each logged to a structure that contains a field for time data as well as a field for the output or states data. The time field contains a vector of simulation times. The signals field contains the same data that is logged when you select the Structure format.

Examples

Access Data Logged Using Dataset Format

Open the model vdp. The model produces two outputs x1 and x2.

mdl = "vdp";
open_system(mdl);

Simulate the model, logging block states along with the output data.

out = sim(mdl,"SaveState","on");

All logged data is returned in the single variable out as a Simulink.SimulationOutput object. The SimulationOutput object contains a Simulink.SimulationData.Dataset object that groups each kind of logged data.

out

out = 
  Simulink.SimulationOutput:
                   tout: [64x1 double] 
                   xout: [1x1 Simulink.SimulationData.Dataset] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

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

Access the Dataset object yout that contains the logged output data using dot notation. The Dataset object contains a Simulink.SimulationData.Signal object for each output.

outputs = out.yout

outputs = 
Simulink.SimulationData.Dataset 'yout' with 2 elements

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      x1    vdp/Out1 
    2  [1x1 Signal]      x2    vdp/Out2 

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

The Signal object has metadata about the signal, including the path to the block and index of the port that produces the signal. Use the getElement function to access the Signal object that contains the data for signal x1 by name. You can also use curly braces({}) to access elements in a Dataset object by index.

outputX1 = getElement(outputs,'x1')

outputX1 = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

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

The signal data is stored in the Values property of the Signal object as a timeseries object.

outputValsX1 = outputX1.Values

  timeseries

  Common Properties:
            Name: 'x1'
            Time: [64x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [64x1 double]
        DataInfo: tsdata.datametadata

The time values are in the Time property of the timeseries object. The signal values are in the Data property.

outputTimesX1 = outputValsX1.Time

outputTimesX1 = 64×1

         0
    0.0001
    0.0006
    0.0031
    0.0157
    0.0785
    0.2844
    0.5407
    0.8788
    1.2788
      ⋮

outputDataX1 = outputValsX1.Data

outputDataX1 = 64×1

    2.0000
    2.0000
    2.0000
    2.0000
    1.9998
    1.9943
    1.9379
    1.8155
    1.5990
    1.2687
      ⋮

You can also access the time values or data values by combining the steps into a single line of code.

outputDataX1 = getElement(out.yout,'x1').Values.Data

outputDataX1 = 64×1

    2.0000
    2.0000
    2.0000
    2.0000
    1.9998
    1.9943
    1.9379
    1.8155
    1.5990
    1.2687
      ⋮

Recommended Settings

The table summarizes recommended values for this parameter based on considerations related to code generation.

Application	Setting
Debugging	No impact
Traceability	No impact
Efficiency	No recommendation
Safety precaution	No recommendation

Programmatic Use

Parameter: SaveFormat

Value: "Array" | "Structure" | "StructureWithTime" | "Dataset"

Default: "Dataset"

Version History

Introduced before R2006a