Simulink.sdi.DiffRunResult

Access run comparison results

expand all in page

Description

The Simulink.sdi.DiffRunResult object provides access to run comparison metadata and comparison results. Use the getSignalByIndex function to access the metadata and comparison results for each signal in the run comparison.

Creation

A Simulink.sdi.DiffRunResult object is created when you perform a comparison using the Simulation Data Inspector.

When you compare data using the UI, use the Simulink.sdi.getCurrentComparison function to access the results in a Simulink.sdi.DiffRunResult object.

Programmatic comparisons using the Simulink.sdi.compareRuns function or the compare function return a DiffRunResult object.

Properties

expand all

This property is read-only.

Version of MATLAB® used to create the DiffRunResult object, returned as a character vector.

This property is read-only.

Run identifier for the comparison baseline run, returned as an integer.

This property is read-only.

Run identifier of the run to compare, returned as an integer.

This property is read-only.

Number of signals that aligned between the two runs in the comparison, returned as an integer. For more information on how signals are aligned for comparisons, see Signal Alignment.

This property is read-only.

Date and time the Simulink.sdi.DiffRunResult object was created, returned as a datetime object.

Data Types: datetime

This property is read-only.

Global tolerance values used for the run comparison, returned as a structure with fields:

  • AbsTol — Global absolute tolerance used for the run comparison.

  • RelTol — Global relative tolerance used for the run comparison.

  • TimeTol — Global time tolerance used for the run comparison.

For more information about how tolerances are used and calculated for comparisons, see Tolerance Specification.

This property is read-only.

Comparison results summary, returned as a structure with a field for each Status a signal comparison result could have. The value of each field indicates the number of signals in the run comparison with the corresponding Status.

  • WithinTolerance — Signal comparison completed, and all data points compared fell within the specified tolerance.

  • OutOfTolerance — Signal comparison completed, and some data points compared fell outside of the specified tolerance.

  • Unaligned — Signal from the baseline run did not align with a signal in the run to compare.

  • Empty — Aligned signal in the baseline run or run to compare contains no data.

  • EmptySynced — Synchronized signal in the baseline run or run to compare contains no data. An empty synchronized signal can mean that the signals do not overlap or, if you specified the intersection synchronization method, that they included none of the same time points,

  • Canceled — Signal result not computed because the user canceled the comparison.

  • Pending — Comparison is in progress and the signal result computation has not started.

  • Processing — Signal result computation in progress.

  • UnitsMismatch — The signal units in the baseline run and run to compare do not match.

  • DataTypeMismatch — The signal data types in the baseline run and run to compare do not match. Only results of comparisons configured to check signal data types can have this status.

  • TimeMismatch — The signal time vectors in the baseline run and run to compare do not match. Only results of comparisons configured to check signal time vectors can have this status.

  • StartStopMismatch — The signal start and stop times in the baseline run and run to compare do not match. Only results of comparisons configured to check signal start and stop times can have this status.

  • Unsupported — The Simulation Data Inspector comparison algorithm does not support this type of signal. For example, signals with data types that lose precision when converted to double are not supported.

For more information about alignment, tolerances, and synchronization, see How the Simulation Data Inspector Compares Data. For more information about how to configure a comparison to check additional metadata, see Simulink.sdi.compareRuns.

This property is read-only.

Configuration options used for the comparison, returned as an n-by-2 cell array. Each row in the cell array corresponds to an option used by the comparison. Every comparison requires that aligned signal units match, so the Options property always includes a row to indicate that units must match. Other possible configuration options correspond to these name-value pairs for the Simulink.sdi.compareRuns function:

  • DataType

  • Time

  • StartStop

  • StopOnFirstMismatch

This property is read-only.

Status of the run comparison, indicating how the comparison ended, returned as one of the following:

  • Completed — Comparison finished computing all results

  • Canceled — Comparison ended because the user canceled the comparison operation in the UI

  • Stopped — Comparison ended because the comparison detected a mismatch and was configured to stop on the first mismatch

This property is read-only.

Signal result for signal comparison that caused the run comparison to stop without comparing remaining signals, returned as a Simulink.sdi.DiffSignalResult object. The StopReason property is empty when the comparison completes without detecting a mismatch and when the comparison is not configured to stop on the first mismatch. You can configure a simulation to stop on the first mismatch using the Simulink.sdi.compareRuns function and the 'StopOnFirstMismatch' name-value pair.

