Simulink.sdi.DiffRunResult
Access run comparison results
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
MatlabVersion
— Software version used to create object
character vector
This property is read-only.
Version of MATLAB® used to create the DiffRunResult
object,
returned as a character vector.
RunID1
— Baseline run ID
integer
This property is read-only.
Run identifier for the comparison baseline run, returned as an integer.
RunID2
— ID for run to compare
integer
This property is read-only.
Run identifier of the run to compare, returned as an integer.
Count
— Number of signals compared
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.
DateCreated
— Object creation date
datetime
This property is read-only.
Date and time the Simulink.sdi.DiffRunResult
object was
created, returned as a datetime
object.
Data Types: datetime
GlobalTolerance
— Global tolerance values used for comparison
structure
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.
Summary
— Comparison results summary
structure
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 theintersection
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 todouble
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
.
Options
— Comparison configuration
n-by-2
cell array
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
Status
— Status of run comparison
Completed
| Canceled
| Stopped
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 resultsCanceled
— Comparison ended because the user canceled the comparison operation in the UIStopped
— Comparison ended because the comparison detected a mismatch and was configured to stop on the first mismatch
StopReason
— Signal result that stopped the run comparison
Simulink.sdi.DiffSignalResult
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
getResultByIndex | Return signal comparison result |
getResultsByName | Return signal comparison results based on signal name |
saveResult | Save comparison results to an MLDATX file |
Examples
Analyze Simulation Data Using Signal Tolerances
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
Configure Comparisons to Check Metadata
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.
Version History
Introduced in R2012b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)