Main Content

sdo.requirements.FunctionMatching class

Package:sdo.requirements
Superclasses:

Impose function matching constraint on variable

expand all in page

Description

Use thesdo.requirements.FunctionMatchingobject 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 variableVmatch a linear function of independent variablesX1andX2:

V = a 0 + a 1 X 1 + a 2 X 2

Where,a0,a1, anda2are the fit-coefficients, andX1andX2are vectors.

You use theevalRequirementmethod 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 yourcost functionand use theevalRequirementcommand in the cost function to evaluate the requirement. You can then use the cost function andsdo.optimizeto 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 andsdo.evaluateto evaluate the requirement for each generated sample.

Construction

requirement= sdo.requirements.FunctionMatchingcreates ansdo.requirements.FunctionMatchingrequirement object and assigns default values to its properties. Use dot notation to customize the properties. Use theevalRequirementcommand 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 moreName,Valuepair arguments.Nameis aproperty nameandValueis the corresponding value.Namemust appear inside single quotes (''). You can specify several name-value pair arguments in any order asName1,Value1,...,NameN,ValueN.

Input Arguments

Name-Value Arguments

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, whereNameis the argument name andValueis 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 encloseNamein quotes.

UseName,Valuearguments to specifypropertiesof the requirement object during object creation. For example,requirement = sdo.requirements.FunctionMatching('Type','quadratic')creates ansdo.requirements.FunctionMatchingobject and specifies the function to be matched as quadratic.

Properties

expand all

Values to subtract from the independent variable vectors that you input to theevalRequirement方法,指定为一个向量的长度等于number of independent variables. The number of independent variables equals the dimensionality of the test data. For example, suppose that you specifyCentersas[1 2]for a two-dimensional variable with two independent variables. The software subtracts1from the first independent variable vector and2from the second independent variable vector.

SpecifyCentersto 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 useCenters.

The default value ofCenters,[0 0], is for a two-dimensional variable. For variables of other dimensions, change theScalesandCentersproperties together using thesetcommand. For an example, seeEvaluate 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 byevalRequirementcommand. The command computes an error signal that is the difference between test data and the function of the independent variables specified in theTypeproperty.Methodspecifies how the errors are further processed.Methodis 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 theevalRequirement方法,指定为一个向量的长度等于number of independent variable. The number of independent variables equals the dimensionality of the test data. The independent variable vectors are divided by the correspondingScalesvalue after subtracting theCentersvalues.

For example, suppose that you specifyCentersas[5 50]andScalesas[10 100]for a two-dimensional variable with two independent variables. The software subtracts5from the first independent variable vector and divides the result by10. The software subtracts50from the second independent variable vector and divides the result by100.

SpecifyScalesto 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 useScales.

The default value ofScales,[1 1], is for a two-dimensional variable. For variables of other dimensions, change theScalesandCentersproperties together using thesetcommand. For an example, seeEvaluate 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 variableVare fit to a linear function. For example, for a two-dimensional variable with independent variables,X1andX2, the linear function has the form:

    V = a 0 + a 1 X 1 + a 2 X 2

    When you useevalRequirementto evaluate the requirement for test data, the software calculates the fit coefficientsa0,a1, anda2and 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 whenTypeis'purequadratic'.

Data Types:char

Methods

evalRequirement Evaluate satisfaction of function matching requirement

Copy Semantics

Handle. To learn how handle classes affect copy operations, seeCopying 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.

指定测试数据必须匹配一个二次函数tion with no cross-terms.

Requirement.Type ='purequadratic';

You can now use theevalRequirementcommand 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.

TheCentersandScalesproperties 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 theevalRequirementcommand, the software subtracts5from the first independent variable and then divides the result by10. The software subtracts50from the second independent variable and then divides the result by100.

Open Live Script

Create a requirement object to match one-dimensional variable data to a linear function.

Requirement = sdo.requirements.FunctionMatching;

Specify theCentersandScalesproperties for a one-dimensional variable by using thesetcommand. 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', soevaluationis returned as a scalar value equal to the sum of squares of the errors.evaluationis very close to zero, indicating that thedependentVariabletest data almost matches a linear function. Note that machine precision can affect the value ofevaluationat such small values.

Version History

Introduced in R2016b

See Also

|||

Topics