evalRequirement

Evaluate design requirement

Syntax

timeEval = evalRequirement(timeReq,signal)

timeEval = evalRequirement(timeReq,signal,ref)

varEval = evalRequirement(varReq,varData)

varEval = evalRequirement(varReq,varData,indepVar1,...,indepVarN)

varEval = evalRequirement(varReq,varData1,varData2)

freqEval = evalRequirement(freqReq,linsys)

Description

Using the evalRequirement function, you can test whether a signal, variable, or linear system satisfies a given design requirement. When writing a cost function, you can use evalRequirement to evaluate the requirements of your design.

You can evaluate the following types of requirements.

• Time-domain requirements — Determine if signals remain within specified bounds or track specified reference signals.

• Variable requirements — Determine if variable data has specified properties, such as monotonicity or smoothness, or if two variables satisfy relational constraints. These requirements can be useful for optimizing lookup table data.

• Frequency-domain requirements — Determine if the response of a linear system satisfies bounds on frequency-domain characteristics, such as bode magnitude, damping ratio, and stability margins. Creating and evaluating frequency-domain requirements requires Simulink^® Control Design™ software.

Time-Domain Requirements

timeEval = evalRequirement(timeReq,signal) evaluates whether the signals specified in signal satisfy the time-domain requirements specified in timeReq. You can evaluate the following time-domain requirements.

• sdo.requirements.SignalBound — Piecewise-linear upper and lower bounds

• sdo.requirements.SignalTracking — Reference signal tracking

• sdo.requirements.StepResponseEnvelope — Step response envelope

• sdo.requirements.PhasePlaneEllipse — Elliptical phase-plane trajectory bounds

• sdo.requirements.PhasePlaneRegion — Piecewise-linear phase-plane trajectory bounds

timeEval = evalRequirement(timeReq,signal,ref) evaluates whether the signals in signal track the reference signal specified by ref. This syntax is supported only when timeReq is an sdo.requirements.SignalTracking object.

Variable Requirements

varEval = evalRequirement(varReq,varData) evaluates whether the variable data in varData, satisfies the requirement specified in varReq. Use this syntax to evaluate one of the following requirements.

• sdo.requirements.FunctionMatching — Constrain a variable to be a linear or quadratic function of independent variables. For this syntax, the default independent variable vector for each dimension is [0 1 2 ...].

• sdo.requirements.SmoothnessConstraint — Define an upper bound for the gradient magnitude between successive variable values. To compute the gradient, this syntax uses a default data spacing of 1.

• sdo.requirements.MonotonicVariable — Constrain a variable to be monotonically increasing or decreasing.

varEval = evalRequirement(varReq,varData,indepVar1,...,indepVarN) specifies independent variable data when evaluating an sdo.requirements.FunctionMatching or sdo.requirements.SmoothnessConstraint requirement.

varEval = evalRequirement(varReq,varData1,varData2) evaluates whether the test data from two variables, varData1 and varData2, satisfy the relational constraint specified in varReq, which must be an sdo.requirements.RelationalConstraint object.

Frequency-Domain Requirements

freqEval = evalRequirement(freqReq,linsys) evaluates whether the linear system specified in linsys satisfies the frequency-domain requirements specified in freqReq. You can evaluate the following frequency-domain requirements for a linear system.

• sdo.requirements.BodeMagnitude — Piecewise-linear bounds on the Bode magnitude

• sdo.requirements.ClosedLoopPeakGain — Bounds on closed-loop peak gain

• sdo.requirements.GainPhaseMargin — Gain and phase margin

• sdo.requirements.OpenLoopGainPhase — Piecewise-linear bounds on Nichols response

• sdo.requirements.PZDampingRatio — Damping ration of system poles

• sdo.requirements.PZNaturalFrequency — Natural frequency of system poles

• sdo.requirements.PZSettlingTime — Bounds on real component of system poles

• sdo.requirements.SingularValue — Piecewise-linear bounds on singular values

Examples

Evaluate Signal Tracking Requirement

Create the reference data.

time = (0:0.1:10)';
data = 1-exp(-time);

Create the signal tracking requirement object. Specify the reference signal.

req = sdo.requirements.SignalTracking;
req.ReferenceSignal = timeseries(data,time);

Obtain the test point signal.

sig = timeseries(1-exp(-time/2),time);

Evaluate the signal tracking requirement.

c = evalRequirement(req,sig);

Evaluate Tracking Using Requirement Object to Specify Error Computation Method

When you estimate parameters for multiple experiments, you repeatedly compare test point and reference signal sets. If you use the same evaluation criteria for all comparisons, you can use the c = evalrequirement(req,sig,ref) syntax. You vary sig and ref, and re-use the requirement object, req. req specifies the estimation error computation options.

Create a reference and test point signal. Then, use a requirement object to evaluate the requirement.

Create the reference signal.

time = (0:0.1:10)';
data = 1-exp(-time);
ref = timeseries(data,time);

Create the signal tracking requirement object. Specify the error computation method.

Specify 'Residuals' as the algorithm for error computation.

req = sdo.requirements.SignalTracking;
req.Method = 'Residuals';

Obtain the test point signal.

sig = timeseries(1-exp(-time/2),time);

Evaluate the signal tracking requirement.

c = evalRequirement(req,sig,ref);

