**Package: **Simulink.sdi.constraints

**Superclasses: **`matlab.unittest.constraints.Constraint`

Constraint that compares time series data with tolerances using the Simulation Data Inspector

Use the `Simulink.sdi.constraints.MatchesSignal`

constraint to compare
time series data against an expected value as part of a test. You can configure the constraint
to use a combination of absolute, relative, and time tolerance values for the comparison. You
can also specify additional options to configure the comparison behavior using a `Simulink.sdi.constraints.MatchesSignalOptions`

object or using one or more name-value pair
arguments. For more information about how tolerances and alignment options affect
comparisons, see How the Simulation Data Inspector Compares Data.

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™

`MatchesSignal(expVal)`

creates a constraint that determines
whether time series data representing an actual value matches the data specified by the
expected value, expVal.

`MatchesSignal(`

creates a constraint with additional properties
specified by one or more `expVal`

,`Name,Value`

)`Name,Value`

pair arguments.

Specify optional
comma-separated pairs of `Name,Value`

arguments. `Name`

is
the argument name and `Value`

is the corresponding value.
`Name`

must appear inside quotes. You can specify several name and value
pair arguments in any order as
`Name1,Value1,...,NameN,ValueN`

.

`'IgnoringDataTypes',true`

`'IgnoringDataTypes'`

— Constraint behavior when data types do not match`false`

(default) | `true`

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

**Example: **`'IgnoringDataTypes',true`

`'IgnoringSignalsNotAligned'`

— Constraint behavior when signals do not align`false`

(default) | `true`

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

**Example: **`'IgnoringSignalsNotAligned',true`

`'IgnoringExtraData'`

— Constraint behavior when the actual value covers a different time interval from the expected value`false`

(default) | `true`

Configure the 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.

**Example: **`'IgnoringExtraData',true`

`'AligningBy'`

— Signal alignment criteriastring array

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`

— Simulink identifier. For more information, see Locate Diagram Components Using Simulink Identifiers.`SignalName`

— The name of the signal.`DataSource`

— Path of the variable.

**Example: **`'AligningBy',["SignalName","BlockPath"]`

specifies
signal alignment by signal name and then by block path.

`Expected`

— Expected value to use as the baseline for the comparisontime series data

Expected value to use as the baseline for the comparison. The data for the expected
value must pair data values with time. The data can be in any format supported by the
Simulation Data Inspector. The Simulation Data Inspector requires data in a format that
associates sample values with time. Supported formats include
`timeseries`

, `Structure with time`

, and
`Dataset`

.

`GetAccess` | `public` |

`SetAccess` | `immutable` |

`MatchesSignalOptions`

— Constraint comparison configuration options`Simulink.sdi.constraints.MatchesSignalOptions`

`Simulink.sdi.constraints.MatchesSignalOptions`

object that specifies options
to configure the comparison for the constraint. By default, the comparison uses the
default alignment settings for the Simulation Data Inspector and has strict acceptance
criteria, meaning that the comparison does not ignore any checks. You can use the
`MatchesSignalOptions`

property to configure how the constraint
aligns signals in the expected and actual runs and whether tests using the constraint
are sensitive to:

The actual value having a different data type from the expected value.

One or more signals not aligning between the expected and actual runs.

The actual value containing data outside the time interval defined by the expected value.

You can specify the `MatchesSignalOptions`

property for the
constraint using individual name-value pair
arguments or using the name-value pair `'WithOptions'`

with a
`Simulink.sdi.constraints.MatchesSignalOptions`

object as the value. When
you specify the `MatchesSignalOptions`

property using a
`MatchesSignalOptions`

object, you can use a single name-value pair to
configure all the options for comparisons that use the constraint.

`GetAccess` | `public` |

`SetAccess` | `immutable` |

**Data Types: **`Simulink.sdi.constraints.MatchesSignalOptions`

`AbsTol`

— Absolute tolerance for comparison0 (default) | scalar

Absolute tolerance for comparisons using the constraint. For details about how the Simulation Data Inspector uses tolerance values in comparisons, see How the Simulation Data Inspector Compares Data.

**Example: **`0.1`

**Example: **`2`

`GetAccess` | `public` |

`SetAccess` | `immutable` |

**Data Types: **`double`

`RelTol`

— Relative tolerance for comparison0 (default) | scalar

Relative tolerance for comparisons using the constraint. For example, specify
`0.1`

to use a 10% tolerance for the comparison. For details about
how the Simulation Data Inspector uses tolerance values in comparisons, see How the Simulation Data Inspector Compares Data.

**Example: **`0.05`

`GetAccess` | `public` |

`SetAccess` | `immutable` |

**Data Types: **`double`

`TimeTol`

— Time tolerance for comparison0 (default) | scalar

Time tolerance for comparisons using the constraint, in seconds. For details about how the Simulation Data Inspector uses tolerance values in comparisons, see How the Simulation Data Inspector Compares Data.

**Example: **`0.001`

`GetAccess` | `public` |

`SetAccess` | `immutable` |

**Data Types: **`double`

This example shows how to use the `Simulink.sdi.constraints.MatchesSignal`

constraint to compare time series data using data generated in the workspace. You can use the `MatchesSignal`

constraint to compare data from many sources, including measured test data in a file and logged simulation outputs.

When you use the `MatchesSignal`

constraint, you can specify absolute, relative, and time tolerances to use in the comparison. The `MatchesSignal`

constraint uses the Simulation Data Inspector comparison algorithm, which includes steps for alignment and synchronization. For more information about the algorithm, see How the Simulation Data Inspector Compares Data.

The `MatchesSignal`

constraint uses the Simulation Data Inspector for the time series comparison and requires one of these products:

Simulink®

Signal Processing Toolbox™

MATLAB Coder™

Fixed-Point Designer™

**Create Time Series Data**

This example generates workspace data in `timeseries`

format for illustrative purposes only. You can use the `MatchesSignal`

constraint to compare data from other sources, such as simulation outputs or a file containing test data, and the constraint can compare time series data in any format supported by the Simulation Data Inspector.

In this example, the first signal is a `timeseries`

object containing data for a sine wave with 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';
```