Object Functions

getResultByIndexReturn signal comparison result
saveResultSave comparison results to an MLDATX file

Examples

collapse all

Open Live Script

Using the Simulation Data Inspector programmatic interface, you can specify signal tolerance values to use in comparisons. This example uses the slexAircraftExample model and the Simulation Data Inspector to evaluate the effect of changing the time constant for the low-pass filter following the control input.

Configure the Model

Load the model and mark signals of interest for logging. This example logs data for the q and alpha signals.

load_system('slexAircraftExample')

Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model',3,'on')
Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model',4,'on')

Run Simulations

Run simulations with different low-pass filter time constants to generate results to compare. The slexAircraftExample model stores variables associated with the model in the model workspace. To modify the time constant value, access the model workspace and use the assignin function.

out1 = sim('slexAircraftExample');

modelWorkspace = get_param('slexAircraftExample','modelworkspace');
assignin(modelWorkspace,'Ts',1)

out2 = sim('slexAircraftExample');

Access and Compare Simulation Results

Access the simulation results using the Simulation Data Inspector programmatic interface. Each simulation creates a run in the Simulation Data Inspector with a unique run ID. You use the run IDs to compare the simulation results. 

runIDs = Simulink.sdi.getAllRunIDs;
runIDTs1 = runIDs(end-1);
runIDTs2 = runIDs(end);

Use the Simulink.sdi.compareRuns function to compare the data from the simulations. Then inspect the Status property of the signal result to see whether the signals fell within the default tolerance of 0. 

diffRun1 = Simulink.sdi.compareRuns(runIDTs1,runIDTs2);

sig1Result1 = getResultByIndex(diffRun1,1);
sig2Result1 = getResultByIndex(diffRun1,2);

sig1Result1.Status
ans = 
OutOfTolerance

sig2Result1.Status
ans = 
OutOfTolerance

Compare Runs with Signal Tolerances

By default, signals use 0 for all tolerance values, so the comparison returns out-of-tolerance results when the signals are not identical. To further analyze the effect of the time constant change, specify tolerance values for the signals. You can specify tolerances for a programmatic comparison using the properties of the Simulink.sdi.Signal objects in the runs you compare. The comparison uses the tolerances specified for the baseline Signal object. This example specifies a combination of time and absolute tolerances.

To specify tolerances, first access the Simulink.sdi.Signal objects that correspond to each signal in the runs you want to compare.

run1 = Simulink.sdi.getRun(runIDTs1);
sigID1 = getSignalIDByIndex(run1,1);
sigID2 = getSignalIDByIndex(run1,2);

sig1 = Simulink.sdi.getSignal(sigID1);
sig2 = Simulink.sdi.getSignal(sigID2);

Check the Name property to identify each Signal object.

sig1.Name
ans = 
'q, rad/sec'

sig2.Name
ans = 
'alpha, rad'

Specify an absolute tolerance of 0.1 and a time tolerance of 0.6 for the q signal using the AbsTol and TimeTol properties of the q signal object in the baseline run.

sig1.AbsTol = 0.1;
sig1.TimeTol = 0.6;

Specify an absolute tolerance of 0.2 and a time tolerance of 0.8 for the alpha signal using the AbsTol and TimeTol properties of the alpha signal object in the baseline run.

sig2.AbsTol = 0.2;
sig2.TimeTol = 0.8;

Compare the runs again and access the results.

diffRun2 = Simulink.sdi.compareRuns(runIDTs1,runIDTs2);
sig1Result2 = getResultByIndex(diffRun2,1);
sig2Result2 = getResultByIndex(diffRun2,2);

Check the Status property of each signal to determine whether the comparison results fell within the specified tolerances.

sig1Result2.Status
ans = 
WithinTolerance

sig2Result2.Status
ans = 
WithinTolerance
Open Live Script

You can use the Simulink.sdi.compareRuns function to compare signal data and metadata, including data type and start and stop times. A single comparison may check for mismatches in one or more pieces of metadata. When you check for mismatches in signal metadata, the Summary property of the Simulink.sdi.DiffRunResult object may differ from a basic comparison because the Status property for a Simulink.sdi.DiffSignalResult object can indicate the metadata mismatch. You can configure comparisons using the Simulink.sdi.compareRuns function for imported data and for data logged from a simulation.

