Main Content

sdo.requirements.FunctionMatching Class

Namespace: sdo.requirements
Superclasses:

Impose function matching constraint on variable

expand all in page

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=a0+a1X1+a2X2

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

match_req = 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.

match_req = sdo.requirements.FunctionMatching(Name=Value) specifies one or more properties using name-value arguments. For example, match_req = sdo.requirements.FunctionMatching(Type="quadratic") creates an sdo.requirements.FunctionMatching object and specifies the function to be matched as quadratic.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes. For example, match_req = 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=a0+a1X1+a2X2

    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=a0+a1X1+a2X12+a3X2+a4X22

  • '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=a0+a1X1+a2X12+a3X2+a4X22+a5X1X2

    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

copyCopy design requirement
getGet design requirement property values
setSet design requirement property values
evalRequirementEvaluate design requirement

Copy Semantics

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

Examples

collapse all

Open Live Script

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.

Open Live Script

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.

Open Live Script

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

See Also

Topics