The second signal is also a sine wave at the same frequency, with a slight attenuation and sampled at a different rate. Because the comparison algorithm for the `MatchesSignal`

constraint includes a synchronization step, comparing these two signals with different time vectors does not always result in a test failure. The second signal is also named `Wave Data`

so the alignment algorithm can pair the signals for comparison.

```
time2 = 0:0.05:20;
sig2vals = 0.98*sin(2*pi/5*time2);
sig2_ts = timeseries(sig2vals,time2);
sig2_ts.Name = 'Wave Data';
```

**Create a Test Case and Compare the Signals**

This example uses an interactive test for illustrative purposes. You can use the `MatchesSignal`

constraint with other types of unit tests in the MATLAB testing framework. For example, to write class-based unit tests, see Write Simple Test Case Using Classes (MATLAB).

Create a `TestCase`

instance for interactive use.

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

Compare `sig1_ts`

and `sig2_ts`

using the `MatchesSignal`

constraint. Use `sig1_ts`

for the expected value in the instance of the `MatchesSignal`

constraint.

```
import Simulink.sdi.constraints.MatchesSignal
testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts));
```

Verification failed. --------------------- Framework Diagnostic: --------------------- MatchesSignal failed. --> The following aligned signals did not match: ActualValue ExpectedValue _________________ ___________________ {'<Actual>.Data'} {'<Expected>.Data'} --> Comparison snapshots captured to: --> /tmp/Bdoc19b_1192687_168706/Snapshot_ce9d95d5-17f0-40be-be2f-1ac9da55cf36.png ------------------ Stack Information: ------------------ In /tmp/Bdoc19b_1192687_168706/tp483b69b8/simulink-ex22803619/TestTimeSeriesDataWithTimeToleranceExample.mlx (TestTimeSeriesDataWithTimeToleranceExample) at 14 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/evaluateRegions.p (evaluateRegions) at 0 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/EvaluationOutputsService.p (EvaluationOutputsService.evalRegions) at 0 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/execute.m (execute) at 48 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRun) at 246 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRunConvert) at 202 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (liveCodeToDocbook) at 108 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/build_using_matlab/BML.m (BML) at 13

The diagnostic information shows that the verification failed. Click the link to view the comparison snapshot of both the comparison signals and the difference signal. From the plot, you can see the attenuation creates the difference and causes the comparison to fail.

Specify an absolute tolerance of `0.02`

for the instance of the `MatchesSignal`

constraint to use in the comparison.

`testCase.verifyThat(sig2_ts,MatchesSignal(sig1_ts,'AbsTol',0.02));`

Verification passed.

`MatchesSignal`

Constraint BehaviorThis example shows how to configure the comparison behavior of a `Simulink.sdi.constraints.MatchesSignal`

constraint using a `Simulink.sdi.constraints.MatchesSignalOptions`

object. You can use a `MatchesSignalOptions`

object to configure multiple comparison properties with a single name-value pair input in the construction of the `MatchesSignal`

instance.

**Create Time Series Data**

This example creates workspace data to use for illustrative purposes only. You can use the `MatchesSignal`

constraint to compare data from other sources, such as simulation outputs or a file containing test data, and the constraint can compare time series data in any format supported by the Simulation Data Inspector.

In this example, the first signal is a `timeseries`

object with the name `Wave Data`

that contains data for a sine wave.

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

The second signal is also a sine wave at the same frequency, with a slight attenuation and sampled at a different rate. 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.

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

**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 inerval 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 failed. --> Datatype does not match for the following aligned signals: ActualValue ActualDatatype ExpectedValue ExpectedDatatype _________________ ______________ ___________________ ________________ {'<Actual>.Data'} {'single'} {'<Expected>.Data'} {'double'} ------------------ Stack Information: ------------------ In /tmp/Bdoc19b_1192687_168707/tp224a35ee/simulink-ex71177165/ConfigureMatchesSignalConstraintBehaviorExample.mlx (ConfigureMatchesSignalConstraintBehaviorExample) at 16 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/evaluateRegions.p (evaluateRegions) at 0 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/embeddedoutputs/+matlab/+internal/+editor/EvaluationOutputsService.p (EvaluationOutputsService.evalRegions) at 0 In /mathworks/devel/bat/Bdoc19b/build/matlab/toolbox/matlab/codetools/+matlab/+internal/+liveeditor/@LiveEditorUtilities/execute.m (execute) at 48 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRun) at 246 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (doRunConvert) at 202 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/examples/exampletools/+mwtools/liveCodeToDocbook.m (liveCodeToDocbook) at 108 In /mathworks/devel/bat/Bdoc19b/build/matlab/tools/build_using_matlab/BML.m (BML) at 13

`Simulink.sdi.constraints.MatchesSignalOptions`

| `matlab.unittest.TestCase`

| `matlab.unittest.constraints Package`

| `matlab.unittest.constraints.Constraint`

| `verifyThat`

A modified version of this example exists on your system. Do you want to open this version instead?

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.

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

Select web siteYou can also select a web site from the following list:

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

- América Latina (Español)
- Canada (English)
- United States (English)

- 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)