Simulink.sdi.constraints.MatchesSignalOptions Class

R2026b

Namespace: Simulink.sdi.constraints

Specify comparison options for Simulink.sdi.constraints.MatchesSignal constraint

expand all in page

Description

Use a Simulink.sdi.constraints.MatchesSignalOptions object to configure the comparison behavior and acceptance criteria for an instance of the Simulink.sdi.constraints.MatchesSignal constraint.

Note

The MatchesSignal constraint uses the Simulation Data Inspector to perform comparisons and requires a license for one of these products:

  • Simulink®

  • Signal Processing Toolbox™

  • MATLAB® Coder™

  • Fixed-Point Designer™

Creation

Description

MatchesSignalOptions creates an instance of the Simulink.sdi.constraints.MatchesSignalOptions class with properties that correspond to a constraint that does not ignore any checks and uses the default alignment settings for the Simulation Data Inspector.

example

MatchesSignalOptions(Name=Value) creates an instance of the Simulink.sdi.constraints.MatchesSignalOptions class with comparison behavior using properties specified by one or more name-value arguments.

example

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Constraint behavior when data types do not match, specified as one of these options:

  • false (default) — The constraint checks whether the expected value and actual value data types match.

  • true — The constraint is insensitive to data type mismatches between the expected value and actual value.

Example: IgnoringDataTypes=true

Constraint behavior when units do not match, specified as one of these options:

  • false (default) — The constraint checks whether the expected value and actual value units match.

  • true — The constraint is insensitive to unit mismatches between the expected value and actual value.

Example: IgnoringUnits=true

Constraint behavior when signals do not align, specified as one of these options:

  • false (default) — The constraint checks for signals that do not align between the expected value and actual value.

  • true — The constraint is insensitive to one or more signals not aligning between the expected value and actual value.

Example: IgnoringSignalsNotAligned=true

Constraint behavior when the actual value covers a different time interval from the expected value, specified as one of these options:

  • false (default) — The constraint checks whether the actual value contains data outside the time interval defined by the expected value.

  • true — The constraint is insensitive to the actual value containing data outside the time interval defined by the expected value.

Example: IgnoringExtraData=true

Alignment criteria for the comparison, specified as a string array with one or more of these options listed in the order in which you want them considered:

  • BlockPath — Path to the source block for the signal.

  • SID — Automatically assigned Simulink identifier.

  • SignalName — Name of the signal.

  • DataSource — Path of the variable.

When the expected value contains more than one signal, the Simulation Data Inspector comparison algorithm aligns signals for comparison between the expected and actual values. By default, the Simulation Data Inspector aligns by data source, then by block path, then by SID, and then by signal name. For details about the Simulation Data Inspector alignment algorithm, see How the Simulation Data Inspector Compares Data.

Example: AligningBy=["SignalName","DataSource"]

Properties

expand all

Constraint sensitivity to the actual value having a different data type from the expected value.

  • false — The constraint checks whether the expected value and actual value data types match.

  • true — The constraint is insensitive to data type mismatches between the expected value and actual value.

You can specify the IgnoreDataTypes property in the constructor using the IgnoringDataTypes name-value argument.

Attributes:

GetAccess
public
SetAccess
public

Constraint sensitivity to the actual value having different units from the expected value.

  • false — The constraint checks whether the expected value and actual value units match.

  • true — The constraint is insensitive to unit mismatches between the expected value and actual value.

You can specify the IgnoreUnits property in the constructor using the IgnoringUnits name-value argument.

Attributes:

GetAccess
public
SetAccess
public

Constraint sensitivity to one or more signals not aligning between the expected value and actual value.

  • false — The constraint checks for signals that do not align between the expected value and actual value.

  • true — The constraint is insensitive to one or more signals not aligning between the expected value and actual value.

You can specify the IgnoreSignalsNotAligned property in the constructor using the IgnoringSignalsNotAligned name-value argument.

Attributes:

GetAccess
public
SetAccess
public

Constraint sensitivity to the actual value containing data outside of the time interval defined by the expected value.

  • false — The constraint checks whether the actual value contains data outside the time interval defined by the expected value.

  • true — The constraint is insensitive to the actual value containing data outside the time interval defined by the expected value.

