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

`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

expand all

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

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

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

expand all

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

expand all

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.

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.

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}}\stackrel{^}{i}+\frac{\partial F}{\partial {x}_{2}}\stackrel{^}{j}$`

`$|\nabla F|=\sqrt{{\left(\frac{\partial F}{\partial {x}_{1}}\right)}^{2}+{\left(\frac{\partial F}{\partial {x}_{2}}\right)}^{2}}$`
`$|\nabla F|=\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`.