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 Arguments

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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)yr – AbsTol 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)yr— AbsTol 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 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. '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.

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.