You can specify the IgnoreExtraData property in the constructor using the IgnoringExtraData name-value argument.

Attributes:

GetAccess
public
SetAccess
public

Alignment criteria for the comparison. When the expected value contains more than one signal, the Simulation Data Inspector comparison algorithm aligns signals for comparison between the expected and actual values. By default, the Simulation Data Inspector aligns by data source, then by block path, then by SID, and then by signal name. For details about the Simulation Data Inspector alignment algorithm, see How the Simulation Data Inspector Compares Data.

Specify alignment criteria as a string array with one or more of these options listed in the order in which you want them considered:

  • BlockPath — The path to the source block for the signal.

  • SID — Automatically assigned Simulink identifier.

  • SignalName — The name of the signal.

  • DataSource — Path of the variable.

You can specify the Alignment property in the constructor using the AligningBy name-value argument.

Examples

collapse all

Open Live Script

To configure the comparison behavior of a Simulink.sdi.constraints.MatchesSignal constraint, use a Simulink.sdi.constraints.MatchesSignalOptions object.

Create Time Series Data

This example creates workspace data to use for illustrative purposes only. You can also use the MatchesSignal constraint to compare data from other sources, such as simulation outputs or a file containing test data. The constraint can compare time series data in any format supported by the Simulation Data Inspector.

Create two sine wave signals at the same frequency, but with a slight attenuation and sampled at different rates.

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

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

Because the comparison algorithm for the MatchesSignal constraint includes a synchronization step, comparing these two signals with different time vectors does not necessarily result in a test failure. The second signal is cast to single data type and also named Wave Data so the alignment algorithm can pair the signals for comparison.

Configure a MatchesSignal Instance and Compare the Data

You can use a MatchesSignalOptions object to specify how an instance of the MatchesSignal constraint handles conditions such as mismatched data types and how signals are aligned between the actual and expected data sets. You can specify the properties of the MatchesSignalOptions object to suit the test you want to write. For example, if you want your test to compare data of varying types and a data type match is not functionally relevant, you could set the IgnoreDataTypes property to true.

Create a MatchesSignalOptions object to create a MatchesSignal instance that ignores data type mismatches and data samples outside the time interval the actual and expected signals share.

import Simulink.sdi.constraints.MatchesSignalOptions
opts = MatchesSignalOptions(IgnoringDataTypes=true, IgnoringExtraData=true);

Create a TestCase instance for interactive use and compare sig1_ts and sig2_ts using the MatchesSignal constraint, the MatchesSignalOptions object, and an absolute tolerance of 0.02.

import matlab.unittest.TestCase
testCase = TestCase.forInteractiveUse;

import Simulink.sdi.constraints.MatchesSignal
testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts, AbsTol=0.02, WithOptions=opts))
Verification passed.

The test passes. When you run the same test again without the options defined by the MatchesSignalOptions object, the test fails due to the mismatched data types.

testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts,AbsTol=0.02))
Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    MatchesSignal(<Value>,'AbsTol',0.02) failed.
    --> Data types do not match for the following aligned signals:
        
              Name       ActualSignals    ActualDataType    ExpectedSignals    ExpectedDataType
            _________    _____________    ______________    _______________    ________________
                                                                                               
            Wave Data    <Actual>.Data        single        <Expected>.Data         double     
    
    ------------------
    Stack Information:
    ------------------
    In /tmp/Bdoc26b_3351752_2869049/Editor_ijaai/LiveEditorEvaluationHelperE41bd46d9f6b741efacbf54205d9ba634.m (LiveEditorEvaluationHelperE41bd46d9f6b741efacbf54205d9ba634) at 31
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/runnable/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/doExecute.m (doExecute) at 79
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/runnable/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/execute.m (execute) at 27
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRun) at 465
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRunConvert) at 377
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (liveCodeToDocbook) at 167
    In /mathworks/devel/bat/filer/batfs2566-0/Bdoc26b.3351752/build/matlab/tools/build_using_matlab/BML.m (BML) at 13

Version History

Introduced in R2019a

expand all

See Also

| | | |

Topics