evalRequirement
Evaluate design requirement
Syntax
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.
Timedomain 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.
Frequencydomain requirements — Determine if the response of a linear system satisfies bounds on frequencydomain characteristics, such as bode magnitude, damping ratio, and stability margins. Creating and evaluating frequencydomain requirements requires Simulink^{®} Control Design™ software.
TimeDomain Requirements
evaluates whether the signals specified in timeEval
= evalRequirement(timeReq
,signal
)signal
satisfy the
timedomain requirements specified in timeReq
. You can evaluate the
following timedomain requirements.
sdo.requirements.SignalBound
— Piecewiselinear upper and lower boundssdo.requirements.SignalTracking
— Reference signal trackingsdo.requirements.StepResponseEnvelope
— Step response envelopesdo.requirements.PhasePlaneEllipse
— Elliptical phaseplane trajectory boundssdo.requirements.PhasePlaneRegion
— Piecewiselinear phaseplane trajectory bounds
Variable Requirements
evaluates whether the variable data in varEval
= evalRequirement(varReq
,varData
)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 of1
.sdo.requirements.MonotonicVariable
— Constrain a variable to be monotonically increasing or decreasing.
specifies independent variable data when evaluating an
varEval
= evalRequirement(varReq
,varData
,indepVar1,...,indepVarN
)sdo.requirements.FunctionMatching
or
sdo.requirements.SmoothnessConstraint
requirement.
FrequencyDomain Requirements
evaluates whether the linear system specified in freqEval
= evalRequirement(freqReq
,linsys
)linsys
satisfies the
frequencydomain requirements specified in freqReq
. You can evaluate
the following frequencydomain requirements for a linear system.
sdo.requirements.BodeMagnitude
— Piecewiselinear bounds on the Bode magnitudesdo.requirements.ClosedLoopPeakGain
— Bounds on closedloop peak gainsdo.requirements.GainPhaseMargin
— Gain and phase marginsdo.requirements.OpenLoopGainPhase
— Piecewiselinear bounds on Nichols responsesdo.requirements.PZDampingRatio
— Damping ration of system polessdo.requirements.PZNaturalFrequency
— Natural frequency of system polessdo.requirements.PZSettlingTime
— Bounds on real component of system polessdo.requirements.SingularValue
— Piecewiselinear bounds on singular values
Examples
Evaluate Signal Tracking Requirement
Create the reference data.
time = (0:0.1:10)'; data = 1exp(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(1exp(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 reuse 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 = 1exp(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(1exp(time/2),time);
Evaluate the signal tracking requirement.
c = evalRequirement(req,sig,ref);
Evaluate PiecewiseLinear Bound on Signal
req = sdo.requirements.SignalBound; sig = timeseries(1exp((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(1exp((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:
Distance from upper bound for the overshoot
Distance from upper bound for the settling time
Distance from lower bound for the undershoot
Distance from lower bound for the % rise
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 PiecewiseLinear 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(1exp((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 piecewiselinear 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 outofbound 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 outof 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 outofbound 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 xaxis radius of the ellipse is 1 and a yaxis radius is 0.5.
Specify the test signal data as timeseries
objects.
signal1 = timeseries(1exp((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 nby2 array. The first column corresponds to the first signal, the xvalue of the phase plane trajectory. The second column corresponds to the second signal, the yvalue 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 OneDimensional Variable
Create a requirement object to match onedimensional variable data to a linear function.
Requirement = sdo.requirements.FunctionMatching;
Specify the Centers
and Scales
properties for a onedimensional variable by using the set
command. You specify these properties because their default values are for a twodimensional variable.
set(Requirement,'Centers',0,'Scales',1);
Specify test data for the onedimensional variable.
dependentVariable = 0.5+5.*(1:5);
Evaluate the requirement.
evaluation = evalRequirement(Requirement,dependentVariable)
evaluation = 5.6798e30
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 TwoDimensional 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 crossterms.
Create 2dimensional 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.3950e29
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 crossterms.
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 purequadratic function as well as dependentVariable
fits the function.
Evaluate Smoothness Constraint on a OneDimensional Variable
Create a requirement object to constrain the gradient magnitude of a onedimensional variable to 5.5.
Requirement = sdo.requirements.SmoothnessConstraint('GradientBound',5);
Specify test data for the onedimensional 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 onedimensional 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 2dimensional variable to be below 5.5.
Requirement = sdo.requirements.SmoothnessConstraint;
Requirement.GradientBound = 5.5;
Specify 2dimensional 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 1dimensional variable as monotonically decreasing.
Requirement.Type = {'>'};
Specify test data for a 1dimensional 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 2dimensional 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 2dimensional 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(76)= 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 nonzero 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 nonzero Evaluation(2)
.
Evaluate Frequency Domain Requirement
You can evaluate frequencydomain 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 frequencydomain requirements. For example, evaluate the transfer function using a default damping ration requirement.
req2 = sdo.requirements.PZDampingRatio; c2 = evalRequirement(req2,sys);
Input Arguments
timeReq
— Timedomain design requirement
design requirement object
Timedomain design requirement to evaluate, specified as one of the design requirement objects in the following table.
TimeDomain Requirement  Description 

sdo.requirements.SignalBound  Define piecewiselinear upper or lower amplitude bounds on a timedomain signal. For an example, see Evaluate PiecewiseLinear Bound on Signal. 
sdo.requirements.SignalTracking  Compare a timedomain 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 timedomain 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 piecewiselinear bounds. For examples, see Evaluate PiecewiseLinear Bound on Phase Plane Trajectory and Specify Bounding Region With Multiple Edges and Evaluate the Requirement. 
signal
— Timedomain signals
timeseries
object  numeric array  dynamic system model  two commaseparated 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
.
TimeDomain Requirement (  Signals to Evaluate ( 

sdo.requirements.SignalBound  Specify signals to evaluate as one of the following:

sdo.requirements.SignalTracking  
sdo.requirements.StepResponseEnvelope  Specify stepresponse signals to evaluate as one of the following:

sdo.requirements.PhasePlaneEllipse  Specify two signals to evaluate as one of the following:

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
.
varReq
— Variable design requirement
design requirement object
Variable design requirement to evaluate, specified as one of the design requirement objects in the following table.
varData
, varData1
, varData2
— Variable data
vector  array
Variable data to evaluate, specified as a numeric vector or an Ndimensional 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 twodimensional 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 twodimensional,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]
andindepVar2
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]
andindepVar2
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
.
freqReq
— Frequencydomain design requirement
design requirement object
Frequencydomain design requirement to evaluate, specified as one of the design requirement objects in the following table. Creating and evaluating frequencydomain requirements requires Simulink Control Design software.
For an example of evaluating frequencydomain requirements, see Evaluate Frequency Domain Requirement.
FrequencyDomain Requirement  Description 

sdo.requirements.BodeMagnitude  Specify frequencydependent piecewiselinear upper and lower magnitude bounds on the Bode magnitude of a linear system. 
sdo.requirements.ClosedLoopPeakGain  Specify lower or equality bounds on the closedloop 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 piecewiselinear bounds on the Nichols (gainphase) 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 frequencydependent piecewiselinear 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:
Continuoustime or discretetime numeric LTI models, such as
tf
(Control System Toolbox),zpk
(Control System Toolbox), orss
(Control System Toolbox) models.Generalized or uncertain LTI models, such as
genss
(Control System Toolbox) oruss
(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.
Frequencyresponse data models, such as
frd
(Control System Toolbox),genfrd
(Control System Toolbox), andufrd
models. These models are not supported whenfreqReq
is ansdo.requirements.PZDampingRatio
,sdo.requirements.PZNaturalFrequency
, or ,sdo.requirements.PZSettlingTime
object.
Output Arguments
timeEval
— Timedomain requirement evaluation result
scalar  vector  array
Timedomain 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.
TimeDomain Requirement (  Evaluation Result 

sdo.requirements.SignalBound  Maximum signed distance of the signal in If 
sdo.requirements.SignalTracking  If the If the

sdo.requirements.StepResponseEnvelope  Maximum distances between The evaluations of the step response bounds are returned in the following order.
Here, the The final value in 
sdo.requirements.PhasePlaneEllipse  Evaluation of the phase plane ellipse requirement, returned as a
scalar or column vector depending on the

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

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 (  Evaluation Result  

sdo.requirements.FunctionMatching 
 
sdo.requirements.MonotonicVariable  Evaluation of the monotonic requirement, returned as a column vector.
The number of elements in  
sdo.requirements.RelationalConstraint  Evaluation of the relational constraint requirement, returned as a
vector or array with the same dimensions as Each element in
Here,  
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
— Frequencydomain requirement evaluation result
scalar  vector  array
Frequencydomain 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 frequencydomain requirement.
FrequencyDomain Requirement (  Evaluation Result 

sdo.requirements.BodeMagnitude  Column vector indicating the maximum signed distance of the system
gain to each bound specified in 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
If 
sdo.requirements.GainPhaseMargin  If the When
If 
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 When
When 
sdo.requirements.PZNaturalFrequency  If the When
When 
sdo.requirements.PZSettlingTime  If the When
When 
sdo.requirements.SingularValue  Column vector indicating the maximum signed distance of the system
gain to each bound specified in 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 twodimensional variable that is a function of independent
variables x_{1}
and
x_{2}
. 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 Ndimensional 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 R2011bR2017a: 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 variablesdo.requirements.SmoothnessConstraint
— Bounds on gradient magnitude of variablesdo.requirements.RelationalConstraint
— Relational constraint between two variablessdo.requirements.FunctionMatching
— Linear or quadratic function matching constraint on a variablesdo.requirements.PhasePlaneEllipse
— Elliptic bound on phase plane trajectorysdo.requirements.PhasePlaneRegion
— Piecewiselinear 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.
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
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.
Select a Web Site
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: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 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)