evalRequirement

Class: sdo.requirements.SmoothnessConstraint
Package: sdo.requirements

Evaluate satisfaction of smoothness constraint requirement

Syntax

evaluation = evalRequirement(requirement,variableData)
evaluation = evalRequirement(requirement,variableData,indepVar1,...,indepVarN)


Description

evaluation = evalRequirement(requirement,variableData) evaluates whether the test data, variableData, satisfies the smoothness constraint requirement that is specified in the requirement object. The software calculates the gradient magnitude of the test data, and compares it to the bound specified in the GradientBound property of the object. For calculating the gradient, the software assumes the spacing between data points in each dimension is 1. A positive evaluation value indicates that the requirement has been violated.

For more information about how the gradient magnitude is calculated, see Algorithms.

evaluation = evalRequirement(requirement,variableData,indepVar1,...,indepVarN) uses indepVar1,...,indepVarN to specify the spacing between test data points in each of the N dimensions of the data.

Input Arguments

requirement — Smoothness constraint requirement

sdo.requirements.SmoothnessConstraint object

Smoothness constraint requirement, specified as an sdo.requirements.SmoothnessConstraint object. In the object, you specify the upper bound on the gradient magnitude.

variableData — Variable data to be evaluated

real numeric vector | real numeric matrix | real numeric array

Variable data to be evaluated, specified as a real numeric vector, matrix, or array.

indepVar1,...,indepVarN — Spacing between points of test data in each dimension

scalar | vector

Spacing between points of test data in each of the N dimensions of the data, specified as a scalar or vector. The independent variable indepVar1 specifies the spacing going down the test data rows, and indepVar2 specifies spacing along the columns. Similarly, indepVarN specifies the spacing along the Nth dimension of test data. You can specify each of indepVar1,...,indepVarN as scalars or vectors:

• Scalars — Specify the spacing between test data in the corresponding dimension as a nonzero scalar. For example, suppose that variableData is two-dimensional, and the spacing between data in the first dimension is 5 and in the second dimension is 2. Specify indepVar1 as 5 and indepVar2 as 2.

• Vectors — Specify the coordinates of the test data in the corresponding dimension as real, numeric, monotonic vectors. The software uses the coordinates to compute the spacing between test data points in the corresponding dimension. The length of the vector must match the length of the test data in the corresponding dimension. You do not have to specify coordinates with uniform spacing.

  For example, suppose that variableData 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 [1 2 3]. In the second dimension, the spacing is not uniform and the coordinates of the test data are [1 2 10 20 30]. Specify indepVar1 as [1 2 3] and indepVar2 as [1 2 10 20 30].

For an example showing the effect of specifying indepVar1,...,indepVarN, see Specify Spacing Between Tests Data Points.

You can also specify spacing between points of test data using a cell array. The number of elements in the cell array must match the number of dimensions in the test data, variableData. For example, suppose that variableData is two-dimensional, and the spacing between data in the first dimension is 2. In the second dimension, the coordinates of the test data are [1 3 6 7 10]. You can use either of the following syntaxes to specify spacing between test data:

evaluation = evalRequirement(requirement,variableData,2,[1 3 6 7 10]);
evaluation = evalRequirement(requirement,variableData,{2,[1 3 6 7 10]});

Output Arguments

evaluation — Evaluation of the smoothness constraint requirement

scalar

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 has been violated.

Examples

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.

Algorithms

To understand how the gradient magnitude is computed, 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 requirement, and returns the normalized value in evaluation.

Version History

Introduced in R2016b