This example configures a comparison of runs created from workspace data three ways to show how the Summary of the DiffSignalResult object can provide specific information about signal mismatches.

Create Workspace Data

The Simulink.sdi.compareRuns function compares time series data. Create data for a sine wave to use as the baseline signal, using the timeseries format. Give the timeseries the name Wave Data.

time = 0:0.1:20;
sig1vals = sin(2*pi/5*time);
sig1_ts = timeseries(sig1vals,time);
sig1_ts.Name = 'Wave Data';

Create a second sine wave to compare against the baseline signal. Use a slightly different time vector and attenuate the signal so the two signals are not identical. Cast the signal data to the single data type. Also name this timeseries object Wave Data. The Simulation Data Inspector comparison algorithm will align these signals for comparison using the name.

time2 = 0:0.1:22;
sig2vals = single(0.98*sin(2*pi/5*time2));
sig2_ts = timeseries(sig2vals,time2);
sig2_ts.Name = 'Wave Data';

Create and Compare Runs in the Simulation Data Inspector

The Simulink.sdi.compareRuns function compares data contained in Simulink.sdi.Run objects. Use the Simulink.sdi.createRun function to create runs in the Simulation Data Inspector for the data. The Simulink.sdi.createRun function returns the run ID for each created run.

runID1 = Simulink.sdi.createRun('Baseline Run','vars',sig1_ts);
runID2 = Simulink.sdi.createRun('Compare to Run','vars',sig2_ts);

You can use the Simulink.sdi.compareRuns function to compare the runs. The comparison algorithm converts the signal data to the double data type and synchronizes the signal data before computing the difference signal. 

basic_DRR = Simulink.sdi.compareRuns(runID1,runID2);

Check the Summary property of the returned Simulink.sdi.DiffRunResult object to see the result of the comparison. 

basic_DRR.Summary
ans = struct with fields:
       OutOfTolerance: 1
      WithinTolerance: 0
            Unaligned: 0
        UnitsMismatch: 0
                Empty: 0
             Canceled: 0
          EmptySynced: 0
     DataTypeMismatch: 0
         TimeMismatch: 0
    StartStopMismatch: 0
          Unsupported: 0

The difference between the signals is out of tolerance.

Compare Runs and Check for Data Type Match

Depending on your system requirements, you may want the data types for signals you compare to match. You can use the Simulink.sdi.compareRuns function to configure the comparison algorithm to check for and report data type mismatches.

dataType_DRR = Simulink.sdi.compareRuns(runID1,runID2,'DataType','MustMatch');
dataType_DRR.Summary
ans = struct with fields:
       OutOfTolerance: 0
      WithinTolerance: 0
            Unaligned: 0
        UnitsMismatch: 0
                Empty: 0
             Canceled: 0
          EmptySynced: 0
     DataTypeMismatch: 1
         TimeMismatch: 0
    StartStopMismatch: 0
          Unsupported: 0

The result of the signal comparison is now DataTypeMismatch because the data for the baseline signal is double data type, while the data for the signal compared to the baseline is single data type.

Compare Runs and Check for Start and Stop Time Match

You can use the Simulink.sdi.compareRuns function to configure the comparison algorithm to check whether the aligned signals have the same start and stop times. 

startStop_DRR = Simulink.sdi.compareRuns(runID1,runID2,'StartStop','MustMatch');
startStop_DRR.Summary
ans = struct with fields:
       OutOfTolerance: 0
      WithinTolerance: 0
            Unaligned: 0
        UnitsMismatch: 0
                Empty: 0
             Canceled: 0
          EmptySynced: 0
     DataTypeMismatch: 0
         TimeMismatch: 0
    StartStopMismatch: 1
          Unsupported: 0

The signal comparison result is now StartStopMismatch because the signals created in the workspace have different stop times.

Alternatives

You can view and inspect comparison results using the Simulation Data Inspector UI. For more information, see Compare Simulation Data.

For software tests, see the Simulink.sdi.constraints.MatchesSignal constraint.

See Also

| |

Topics

Introduced in R2012b

Simulink Documentation

Support