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
getResultsByNameReturn signal comparison results based on signal name
saveResultSave comparison results to an MLDATX file

Examples

collapse all

Open Live Script

You can programmatically specify signal tolerance values to use in comparisons performed using the Simulation Data Inspector. In this example, you compare data collected by simulating a model of an aircraft longitudinal flight control system. Each simulation uses a different value for the input filter time constant and logs the input and output signals. You analyze the effect of the time constant change by comparing results using the Simulation Data Inspector and signal tolerances.

First, load the session file that contains the simulation data.

Simulink.sdi.load('AircraftExample.mldatx');

The session file contains four runs. In this example, you compare data from the first two runs in the file. Access the Simulink.sdi.Run objects for the first two runs loaded from the file.

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

Compare the two runs without specifying any tolerances.

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

Use the getResultByIndex function to access the comparison results for the q and alpha signals. 

qResult = getResultByIndex(noTolDiffResult,1);
alphaResult = getResultByIndex(noTolDiffResult,2);

Check the Status property of each signal result to see whether the comparison result falls within or out of tolerance.

qResult.Status
ans = 
  ComparisonSignalStatus enumeration

    OutOfTolerance


alphaResult.Status
ans = 
  ComparisonSignalStatus enumeration

    OutOfTolerance

The comparison uses a value of 0 for all tolerances, so the OutOfTolerance result means the signals are not identical.

You can further analyze the effect of the time constant by specifying tolerance values for the signals. Specify the tolerances by setting the properties for the Simulink.sdi.Signal objects that correspond to the signals being compared. Comparisons use tolerances specified for the baseline signals. This example specifies a time tolerance and an absolute tolerance.

To specify a tolerance, first access the Signal objects from the baseline run.

runTs1 = Simulink.sdi.getRun(runIDTs1);
qSig = getSignalsByName(runTs1,'q, rad/sec');
alphaSig = getSignalsByName(runTs1,'alpha, rad');

For the q signal, specify an absolute tolerance of 0.1 and a time tolerance of 0.6 using the AbsTol and TimeTol properties, respectively.

qSig.AbsTol = 0.1;
qSig.TimeTol = 0.6;

For the alpha signal, specify an absolute tolerance of 0.2 and a time tolerance of 0.8.

alphaSig.AbsTol = 0.2;
alphaSig.TimeTol = 0.8;

Compare the results again. Access the results from the comparison and check the Status property for each signal.

tolDiffResult = Simulink.sdi.compareRuns(runIDTs1,runIDTs2);
qResult2 = getResultByIndex(tolDiffResult,1);
alphaResult2 = getResultByIndex(tolDiffResult,2);

qResult2.Status
ans = 
  ComparisonSignalStatus enumeration

    WithinTolerance


alphaResult2.Status
ans = 
  ComparisonSignalStatus enumeration

    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 might 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 might 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.

Version History

Introduced in R2012b

See Also

| |

Topics