Documentation

# sdo.requirements.FunctionMatching class

Package: sdo.requirements
Superclasses:

Impose function matching constraint on variable

## Description

Use the `sdo.requirements.FunctionMatching` object to impose a function matching constraint on the values of a variable in a Simulink® model. The variable can be a vector, matrix, or a multidimensional array that is a parameter in your model, such as the data of a lookup table in your model. You create the requirement object, and specify the linear or quadratic function that you want the variable to match. For example, for a two-dimensional variable, you can specify that test data from dependent variable `V` match a linear function of independent variables `X1` and `X2`:

`$V={a}_{0}+{a}_{1}{X}_{1}+{a}_{2}{X}_{2}$`

Where, `a0`, `a1`, and `a2` are the fit-coefficients, and `X1` and `X2` are vectors.

You use the `evalRequirement` method to evaluate whether your test data satisfies the specified requirement, and specify the independent variable vectors as inputs to the method. The software calculates the fit-coefficients using the independent variables and test data and then calculates the error between the test data and the specified function of the independent variables.

You can use the requirement object as an input to your cost function and use the `evalRequirement` command in the cost function to evaluate the requirement. You can then use the cost function and `sdo.optimize` to perform response optimization, subject to satisfaction of the specified requirement. If you are performing sensitivity analysis, after you generate parameter samples, you can use the cost function and `sdo.evaluate` to evaluate the requirement for each generated sample.

## Construction

```requirement = sdo.requirements.FunctionMatching``` creates an `sdo.requirements.FunctionMatching` requirement object and assigns default values to its properties. Use dot notation to customize the properties. Use the `evalRequirement` command to evaluate whether test data satisfies the specified requirement.

`requirement = sdo.requirements.FunctionMatching(Name,Value)` creates the requirement object with additional options specified by one or more `Name,Value` pair arguments. `Name` is a property name and `Value` is the corresponding value. `Name` must appear inside single quotes (`''`). You can specify several name-value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

### Input Arguments

#### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Use `Name,Value` arguments to specify properties of the requirement object during object creation. For example, ```requirement = sdo.requirements.FunctionMatching('Type','quadratic')``` creates an `sdo.requirements.FunctionMatching` object and specifies the function to be matched as quadratic.

## Properties

expand all

Values to subtract from the independent variable vectors that you input to the `evalRequirement` method, specified as a vector of length equal to number of independent variables. The number of independent variables equals the dimensionality of the test data. For example, suppose that you specify `Centers` as ```[1 2]``` for a two-dimensional variable with two independent variables. The software subtracts `1` from the first independent variable vector and `2` from the second independent variable vector.

Specify `Centers` to improve numerical conditioning when one or more independent variable vectors have a mean that differs from 0 by several orders of magnitude. If you do not specify independent variable vectors, then the software does not use `Centers`.

The default value of `Centers`, ```[0 0]```, is for a two-dimensional variable. For variables of other dimensions, change the `Scales` and `Centers` properties together using the `set` command. For an example, see Evaluate Function Matching Requirement for One-Dimensional Variable.

Data Types: `double`

Requirement description, specified as a character vector.

Example: `'Requirement 1 for myModel.'`

Data Types: `char`

Method for processing errors during evaluation of requirement by `evalRequirement` command. The command computes an error signal that is the difference between test data and the function of the independent variables specified in the `Type` property. `Method` specifies how the errors are further processed. `Method` is specified as one of the following values:

• `'SSE'` — Sum of squares of the errors

• `'SAE'` — Sum of absolute values of errors

• `'Residuals'` — Errors

Data Types: `char`

Name of requirement, specified as a character vector.

Example: `'Requirement1'`

Data Types: `char`

Scaling of the independent variable vectors that you input to the `evalRequirement` method, specified as a vector of length equal to number of independent variable. The number of independent variables equals the dimensionality of the test data. The independent variable vectors are divided by the corresponding `Scales` value after subtracting the `Centers` values.

For example, suppose that you specify `Centers` as ```[5 50]``` and `Scales` as `[10 100]` for a two-dimensional variable with two independent variables. The software subtracts `5` from the first independent variable vector and divides the result by `10`. The software subtracts `50` from the second independent variable vector and divides the result by `100`.

Specify `Scales` to improve numerical conditioning when independent variable vectors differ from each other by several orders of magnitude. If you do not specify independent variable vectors, then the software does not use `Scales`.

The default value of `Scales`, ```[1 1]```, is for a two-dimensional variable. For variables of other dimensions, change the `Scales` and `Centers` properties together using the `set` command. For an example, see Evaluate Function Matching Requirement for One-Dimensional Variable.

Data Types: `double`

Function to be matched, specified as one of the following:

• `'linear'` — Test data from dependent variable `V` are fit to a linear function. For example, for a two-dimensional variable with independent variables, `X1` and `X2`, the linear function has the form:

`$V={a}_{0}+{a}_{1}{X}_{1}+{a}_{2}{X}_{2}$`

When you use `evalRequirement` to evaluate the requirement for test data, the software calculates the fit coefficients `a0`, `a1`, and `a2` and then calculates the error between the test data and the linear function.

• `'purequadratic'` — Test data are fit to a quadratic function with no cross-terms. For a two-dimensional variable, the pure quadratic function has the form:

`$V={a}_{0}+{a}_{1}{X}_{1}+{a}_{2}{X}_{1}^{2}+{a}_{3}{X}_{2}+{a}_{4}{X}_{2}^{2}$`
• `'quadratic'` — Test data are fit to a quadratic function that includes cross-terms. For a two-dimensional variable, the quadratic function has the form:

`$V={a}_{0}+{a}_{1}{X}_{1}+{a}_{2}{X}_{1}^{2}+{a}_{3}{X}_{2}+{a}_{4}{X}_{2}^{2}+{a}_{5}{X}_{1}{X}_{2}$`

If the test data are one-dimensional, there are no cross-terms and so the computation is the same as when `Type` is `'purequadratic'`.

Data Types: `char`

## Methods

 evalRequirement Evaluate satisfaction of function matching requirement

## Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects (MATLAB).

## Examples

collapse all

Create a requirement object to impose a function matching requirement on the values of a variable.

`Requirement = sdo.requirements.FunctionMatching;`

The object is created with default properties and specifies that test data from the variable must match a linear function.

Specify that test data must match a quadratic function with no cross-terms.

`Requirement.Type = 'purequadratic';`

You can now use the `evalRequirement` command to evaluate whether test data satisfies the requirement.

Create a function matching requirement object for a two-dimensional variable, and specify scaling and centering values for the independent variables.

The `Centers` and `Scales` properties are specified as vectors of length equal to number of independent variables. The number of independent variables equals the dimensionality of the test data.

```Requirement = sdo.requirements.FunctionMatching('Centers',[5 10],... 'Scales',[50 100]);```

When you specify independent variables as inputs to the `evalRequirement` command, the software subtracts `5` from the first independent variable and then divides the result by `10`. The software subtracts `50` from the second independent variable and then divides the result by `100`.

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.