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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

Centers — Values to subtract from independent variable vectors

[0 0] (default) | vector

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

Description — Requirement description

'' (default) | character vector

Requirement description, specified as a character vector.

Example: 'Requirement 1 for myModel.'

Data Types: char

Method — Method for processing errors

'SSE' (default) | 'SAE' | 'Residuals'

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 — Name of requirement

'' (default) | character vector

Name of requirement, specified as a character vector.

Example: 'Requirement1'

Data Types: char

Scales — Scaling of independent variable vectors

[1 1] (default) | vector of positive numbers

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

Type — Function to be matched

'linear' (default) | 'purequadratic' | 'quadratic'

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.

Examples

Create a Requirement Object to Match a Quadratic Function

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.

Specify Scaling and Centering Values for Independent Variables

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.

Evaluate Function Matching Requirement for One-Dimensional Variable

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.

Version History

Introduced in R2016b