# evalRequirement

Class: sdo.requirements.FunctionMatching
Package: sdo.requirements

Evaluate satisfaction of function matching requirement

## Syntax

```evaluation = evalRequirement(requirement,dependentVar) evaluation = evalRequirement(requirement,dependentVar,indepVar1,...,indepVarN) ```

## Description

`evaluation = evalRequirement(requirement,dependentVar)` evaluates whether the test data `dependentVar` matches the function that is specified in the `Type` property of the `requirement` object. The software computes the specified function using default independent variable vectors with value ```[0 1 2 ...]```. There is an independent variable vector corresponding to each dimension of `dependentVar`, and the length of each independent variable vector is the same as the size of `dependentVar` in the corresponding dimension.

For example, consider a two-dimensional `dependentVar` of size 3-by-2. To compute a linear function of the form ${a}_{0}+{a}_{1}{X}_{1}+{a}_{2}{X}_{2}$, the software uses the independent variable vectors `X1 = [0 1 2]` and `X2 = [0 1]`. The software calculates the fit coefficients `a0`, `a1`, and `a2` and then calculates the error between the test data and the linear function.

`evaluation = evalRequirement(requirement,dependentVar,indepVar1,...,indepVarN)` specifies the independent variable vectors to use for computing the function.

## Input Arguments

expand all

Function matching requirement, specified as an `sdo.requirements.FunctionMatching` object. You specify the function to be matched in `requirement.Type`.

Dependent variable test data to be evaluated, specified as a vector, matrix, or multidimensional array.

Independent variable vectors used for computing the function, specified as real, numeric, monotonic vectors. The independent variable vectors must satisfy the following characteristics:

• The number of independent variables N must equal the number of dimensions of the test data.

For example, use two independent variables when the test data `dependentVar` is a matrix, and use three independent variables when the test data is a three-dimensional array.

• The first independent variable vector specifies coordinates going down test data rows, and the second independent variable vector specifies coordinates going across test data columns. The Nth independent variable vector specifies coordinates along the Nth dimension of `dependentVar`.

• The number of elements in each independent variable vector must match the size of test data in the corresponding dimension.

• The independent variable vectors must be monotonically increasing or decreasing.

In the requirement object, you can specify centering and scaling of the independent variables using the `Centers` and `Scales` properties. The independent variable vectors specified by you are divided by these `Scales` values after subtracting the `Centers` values. For more information, see the property descriptions on the `sdo.requirements.FunctionMatching` reference page.

You can also specify independent variable vectors using a cell array. The number of elements in the cell array must match the number of dimensions in the test data, `dependentVar`. For example, suppose that `dependentVar` is two-dimensional, you can use either of the following syntaxes:

```evaluation = evalRequirement(requirement,dependentVar,independentVar1,independentVar2); evaluation = evalRequirement(requirement,dependentVar,{independentVar1,independentVar2});```

## Output Arguments

expand all

Evaluation of the function matching requirement, returned as a scalar, vector, matrix, or array, depending on the value of `requirement.Method`.

`evalRequirement` computes an error signal that is the difference between test data and the specified function of the independent variables. The error signal is then processed further to compute `evaluation`. The value of `evaluation` depends on the error processing method specified in `requirement.Method`.

`requirement.Method``evaluation`
`'SSE'`

`evaluation` 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 `0` value indicates that the requirement is satisfied. The closer `evaluation` is to `0`, the better the match between the function and test data.

`'SAE'`

`evaluation` 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 `0` value indicates that the requirement is satisfied. The closer `evaluation` is to `0`, the better the match between the function and test data.

`'Residuals'``evaluation` is returned as a vector, matrix, or array of the same size as the test data `dependentVar`. `evaluation` contains the difference between the test data and the specified function of the independent variables.

## Examples

expand all

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.

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.

## Version History

Introduced in R2016b