Evaluate Piecewise-Linear Bound on Signal

 req = sdo.requirements.SignalBound;
 sig = timeseries(1-exp(-(0:10)'));
 c = evalRequirement(req,sig);

Evaluate Step Response Requirement

Create a step response requirement.

requirement = sdo.requirements.StepResponseEnvelope;

A requirement is created with the default settling time of 7 seconds.

Specify the signal to be evaluated.

signal = timeseries(1-exp(-(0:10)'));

The signal data extends to 10 seconds.

Evaluate the step response requirement.

evaluation = evalRequirement(requirement,signal)

evaluation = 6×1

   -0.0917
   -0.0099
   -1.0000
   -0.2416
   -0.0092
   -0.0299

The maximum distance of the signal from the step response bounds is returned in evaluation(1:5), followed by the stability value. Negative values indicate that the requirement is satisfied.

The maximum distance from the bounds are returned in the following order:

1. Distance from upper bound for the overshoot

2. Distance from upper bound for the settling time

3. Distance from lower bound for the undershoot

4. Distance from lower bound for the % rise

5. Distance from lower bound for the settling time

evaluation does not include the distance of the signal from bounds beyond 1.5*settling time because the signal data does not extend beyond 1.5*settling time.

Evaluate Piecewise-Linear Bound on Phase Plane Trajectory

Create a default requirement object.

Requirement = sdo.requirements.PhasePlaneRegion;

The requirement object specifies the bounding region as a single edge extending from (-1,0) to (-1,1) in the phase plane defined by two signals. Requirement.Type has the default value of '<='. This value implies the area to the left of the edge is out of bounds, where the forward direction is the direction of creation of the edge.

Specify the test signal data as timeseries objects.

signal1 = timeseries(1-exp(-(0:10)'));
signal2 = timeseries(sin((0:10)'));

Evaluate the requirement.

Evaluation = evalRequirement(Requirement,signal1,signal2)

Evaluation = 
-0.2632

A negative value indicates that the requirement is satisfied, and the phase plane trajectory of the two test signal data is in the bounding region.

Specify Bounding Region with Multiple Edges and Evaluate the Requirement

Create a requirement object to specify a piecewise-linear bound on the phase plane trajectory of two signals. The bound has two edges. The first edge extends from (-4,1) to (2,1). The second edge extends from (2,1) to (2,-4).

Requirement = sdo.requirements.PhasePlaneRegion('BoundX',[-4 2; 2 2],...
    'BoundY',[1 1; 1 -4]);

Specify the bound type as '>='.

Requirement.Type = '>=';

The plot below shows the bounding edges in black. The arrows indicate the direction in which the edges were specified. When you specify the Type property as '>=', the out-of-bound area is always to the right of each edge, where the forward direction is the direction of creation of the edge. As a result, the out-of bound region is the yellow shaded area, and a trajectory point located at (3,3) is in the bounded region.

Evaluate the requirement for the phase plane trajectory point located at (3,3).

Evaluation = evalRequirement(Requirement,[3 3])

Evaluation = 
-0.6389

evalRequirement returns a negative number, indicating the requirement is satisfied.

Now create the requirement by changing the order of specification of the edges.

set(Requirement,'BoundX',[2 2; 2 -4],'BoundY',[-4 1;1 1]);

The plot shows that the edges were created in the opposite order. So, even though the requirement type is still '>=', the out-of-bound region, which is always to the right of the edges, is now flipped.

Evaluate the requirement.

Evaluation = evalRequirement(Requirement,[3 3])

Evaluation = 
0.1087

A positive Evaluation value indicates the requirement has been violated. Thus, for the same requirement type, the trajectory point at (3,3) is out of bounds when the edges are defined in the reverse order.

Evaluate Elliptical Bound on Phase Plane Trajectory

Create a default requirement object.

Requirement = sdo.requirements.PhasePlaneEllipse;

The requirement object specifies the bounding ellipse as an upper bound with center located at [0,0], and no rotation. The x-axis radius of the ellipse is 1 and a y-axis radius is 0.5.

Specify the test signal data as timeseries objects.

signal1 = timeseries(1-exp(-(0:10)'));
signal2 = timeseries(sin((0:10)'));

Evaluate the requirement.

Evaluation = evalRequirement(Requirement,signal1,signal2)

Evaluation = 
0.6997

The default method for requirement evaluation, Requirement.Method is 'Maximum'. Thus, the evalRequirement command computes the signed minimum distance of each point in the phase plane trajectory to the bounding ellipse and then returns the maximum of these distances. A positive value indicates that the at least one point on the phase trajectory lies outside the ellipse and violates the requirement.

To see the signed distance of each of the points on the trajectory to the phase plane ellipse, specify the method for evaluation as 'Residuals'.

Requirement.Method = 'Residuals';

Evaluate the requirement using the new evaluation method.

Evaluation2 = evalRequirement(Requirement,signal1,signal2)

Evaluation2 = 11×1

   -0.5000
    0.4291
    0.5711
   -0.0078
    0.4850
    0.6695
    0.1133
    0.4079
    0.6997
    0.2102
      ⋮

Evaluation2 is the minimum distance of the phase plane trajectory to the bounding ellipse and is a column vector with length equal to the length of the signals.

A negative value indicates that the phase plane trajectory of the two signals at the corresponding time point lies inside the ellipse and satisfies the requirement. A positive value indicates that the phase plane trajectory of the two signals at the corresponding time point lies outside the ellipse and violates the requirement.

You can see that the maximum value in Evaluation2 is the same as Evaluation.

Evaluate Circular Bound on Phase Plane Trajectory

Create a default requirement object.

Requirement = sdo.requirements.PhasePlaneEllipse;

Specify a circular bound of radius 2. The bounding circle is an upper bound.

Requirement.Radius = [2 2];

Specify the test signal data.

Signals = [1 2 3 4 5 6; 10 20 30 40 50 60]';

The test data is specified as an n-by-2 array. The first column corresponds to the first signal, the x-value of the phase plane trajectory. The second column corresponds to the second signal, the y-value of the phase plane trajectory.

Evaluate the requirement.

Evaluation = evalRequirement(Requirement,Signals)

Evaluation =

   58.2993

A positive Evaluation value indicates that the requirement is violated.

Evaluate Function Matching Requirement for One-Dimensional Variable

Create a requirement object to match one-dimensional variable data to a linear function.

Requirement = sdo.requirements.FunctionMatching;

Specify the Centers and Scales properties for a one-dimensional variable by using the set command. You specify these properties because their default values are for a two-dimensional variable.

set(Requirement,'Centers',0,'Scales',1);

Specify test data for the one-dimensional variable.

dependentVariable = 0.5+5.*(1:5);

Evaluate the requirement.

evaluation = evalRequirement(Requirement,dependentVariable)

evaluation = 
5.6798e-30

The software computes the linear function using the default independent variable vector [0 1 2 3 4] because you did not specify any independent variable vectors. There is one independent variable because the number of independent variables must equal the number of dimensions of the test data. The size of the independent variable vector equals the size of the test data.

In this example, the processing method has the default value of 'SSE', so evaluation is returned as a scalar value equal to the sum of squares of the errors. evaluation is very close to zero, indicating that the dependentVariable test data almost matches a linear function. Note that machine precision can affect the value of evaluation at such small values.

Match Quadratic Function to Two-Dimensional Variable Data

Create a requirement object, and specify the function to be matched.

Requirement = sdo.requirements.FunctionMatching('Type','purequadratic');

The object specifies that the variables should match a quadratic function with no cross-terms.

Create 2-dimensional test data for the variable.

[X1,X2] = ndgrid((-1:1),(-4:2:4));
dependentVar = X1.^2 + X2.^2;

Specify independent variable vectors to compute the quadratic function.

The number of independent variable vectors must equal the dimensionality of the test data. In addition, the independent variable vectors must be monotonic and have the same size as the test data in the corresponding dimension.

indepVar1 = (-2:0);
indepVar2 = (-6:2:2);

Evaluate if the test data satisfies the requirement.

evaluation = evalRequirement(Requirement,dependentVar,indepVar1,indepVar2)

evaluation = 
6.3950e-29

The evalRequirement command computes an error signal that is the difference between test data and the function of the independent variable vectors. The error signal is further processed to compute evaluation, based on the error processing method specified in Requirement.Method.

In this example, the processing method has the default value of 'SSE', so evaluation is returned as a scalar value equal to the sum of squares of the errors. evaluation is very close to zero, indicating that the dependentVariable test data almost matches a pure quadratic function.

Create test data with cross-terms.

dependentVariable2 = X1.^2 + X2.^2 + X1.*X2;

Evaluate the requirement for the new test data.

evaluation2 = evalRequirement(Requirement,dependentVariable2,indepVar1,indepVar2)

evaluation2 = 
5.3333

The output evaluation2 is greater than evaluation and is substantially different from 0, indicating that dependentVariable2 does not fit a pure-quadratic function as well as dependentVariable fits the function.

Evaluate Smoothness Constraint on a One-Dimensional Variable

Create a requirement object to constrain the gradient magnitude of a one-dimensional variable to 5.5.

Requirement = sdo.requirements.SmoothnessConstraint('GradientBound',5);

Specify test data for the one-dimensional variable. The data is linear with slope equal to 10.

variableData = 10*(1:5);

Evaluate the requirement.

Evaluation = evalRequirement(Requirement,variableData)

Evaluation = 
1

Since you did not specify the spacing between the test data points, the software computes the gradient magnitude assuming that the spacing is 1. Evaluation is positive, indicating that the test data gradient magnitude is greater than the bound, and the requirement is violated.

Specify Spacing Between Tests Data Points

Create a smoothness constraint requirement object, and specify the gradient bound as 3.

Requirement = sdo.requirements.SmoothnessConstraint;
Requirement.GradientBound = 3;

Specify test data with gradient magnitude value of 2 for a one-dimensional variable. The spacing between the test points is 2.

variableData = 2:2:10;

Evaluate the requirement without specifying the spacing between test points. The software assumes a spacing of 1.

Evaluation = evalRequirement(Requirement,variableData)

Evaluation = 
-0.3333

A negative value indicates that the requirement is satisfied.

Evaluate the requirement using 2 as the spacing between test data points.

Evaluation = evalRequirement(Requirement,variableData,2)

Evaluation = 
-0.6667

The increased spacing reduces the gradient value, and the requirement is still satisfied.

Now evaluate the requirement using 0.5 as the spacing.

Evaluation = evalRequirement(Requirement,variableData,0.5)

Evaluation = 
0.3333

The decreased spacing increases the gradient magnitude value to be above the gradient bound, and the requirement is violated.

Evaluate Smoothness Constraint on a Multidimensional Variable

Create a requirement object to constrain the gradient magnitude of a 2-dimensional variable to be below 5.5.

Requirement = sdo.requirements.SmoothnessConstraint;

Requirement.GradientBound = 5.5;

Specify 2-dimensional test data for the variable. In this example, generate test data with a gradient magnitude of 5, and use 2 as the spacing between the test data points in each dimension.

[X1,X2] = ndgrid(1:2:20,1:2:10);
variableData = 3*X1+4*X2;

The gradient of the test data in the two dimensions is 3 and 4. Therefore, the gradient magnitude of the test data is 5 ( = $$\sqrt{3^2+4^2}$$).

Specify the coordinates of the test data in each dimension.

indepVar1 = [1:2:20];
indepVar2 = [1:2:10];

The specified coordinates indicate that the spacing between the test data points in both dimensions is 2.

Evaluate if the test data satisfies the requirement.

Evaluation = evalRequirement(Requirement,variableData,indepVar1,indepVar2)

Evaluation = 
-0.0909

Evaluation is a negative number, indicating that the requirement is satisfied, and the test data gradient magnitude is below the specified bound.

Evaluate a Monotonic Variable Requirement

Create a requirement object with default properties.

Requirement = sdo.requirements.MonotonicVariable;

Specify the requirement type for a 1-dimensional variable as monotonically decreasing.

Requirement.Type = {'>'};

Specify test data for a 1-dimensional variable.

Data = [20; 15; 25; 26];

Evaluate if the test data satisfies the requirement.

Evaluation = evalRequirement(Requirement,Data)

Evaluation = 
10

Since Evaluation is a positive number, it shows that the requirement is violated. To understand the magnitude of Evaluation, consider the elements of the test data. While 20>15 satisfies the '>' requirement, 15<25 and 25<26 violate the requirement, resulting in a positive Evaluation value. Because the elements 15 and 25 violate the requirement the most, the magnitude of Evaluation is 10, the difference between these elements.

Evaluate Monotonic Variable Requirement for a Multidimensional Variable

Create a requirement object, and specify the monotonicity for a 2-dimensional variable.

Requirement = sdo.requirements.MonotonicVariable('Type',{'<','>'});

The object requires the elements in the first dimension of the variable to be monotonically increasing and the elements in the second dimension to be monotonically decreasing.

Specify 2-dimensional test data for the variable.

Data = [10 5; 20 24;30 33];

Evaluate if the test data satisfies the requirement.

Evaluation = evalRequirement(Requirement,Data)

Evaluation = 2×1

    -9
     4

Evaluation is column vector with size corresponding to the dimensions of the test data.

To understand the magnitude of Evaluation, consider the elements of the test data along each dimension. For the first dimension of the test data, going down the rows, the software checks the '<' requirement. Since 10<20<30 and 5<24<33 both satisfy the requirement, Evaluation(1) is a negative number. Because 24<33 comes closest to violating the requirement, the magnitude of Evaluation for this dimension is 9, the difference between these two elements.

For the second dimension of the test data, going across the columns, the software checks, the '>' requirement. While 10>5 satisfies the requirement, 20<24 and 30<33 do not satisfy the requirement. This results in Evaluation(2) being a positive number, indicating that the requirement is not satisfied. Because the elements 20 and 24 violate the requirement the most, the magnitude of Evaluation(2) is 4, the difference between these elements.

Evaluate a Relational Constraint Requirement

Create a requirement object, and specify that the elements of the first variable should be greater than elements of the second variable.

Requirement = sdo.requirements.RelationalConstraint('Type','>');

Specify test data for the two variables. The test data for both variables must be the same size.

varData1 = [20 -3 7];
varData2 = [20 -1 6];

Evaluate whether the test data satisfy the requirement.

Evaluation = evalRequirement(Requirement,varData1,varData2)

Evaluation = 1×3

    0.0000    2.0000   -1.0000

Evaluation is always the same size as the test data. When the relation type is specified as '>', if the requirement is satisfied, evalRequirement returns a negative number with magnitude equal to the absolute value of difference between the two elements. If the requirement is violated, Evaluation is a positive number with magnitude equal to the absolute value of the difference between the two elements, or 0 if the elements are equal.

The first elements of the two variables are equal, so the requirement is violated and Evaluation(1) is 0, the difference between the elements.

The second elements, -3 and -1, violate the requirement, resulting in a positive Evaluation(2) with value = abs(-3-(-1))= 2.

The third elements, 7 and 6, satisfy the requirement, resulting in a negative Evaluation(3) with value = -abs(7-6)= -1.

Evaluate Equality of Two Variables

Create a requirement object, and specify that the elements of two variables should be equal to each other.

Requirement = sdo.requirements.RelationalConstraint('Type','==');

Specify test data for the two variables.

varData1 = [20 15];
varData2 = [20 55];

Evaluate whether the test data satisfies the requirement.

Evaluation = evalRequirement(Requirement,varData1,varData2)

Evaluation = 1×2

     0   -40

Evaluation is the same size as the test data. When the relation type is specified as '==', if the requirement is satisfied, evalRequirement returns 0, the difference between the elements. If the requirement is violated, Evaluation is a non-zero number equal to the difference between the two elements.

The first elements of the two variables are equal, so the requirement is satisfied and Evaluation(1) is 0.

The second elements, 15 and 55, violate the requirement, resulting in a non-zero Evaluation(2).

Evaluate Frequency Domain Requirement

You can evaluate frequency-domain requirements for an LTI dynamic system model.

For this example, create a transfer function model.

 req = sdo.requirements.BodeMagnitude;
 sys = tf(1,[1 2 2 1]);
 c = evalRequirement(req,sys);

Create a frequency domain requirement. For this example, use a default Bode magnitude requirement.

 req = sdo.requirements.BodeMagnitude;
 

Evaluate the requirement for the transfer function model.

 c = evalRequirement(req,sys);

You can evaluate the same dynamic system model using other frequency-domain requirements. For example, evaluate the transfer function using a default damping ration requirement.

 req2 = sdo.requirements.PZDampingRatio;
 c2 = evalRequirement(req2,sys);

Input Arguments

Time-Domain Requirements

timeReq — Time-domain design requirement

design requirement object

Time-domain design requirement to evaluate, specified as one of the design requirement objects in the following table.

Time-Domain Requirement	Description
sdo.requirements.SignalBound	Define piecewise-linear upper or lower amplitude bounds on a time-domain signal. For an example, see Evaluate Piecewise-Linear Bound on Signal.
sdo.requirements.SignalTracking	Compare a time-domain signal to a given reference signal using equality, upper, or lower bounds. For examples, see Evaluate Signal Tracking Requirement and Evaluate Tracking Using Requirement Object to Specify Error Computation Method.
sdo.requirements.StepResponseEnvelope	Compare a time-domain signal to a step response envelope based on characteristics such as percentage overshoot, settling time, and final value. For an example, see Evaluate Step Response Requirement.
sdo.requirements.PhasePlaneEllipse	Constrain the phase plane trajectory of two signals to an elliptical region. For examples, see Evaluate Elliptical Bound on Phase Plane Trajectory and Evaluate Circular Bound on Phase Plane Trajectory.
sdo.requirements.PhasePlaneRegion	Constrain the phase plane trajectory of two signals to a region with piecewise-linear bounds. For examples, see Evaluate Piecewise-Linear Bound on Phase Plane Trajectory and Specify Bounding Region with Multiple Edges and Evaluate the Requirement.

signal — Time-domain signals

timeseries object | numeric array | dynamic system model | two comma-separated timeseries objects

Time- domain signals to evaluate, specified as timeseries objects, a numeric array, or a dynamic system model, depending on the type of requirement specified in timeReq.

Time-Domain Requirement (timeReq)	Signals to Evaluate (signal)
sdo.requirements.SignalBound	Specify signals to evaluate as one of the following: timeseries object N-by-M array, where the first column represents time and each of the remaining M–1 columns contain a signal channel to evaluate
sdo.requirements.SignalTracking
sdo.requirements.StepResponseEnvelope	Specify step-response signals to evaluate as one of the following: timeseries object N-by-M array, where the first column first column represents time and each of the remaining M–1 columns contain a signal channel to evaluate Linear time-invariant (LTI) dynamic system model, including the following: Numeric LTI model (tf (Control System Toolbox), zpk (Control System Toolbox), or ss (Control System Toolbox)). Using numeric LTI models requires Control System Toolbox™ software. Generalized LTI model (genss (Control System Toolbox)), where the step response is evaluated for the current model value. Using generalized LTI models requires Control System Toolbox software. Uncertain LTI model (uss (Robust Control Toolbox)), where the step response is evaluated for the nominal model. Using uncertain models requires Robust Control Toolbox™ software.
sdo.requirements.PhasePlaneEllipse	Specify two signals to evaluate as one of the following: Two comma-separated timeseries objects, where the first and second objects correspond to the x and y values of the phase plane trajectory, respectively. N-by-2 array, where the first and second columns correspond to the x and y values of the phase plane trajectory, respectively. N is the signal length.
sdo.requirements.PhasePlaneRegion

ref — Reference signal

timeseries object

Reference signal to track, specified as a timeseries object. You can specify a reference signal only when timeReq is an sdo.requirements.SignalTracking object. If you do not specify ref, then define the reference signal in timeReq.

Estimating parameters for multiple experiments requires you to repeatedly compare test point and reference signal sets. If you use the same evaluation criteria for all comparisons, you can vary signal and ref, and reuse the requirement object, timeReq.

Variable Requirements

varReq — Variable design requirement

design requirement object

Variable design requirement to evaluate, specified as one of the design requirement objects in the following table.

Variable Requirement	Description
sdo.requirements.FunctionMatching	Constrain a variable to be a linear or quadratic function of specified independent variables. For examples, see Evaluate Function Matching Requirement for One-Dimensional Variable and Match Quadratic Function to Two-Dimensional Variable Data.
sdo.requirements.MonotonicVariable	Constrain a variable to be monotonically increasing or decreasing. For examples, see Evaluate a Monotonic Variable Requirement and Evaluate Monotonic Variable Requirement for a Multidimensional Variable.
sdo.requirements.RelationalConstraint	Define a relational constraint between two signals. For examples, see Evaluate a Relational Constraint Requirement and Evaluate Equality of Two Variables.
sdo.requirements.SmoothnessConstraint	Define an upper bound for the gradient magnitude between successive variable values. For examples, see Evaluate Smoothness Constraint on a One-Dimensional Variable, Specify Spacing Between Tests Data Points, and Evaluate Smoothness Constraint on a Multidimensional Variable.

varData, varData1, varData2 — Variable data

vector | array

Variable data to evaluate, specified as a numeric vector or an N-dimensional array.

When varReq is an sdo.requirements.RelationalConstraint object, varData1 and varData2 must have the same dimensions.

indepVar1,...,indepVarN — Independent variable data

scalars | vectors | cell array

Independent variable data for evaluating a function matching or smoothness constraint requirement, specified as scalars, vectors, or a cell array. You must specify independent variable data for each of the N dimensions of varData.

Function Matching

When varReq is an sdo.requirements.FunctionMatching object, specify independent variable data as numeric, monotonic vectors.

In the sdo.requirements.FunctionMatching object, you can specify centering and scaling for the independent variables using the Centers and Scales properties, respectively. Each center value is subtracted from the corresponding independent variable data and the result is divided by the corresponding scale value.

You can also specify independent variable data using a single cell array, {indepVar1,indepVar2,...,indepVarN}. The number of elements in the cell array must match the number of dimensions in varData. The length of each independent data vector must match the size of the corresponding dimension of varData.

Smoothness Constraint

When varReq is an sdo.requirements.SmoothnessConstraint object specify the spacing between data points in each data dimension.

To specify uniform spacing along a given dimension, specify the corresponding independent variable as a scalar. For example, suppose that varData is two-dimensional and the spacing between data in the first dimension is 5 and in the second dimension is 2. In this case, specify indepVar1 as 5 and indepVar2 as 2.

To use nonuniform spacing, specify the coordinates of the test data in the corresponding dimension as a numeric, monotonic vector. The software computes the spacing between test data points using the specified coordinates. The length of an independent data vector must match the size of the corresponding dimension of varData.

For example, suppose that:

• varData is two-dimensional,and the length of the test data in the first and second dimension is 3 and 5, respectively.

• The coordinates of the test data in the first dimension are Specify indepVar1 as [1 2 3] and indepVar2 as [1 2 10 20 30]..

• In the second dimension, the spacing is not uniform and the coordinates of the test data are Specify indepVar1 as [1 2 3] and indepVar2 as [1 2 10 20 30]..

In this case, specify indepVar1 as [1 2 3] and indepVar2 as [1 2 10 20 30].

You can also specify spacing between points of test data using a single cell array, {indepVar1,indepVar2,...,indepVarN}. The number of elements in the cell array must match the number of dimensions in varData.

Frequency-Domain Requirements

freqReq — Frequency-domain design requirement

design requirement object

Frequency-domain design requirement to evaluate, specified as one of the design requirement objects in the following table. Creating and evaluating frequency-domain requirements requires Simulink Control Design software.

For an example of evaluating frequency-domain requirements, see Evaluate Frequency Domain Requirement.

Frequency-Domain Requirement	Description
sdo.requirements.BodeMagnitude	Specify frequency-dependent piecewise-linear upper and lower magnitude bounds on the Bode magnitude of a linear system.
sdo.requirements.ClosedLoopPeakGain	Specify lower or equality bounds on the closed-loop peak gain of a linear system.
sdo.requirements.GainPhaseMargin	Specify lower or equality bounds on the gain and phase margin of a linear system.
sdo.requirements.OpenLoopGainPhase	Specify piecewise-linear bounds on the Nichols (gain-phase) response of a linear system.
sdo.requirements.PZDampingRatio	Specify bounds on the damping ratio of the poles of a linear system.
sdo.requirements.PZNaturalFrequency	Specify bounds on the natural frequency of the poles of a linear system.
sdo.requirements.PZSettlingTime	Specify bounds on the real component of the poles of a linear system. The real component of poles are used to approximate the settling time.
sdo.requirements.SingularValue	Specify frequency-dependent piecewise-linear upper and lower bounds on the singular values of a linear system.

linsys — Dynamic system

dynamic system model | model array

Dynamic system to evaluate, specified as a SISO or MIMO dynamic system model or an array of dynamic system models. Dynamic systems that you can use include:

• Continuous-time or discrete-time numeric LTI models, such as tf (Control System Toolbox), zpk (Control System Toolbox), or ss (Control System Toolbox) models.

• Generalized or uncertain LTI models, such as genss (Control System Toolbox) or uss (Robust Control Toolbox) models. Using uncertain models requires Robust Control Toolbox software.

  • For generalized models, the design requirement is evaluated for the response of the model based on its current value.

  • For uncertain models, the design requirement is evaluated for the response of the nominal model only.

• Frequency-response data models, such as frd (Control System Toolbox), genfrd (Control System Toolbox), and ufrd models. These models are not supported when freqReq is an sdo.requirements.PZDampingRatio, sdo.requirements.PZNaturalFrequency, or, sdo.requirements.PZSettlingTime object.

Output Arguments

timeEval — Time-domain requirement evaluation result

scalar | vector | array

Time-domain requirement evaluation result, returned as a numeric scalar, vector, or array, depending on the type of requirement you are evaluating. The following table shows the evaluation result for each requirement.

Time-Domain Requirement (timeReq)	Evaluation Result
sdo.requirements.SignalBound	Maximum signed distance of the signal in signal to each edge defined in timeReq, returned as a column vector. Negative values indicate that the corresponding bound edge is satisfied and positive values indicate that the bound edge is violated. If signal contains multiple channels, timeEval is returned as an array, where each column contains the evaluation result for one channel.
sdo.requirements.SignalTracking	If the Type property of timeReq is '==', then timeEval is a measure of how well the signal matches the reference signal. Specify the algorithm used to compute the tracking measure using the Method property of timeReq. If the Type property of timeReq is '>=' or '<=', then timeEval is the signed distance of the signal to the reference signal. Negative values indicate the bound is satisfied while positive values indicate that the bound is violated. Signed distance of the test point signal to the reference signal, if the Type property of timeReq is '>=' or '<='. Negative values indicate the bound is satisfied while positive values indicate that the bound is violated. evalRequirement compares the reference and test signals only at time points that are in the range of both signals. Time points outside this range are ignored. The software compares the data in the valid time range using the interpolation method specified by the InterpolationTimes of timeReq.
sdo.requirements.StepResponseEnvelope	Maximum distances between signal and the step response bounds, returned as a column vector. Negative values indicate that a bound is satisfied while positive values indicate that a bound is violated. The evaluations of the step response bounds are returned in the following order. Overshoot upper bound — Evaluated using the signal between StepTime and SettlingTime. Settling time upper bound — Evaluated using the signal between SettlingTime and 1.5*SettlingTime. Additional settling time upper bound — If signal extends beyond 1.5*SettlingTime, there is an additional upper bound for the settling time. The maximum signed distance from this upper bound is also returned. The signal between 1.5*SettlingTime and end of signal is used. Undershoot lower bound — Evaluated using the signal between StepTime and RiseTime. % rise lower bound — Evaluated using the signal between RiseTime and SettlingTime. Settling time lower bound — Evaluated using the signal between SettlingTime and 1.5*SettlingTime. Additional settling time lower bound — If signal extends beyond 1.5*SettlingTime, there is an additional lower bound for the settling time. Maximum signed distance from this lower bound is also returned. The signal between 1.5*SettlingTime and end of signal is used. Here, the StepTime, SettlingTime, and RiseTime properties of timeReq represent the step time, settling time, and rise time of the step response envelope, respectively. The final value in timeEval is a measure of stability from the end of signal to infinity. A negative value indicates that the projected signal is not deviating from the step response after the end of signal. A positive value indicates that the projected signal is deviating.
sdo.requirements.PhasePlaneEllipse	Evaluation of the phase plane ellipse requirement, returned as a scalar or column vector depending on the Method property of timeReq. evalRequirement computes the minimum signed distance of each point in the phase plane trajectory to the bounding ellipse. If Method is 'Maximum', then timeEval is a scalar and contains the maximum of the signed distances. A positive value indicates that the requirement has been violated and at least one of the trajectory points lies outside the bounding region. If Method is 'Residuals', then timeEval is a column vector that contains the signed distances of each point in the phase plane trajectory to the bounding ellipse. A positive value in the vector indicates that the requirement has been violated for that time point. A negative value or zero indicates that the requirement has been satisfied for that time point.
sdo.requirements.PhasePlaneRegion	Evaluation of the phase plane region requirement, returned as a scalar value. The software finds the trajectory point that is closest to the bounding region and then calculates timeEval as a scaled distance between this point and the closest bound edge. A positive value indicates that the requirement has been violated and some or all the trajectory points lie outside the specified bounding region. A negative value or zero indicates that the requirement has been satisfied. When timeEval is zero, the closest trajectory point lies on a bound edge.

varEval — Variable requirement evaluation result

scalar | vector | array

Variable requirement evaluation result, returned as a numeric scalar, vector, or array, depending on the type of requirement you are evaluating. The following table shows the evaluation result for each variable requirement.

Variable Requirement (varReq)	Evaluation Result
sdo.requirements.FunctionMatching	evalRequirement computes an error signal that is the difference between the test data and the specified function of the independent variables. The error signal is processed to compute varEval. The value of varEval depends on the error processing method specified in the Method property of varReq. Method evaluation 'SSE' varEval is returned as a scalar value equal to the sum of squares of the errors. A positive value indicates that the requirement is violated, and a zero value indicates that the requirement is satisfied. The closer varEval is to zero, the better the match between the function and test data. 'SAE' varEval is returned as a scalar value equal to the sum of absolute values of the errors. A positive value indicates that the requirement is violated, and a zero value indicates that the requirement is satisfied. The closer varEval is to zero, the better the match between the function and test data. 'Residuals' varEval is returned as a vector, matrix, or array of the same size as the test data varData. varEval contains the difference between the test data and the specified function of the independent variables.
sdo.requirements.MonotonicVariable	Evaluation of the monotonic requirement, returned as a column vector. The number of elements in varEval is the same as the number of dimensions in varData. A positive value in the vector indicates that the requirement has been violated for the corresponding dimension of varData. The magnitude of varEval corresponds to the difference between two successive elements that come closest to violating the requirement.
sdo.requirements.RelationalConstraint	Evaluation of the relational constraint requirement, returned as a vector or array with the same dimensions as varData1 and varData2 Each element in varEval indicates whether the corresponding elements in varData1 and varData2 satisfy the requirement. The value returned for each element of varEval depends on the relation specified in the Type property of varReq. Type varEval Value When Requirement Satisfied varEval Value When Requirement Violated '>' or '<' Negative number with magnitude |v1-v2| Positive number with magnitude |v1-v2| or 0 if the elements are equal. '>=' or '<=' Negative number with magnitude |v1-v2| or 0 if the elements are equal. Positive number with magnitude |v1-v2|. '==' 0 v1-v2. '~=' 0 1 Here, v1 and v2 are the corresponding values from varData1 and varData2, respectively.
sdo.requirements.SmoothnessConstraint	Evaluation of the smoothness constraint requirement, returned as a scalar. A negative value indicates that the bound is satisfied and a positive value indicates that the requirement is violated.

freqEval — Frequency-domain requirement evaluation result

scalar | vector | array

Frequency-domain requirement evaluation result, returned as a numeric scalar, vector, or array, depending on the type of requirement you are evaluating. The following table shows the evaluation result for each frequency-domain requirement.

Frequency-Domain Requirement (freqReq)	Evaluation Result
sdo.requirements.BodeMagnitude	Column vector indicating the maximum signed distance of the system gain to each bound specified in freqReq. Negative values indicate that the bound edge is satisfied and positive values that the bound edge is violated. For MIMO systems, an array of signed distances where each column represents an I/O pair and gives the distance of that I/O pair gain to each edge in the bounds.
sdo.requirements.ClosedLoopPeakGain	If the Type property of freqReq is '<=' or '==', freqEval contains the signed distance of the closed-loop peak gain to the bound. When Type is: '<=', negative values indicate that the bound is satisfied while positive values indicate the bound is violated '==', any value other than 0 indicates that the bound is violated. If Type is 'min', then freqEval contains the peak gain value.
sdo.requirements.GainPhaseMargin	If the Type property of freqReq is '>=' or '==', freqEval contains the signed distances of the computed gain and phase margins to the corresponding bounds. The distance to the gain margin bound appears before the distance to the phase margin bound. When Type is: '>=', negative values indicate that the bound is satisfied while positive values indicate the bound is violated. Unstable loops return positive values. '==', any value other than 0 indicates that the bound is violated. If Type is 'max', then freqEval contains the negative of the gain and phase margins, such that minimizing the values maximizes the margins. Unstable loops return positive values.
sdo.requirements.OpenLoopGainPhase	Vector of maximum signed distances of the response to each piecewise linear bound. Negative values indicate that the bound edge is satisfied and positive values indicate the bound is violated.
sdo.requirements.PZDampingRatio	If the Type property of freqReq is '>=', '<=', or '==', freqEval contains the signed distance of the computed damping ratio to the bound. When Type is: '>=' or '<=', negative values indicate that the bound is satisfied while positive values indicate the bound is violated. '==', any value other than 0 indicates that the bound is violated. When Type is 'max', then freqEval contains the negative of the damping ratio, such that minimizing the value maximizes the damping ratio.
sdo.requirements.PZNaturalFrequency	If the Type property of freqReq is '>=', '<=', or '==', freqEval contains the signed distance of the natural frequency of each system pole to the bound. When Type is: '>=' or '<=', negative values indicate that the bound is satisfied while positive values indicate the bound is violated. '==', any value other than 0 indicates that the bound is violated. When Type is 'max', then freqEval contains the negative of the natural frequencies, such that minimizing the values maximizes the natural frequencies.
sdo.requirements.PZSettlingTime	If the Type property of freqReq is '<=' or '==', freqEval contains the signed distance of the real component of each system pole to the bound. When Type is: '<=', negative values indicate that the bound is satisfied while positive values indicate the bound is violated. '==', any value other than 0 indicates that the bound is violated. When Type is 'min', then freqEval contains pole of the poles, such that minimizing the values minimizes the settling time.
sdo.requirements.SingularValue	Column vector indicating the maximum signed distance of the system gain to each bound specified in freqReq. Negative values indicate that the bound edge is satisfied and positive values that the bound edge is violated. For MIMO systems, an array of signed distances where each column represents an I/O pair and gives the distance of that I/O pair gain to each edge in the bounds.

Algorithms

Smoothness Constraint Gradient Computation

To understand how the gradient magnitude is computed for an sdo.requirements.SmoothnessConstraint requirement, consider test data F from a two-dimensional variable that is a function of independent variables x1 and x2. The gradient is defined as:

$$\nabla F=\frac{\partial F}{\partial x_1}\widehat{i}+\frac{\partial F}{\partial x_2}\widehat{j}$$

The gradient magnitude is:

$$\left|\nabla F\right|=\sqrt{{\left(\frac{\partial F}{\partial x_1}\right)}^2+{\left(\frac{\partial F}{\partial x_2}\right)}^2}$$

Similarly, the gradient for an N-dimensional variable is:

$$\left|\nabla F\right|=\sqrt{{\left(\frac{\partial F}{\partial x_1}\right)}^2+{\left(\frac{\partial F}{\partial x_2}\right)}^2+\cdots +{\left(\frac{\partial F}{\partial x_N}\right)}^2}$$

To compute the gradient magnitude, the software computes the partial derivative in each dimension by computing the difference between successive test data in that dimension and dividing by the spacing between test data in that dimension. If you specify the spacing between test data in each dimension in indepVar1,...,indepVarN, the software uses the specified spacing. If you do not specify the spacing, the software assumes the test data is spaced 1 step apart in each dimension. The software normalizes the final gradient magnitude by the GradientBound property of req, and returns the normalized value in evaluation.

Version History

Introduced in R2011b

R2017a: Specify method for evaluating elliptic phase plane trajectory bounds

The sdo.requirements.PhasePlaneEllipse object has a new Method property that indicates how evalRequirement evaluates an elliptic bound requirement on the phase plane trajectory of two signals in your model. You can specify Method as one of the following values:

• 'Maximum' (default) — evalRequirement returns a scalar value that is the maximum signed distance between the phase plane trajectory and the bounding ellipse.

• 'Residuals' — evalRequirement returns a vector with the signed distance between the ellipse and all the trajectory points.

Starting in R2017a, if you evaluate an sdo.requirements.PhasePlaneEllipse object with default settings, the evalRequirement command returns a scalar with the maximum signed distance between the phase plane trajectory and the bounding ellipse.

Previously, evalRequirement returned the signed distance between the ellipse and all trajectory points. To reproduce this output, set the Method property of the requirement object to 'Residuals' before evaluating the requirement.

R2016b: Evaluate variable and phase plane constraint requirements

Use evalRequirement to evaluate the following new requirements.

• sdo.requirements.MonotonicVariable — Monotonic constraint on a variable

• sdo.requirements.SmoothnessConstraint — Bounds on gradient magnitude of variable

• sdo.requirements.RelationalConstraint — Relational constraint between two variables

• sdo.requirements.FunctionMatching — Linear or quadratic function matching constraint on a variable

• sdo.requirements.PhasePlaneEllipse — Elliptic bound on phase plane trajectory

• sdo.requirements.PhasePlaneRegion — Piecewise-linear bound on phase plane trajectory

R2012b: Reference signal input argument for evaluating signal tracking requirements

When evaluating signal tracking requirements you can specify the reference signal using the new ref input argument. Previously, evalRequirement compared the signal to the reference signal defined in the sdo.requirements.SignalTracking object.

Using the ref input argument, you can iteratively compare a signal to multiple reference signals using the same evaluation criteria.