sdo.evaluate

Evaluate cost function for samples

collapse all in page

Syntax

[y,info] = sdo.evaluate(fcn,params)
[y,info] = sdo.evaluate(fcn,params,param_samples)
[y,info] = sdo.evaluate(___,opts)

Description

example

[y,info] = sdo.evaluate(fcn,params) evaluates the cost function, fcn, for samples of the parameter space specified by params (sdo.ParameterSpace object). The software generates a table of samples with 2Np+1 rows and Np columns. These samples are generated based on the parameter space specifications in params, per its ParameterDistributions, RankCorrelation, and Options properties. Np is the number of parameters specified in params. fcn takes sample values and computes model goal values. A model goal could be a cost (objective), constraint, or assessment of difference between experimental data and model simulation. sdo.evaluate applies fcn to each row of the table of samples. y is a table with one column for each model goal output returned by fcn and 2Np+1 rows. Additional evaluation information is returned in info.

[y,info] = sdo.evaluate(fcn,params,param_samples) evaluates the cost function for the specified parameter samples table, param_samples. For this syntax, you can specify params as an sdo.ParameterSpace object or a vector of param.Continuous objects. y is a table with one column for each model goal (cost or constraint) output returned by fcn. y contains as many rows as param_samples.

[y,info] = sdo.evaluate(___,opts) specifies evaluation options that configure the evaluation error handling, display, and parallel computing options. This syntax can include any of the input argument combinations in the previous syntaxes.

Examples

collapse all

Open Live Script

Create an arbitrary param.Continuous object.

p = param.Continuous('x',1);

Specify the parameter space definition for the model parameter.

ps = sdo.ParameterSpace(p);

Evaluate the cost function.

[y,info] = sdo.evaluate(@(p) sdoExampleCostFunction(p),ps);
Model evaluated at 3 samples.

The software generates three samples (2Np+1), and evaluates the sdoExampleCostFunction cost function for each sample. Np is the number of parameters ( = 1).

Input Arguments

collapse all

Cost function to be evaluated by sdo.evaluate, specified as a function handle.

The function requires:

  • One input argument, which is a vector of param.Continuous object.

    To pass additional input arguments, use an anonymous function. For example, new_fcn = @(p) fcn(p,arg1,arg2, ...).

  • One output argument, which is a structure with one or more of the following fields:

    • F — Value of the cost (objective) evaluated at p. F is a 1x1 double.

    • Cleq — Value of the nonlinear inequality constraint violations evaluated at p.

      Cleq is a double mx1 vector, where m is the number of nonlinear inequality constraints.

    • Ceq — Value of the nonlinear equality constraint violations evaluated at p.

      The value is a double rx1 vector, where r is the number of nonlinear equality constraints.

    • leq — Value of the linear inequality constraint violations evaluated at p.

      leq is a double nx1 vector, where n is the number of linear inequality constraints.

    • eq — Value of the linear equality constraint violations evaluated at p.

      eq is a double sx1 vector or [], where s is the number of linear equality constraints.

    • Log — Additional optional information from function evaluation. If specified, this is returned in the Log field of output info.

    Note

    You can use the same function handle fcn for sensitivity analysis, response optimization, or parameter estimation. For optimization and estimation, the solver seeks values of p that minimize F while satisfying constraints Cleq, Ceq, leq and eq. For more information, see sdo.optimize and Write a Cost Function.

Model parameters and states, specified as an sdo.ParameterSpace object or a vector of param.Continuous objects. If you specify params as a vector of param.Continuous objects, you must also specify param_samples.

Parameter samples, specified as a table. param_samples contains columns that correspond to free scalar parameters and rows that are samples of these parameters. Free scalar parameters refers to all the parameters specified by params whose Free property is set to 1. Specifying this property value as 1 indicates that the software can vary the value of this parameter for each evaluation.

Each column name must be equal to the name of the corresponding scalar parameter.

Evaluation options, specified as an sdo.EvaluateOptions object.

Output Arguments

collapse all

Cost function and constraint evaluations, returned as a table.

y is a table with one column for each cost or constraint output returned by fcn, and Ns rows.

If you specify param_samples, Ns is equal to the number of rows of param_samples. Otherwise, Ns is equal to 2Np+1. Np is the number of parameters specified in params.

Evaluation information, returned as a structure with the following fields:

  • Status — Evaluation status for each sample, returned as a cell array of character vectors.

    Each entry of the cell array is one of the following character vectors:

    • 'success' — Model evaluation was successful

    • 'failure' — Model evaluation resulted in all NaN results

    • 'error' — Model evaluation resulted in an error

  • Log — Additional evaluation information retrieved from the Log field of the cost function, fcn.

  • Stats — Time to evaluate all samples, returned as a structure with the following fields:

    • StartTime — Evaluation start time, returned as a six-element date vector containing the current date and time in decimal form: [year month day hour minute seconds]

    • EndTime — Evaluation end time, returned as a six-element date vector containing the current date and time in decimal form: [year month day hour minute seconds]

    To determine the total evaluation time, use etime(info.Stats.EndTime,info.Stats.StartTime).

Extended Capabilities

See Also

| | | |

Topics

Introduced in R2014a

Simulink Design Optimization Documentation

Support