sdo.requirements.SignalTracking

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 bound, or lower bound requirement.

Creation

Syntax

track_req = sdo.requirements.SignalTracking

track_req = sdo.requirements.SignalTracking(Name=Value)

Description

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) specifies one or more properties using name-value arguments. For example, track_req = sdo.requirements.SignalTracking(Type=">=") creates an sdo.requirements.SignalTracking object and specifies the Type property as a lower bound.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes. For example, track_req = 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

0 (default) | nonnegative scalar

Absolute tolerance used to determine bounds as the signal approaches the reference signal, specified as a nonegative scalar.

The bounds on the reference signal are given by:

y_u = (1 + RelTol)y_r + AbsTol

y_l = (1 – RelTol)y_r – AbsTol

where y_r is the value of the reference at a certain time, y_u and y_l are the upper and lower tolerance bounds corresponding to that time point.

Description — Requirement description

'' (default) | character vector

Requirement description, specified as a character vector.

Example: 'Requirement on signal 1'

InterpolationTimes — Time points to use when comparing reference and test point signals

"Reference only" (default) | "Testpoint only" | "Reference and Testpoint"

.

Time points to use when comparing reference and test point 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 test point signal only.

• "Reference and Testpoint" — Compare the signals at the time points of both the reference and test point signals.

Linear interpolation is used to compare the signals at the same time points.

The sdo.requirements.SignalTracking object stores the value as a character vector.

Method — Algorithm for evaluating the requirement

"SSE" (default) | "SAE" | "Residuals"

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 test point signals. This property specifies how the error signal e(t) = y_s(t) – y_r(t) should be processed.

Name — Requirement name

'' (default) | character vector

Requirement name, specified as a character vector.

Normalize — Option to enable normalization

"on" (default) | "off"

Option to enable normalization, specified as "on" to enable normalization and "off" otherwise. The maximum absolute value of the reference signal is used for normalization.

The sdo.requirements.SignalTracking object stores the value as a character vector.

ReferenceSignal — Reference signal to track

timeseries object

Reference signal to track, specified as a timeseries object with real finite data points.

RelTol — Relative tolerance used to determine bounds

0 (default) | nonnegative scalar

Absolute tolerance used to determine bounds as the signal approaches the reference signal, specified as a nonegative scalar.

The bounds on the reference signal are given by:

y_u = (1 + RelTol)y_r + AbsTol

y_l = (1 – RelTol)y_r – AbsTol

where y_r is the value of the reference at a certain time, y_u and y_l are the upper and lower tolerance bounds corresponding to that time point.

RobustCost — Option to enable robust treatment of outliers

"off" (default) | "on"

Option to enable robust treatment of outliers when evaluating the requirement, specified as "on" to enable robust treatment of outliers and "off" otherwise.

When robust treatment of outliers is enabled and you call evalRequirement, the software uses a Huber loss function to evaluate the cost for the tracking error outliers. The tracking error is calculated as e(t)=y_ref(t)-y_test(t). The software uses the error statistics to identify the outliers.

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

The sdo.requirements.SignalTracking object stores the value as a character vector.

Method Name	Cost Function for Nonoutliers	Cost Function for Outliers
"SSE"	$$F(x)={\displaystyle \sum _{t\in NOL}e}(t)\times e(t)$$ NOL is the set of nonoutlier samples.	$$F(x)={\displaystyle \sum _{t\in OL}w}\times |e(t)|$$ w is a linear weight. OL is the set of outlier samples.
"SAE"	$$F(x)={\displaystyle \sum _{t\in NOL}|}e(t)|$$ NOL is the set of nonoutlier samples.	$$F(x)={\displaystyle \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(x)=\left[\begin{array}{c}e(0)\\ ⋮\\ e(N)\end{array}\right]$$ N is the number of samples.

Type — Tracking requirement type

"==" (default) | "<=" | ">="

Tracking requirement type, specified as one of the following values and stored as a character vector:

• "==" — Tracking objective.

  "<=" — Upper bound

• ">=" — Lower bound

Weights — Weights to use when evaluating the tracking error

vector

Weights to use when evaluating the tracking error between the reference and test point signals, specified as a vector with the same number of elements as the Time property of the timeseries object in the ReferenceSignal property.

By default, the weights are all 1.

Object Functions

copy	Copy design requirement
get	Get design requirement property values
set	Set design requirement property values
evalRequirement	Evaluate design requirement

Examples

Create Signal Tracking Requirements Object

Create 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 when you create the object

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

Alternatives

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

Version History

Introduced in R2010b