Documentation

# sdo.requirements.SignalTracking class

Package: sdo.requirements

Reference signal to track

## Description

Specify a tracking requirement on a time-domain signal. You can then optimize the model response to track the reference using `sdo.optimize`.

You can specify an equality, upper or lower bound requirement.

## Construction

`track_req = sdo.requirements.SignalTracking` creates an `sdo.requirements.SignalTracking` object and assigns default values to its properties.

```track_req = sdo.requirements.SignalTracking(Name,Value)``` uses additional options specified by one or more `Name,Value` pair arguments. `Name` is a property name and `Value` is the corresponding value. `Name` must appear inside single quotes (`''`). You can specify several name-value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

### Input Arguments

#### 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`.

Use `Name,Value` arguments to specify properties of the requirement object during object creation. For example, ```requirement = sdo.requirements.SignalTracking('Type','>=')``` creates an `sdo.requirements.SignalTracking` object and specifies the `Type` property as a lower bound.

## Properties

`AbsTol`

Absolute tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 –RelTol)yrAbsTol

where yr is the value of the reference at a certain time, yu and yl are the upper and lower tolerance bounds corresponding to that time point.

Default: `0`

`Description`

Requirement description, specified as a character vector. For example, `'Requirement on signal 1'`.

Default: `''`

`InterpolationTimes`

Time points to use when comparing reference and testpoint signals, specified as one of the following values:

• `'Reference only'` — Compare the signals at the time points of the reference signal only

• `'Testpoint only'` — Compare the signals at the time points of the testpoint signal only

• `'Reference and Testpoint'` — Compare the signals at the time points of both the reference and testpoint signals

Linear interpolation is used to compare the signals at the same timepoints.

Default: `'Reference only'`

`Method`

Algorithm for evaluating the requirement when the `Type` property is `'=='`, specified as one of the following values:

• `'SSE'`

• `'SAE'`

• `'Residuals'`

When the requirement is evaluated using `evalRequirement`, the software computes the error between the reference and testpoint signals. This property specifies how the error signal e(t) = ys(t)–yr(t) should be processed.

Default: `'SSE'`

`Name`

Requirement name, specified as a character vector.

Default: `''`

`Normalize`

Enable or disable normalization when evaluating the requirement. The maximum absolute value of the reference signal is used for normalization. Must be `'on'` or `'off'`.

Default: `'on'`

`ReferenceSignal`

Reference signal to track. Must be a MATLAB® `timeseries` object with real finite data points.

Default: `[1x1 timeseries]`

`RelTol`

Relative tolerance used to determine bounds as the signal approaches the reference signal. The bounds on the reference signal are given by:

yu = (1 + RelTol)yr + AbsTol

yl = (1 — RelTol)yrAbsTol

Default: `0`

`RobustCost`

Enable or disable robust treatment of outliers when evaluating the requirement. The software uses a Huber loss function to handle the outliers in the cost function and improves the fit quality. This option reduces the influence of outliers on the estimation without you manually modifying your data.

Must be one of the following:

• `'on'` — When you call the `evalRequirement` method, the software uses a Huber loss function to evaluate the cost for the tracking error outliers. The tracking error is calculated as e(t)=yref(t)-ytest(t). The software uses the error statistics to identify the outliers.

The exact cost function used, F(x), depends on the requirement evaluation `Method`.

Method NameCost Function for NonoutliersCost Function for Outliers
`'SSE'`

`$F\left(x\right)=\sum _{t\in NOL}e\left(t\right)×e\left(t\right)$`

NOL is the set of nonoutlier samples.

`$F\left(x\right)=\sum _{t\in OL}w×|e\left(t\right)|$`

w is a linear weight. OL is the set of outlier samples.

`'SAE'`

`$F\left(x\right)=\sum _{t\in NOL}|e\left(t\right)|$`

NOL is the set of nonoutlier samples.

`$F\left(x\right)=\sum _{t\in OL}w$`

w is a constant value. OL is the set of outlier samples.

`'Residuals'`

The software does not remove the outliers.

`$F\left(x\right)=\left[\begin{array}{c}e\left(0\right)\\ ⋮\\ e\left(N\right)\end{array}\right]$`

N is the number of samples.

• `'off'`

Default: `'off'`

`Type`

Tracking requirement type, specified as one of the following values:

• `'=='` — Tracking objective.

`'<='` — Upper bound

• `'>='` — Lower bound

Default: `'=='`

`Weights`

Weights to use when evaluating the tracking error between the reference and testpoint signals. Use weights to increase or decrease the significance of different time points.

Must be real finite positive vector with the same number of elements as the `Time` property of the MATLAB `timeseries` object in the `ReferenceSignal` property.

## Methods

 evalRequirement Evaluate tracking requirement

## Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects (MATLAB).

## Examples

Construct a signal tracking object and specify a reference signal.

```r = sdo.requirements.SignalTracking; r.ReferenceSignal = timeseries(1-exp(-(0:10)'));```

Alternatively, you can specify the reference signal during construction.

```r = sdo.requirements.SignalTracking(... 'ReferenceSignal',timeseries(1-exp(-(0:10)'))); ```

## Alternatives

Use `getbounds` to get the bounds specified in a Check Against Reference block.