sdo.evaluate

Evaluate cost function for samples

Syntax

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

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

[y,info] = sdo.evaluate(fcn,params,num_samples)

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

Description

[y,info] = sdo.evaluate(fcn,params) evaluates the cost function, fcn, for samples of the parameter space specified by params. The software generates a table of samples based on the parameter space specifications in params.

• If params is an sdo.ParameterSpace object, then sdo.evalute generates random samples according to the ParameterDistributions, RankCorrelation, and Options properties of the parameter space.

• If params is an sdo.GriddedSpace object, then sdo.evalute generates a grid of samples according to the ParameterValues and Options properties of the parameter space.

The function specified by fcn takes the sample values and computes model goal values. A model goal can be a cost (objective), constraint, or assessment of difference between experimental data and model simulation. y is a table containing the results of applying fcn to each of the samples. Additional evaluation information is returned in info.

[y,info] = sdo.evaluate(fcn,params,param_samples) evaluates the cost function for the specified parameter samples. For this syntax, you can specify params as one of these options:

• An sdo.ParameterSpace object

• An sdo.GriddedSpace object

• A vector of parameter objects, which you typically generate using sdo.getParameterFromModel

You typically generate the table of parameter samples param_samples using sdo.sample.

[y,info] = sdo.evaluate(fcn,params,num_samples) generates parameter samples and evaluates the cost function for the generated parameter samples. You specify the number of parameter samples to generate in num_samples. For this syntax, you can specify params as one of these options:

• An sdo.ParameterSpace object

• An sdo.GriddedSpace object

[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

Evaluate Cost Function Value for Parameter Samples

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).

Specify Number of Parameter Samples and Evaluate Cost Function

Create an arbitrary param.Continuous object.

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

Specify the parameter space definition for the model parameter.

ps = sdo.ParameterSpace(p);

Specify the number of parameter samples to generate.

num_samples = 6;

Evaluate the cost function.

[y,info] = sdo.evaluate(@(p) sdoExampleCostFunction(p),ps,num_samples);

Model evaluated at 6 samples.

The software generates six parameter samples as specified and evaluates the cost function.

Store Additional Evaluation Information

Create a cost function that sets the Log field in the output. For this example, use the sdoExampleCostFunctionWithLog cost function. Each time this cost function is called, it logs the parameter value in the Log field.

type("sdoExampleCostFunctionWithLog.m")

function [vals,derivs] = sdoExampleCostFunctionWithLog(params)

% Copyright 2015 The MathWorks, Inc.

% Get the value of x from the parameter object
x = params.Value; 

% Compute the cost and constraint violations.
vals.F    = x.^2;         % Cost
vals.Cleq = x.^2-4*x+1;   % Nonlinear inequality violation
vals.leq  = 2*x/3-3;      % Linear inequality violation
vals.Log = x;             % Additional evaluation information

% Compute the cost and constraint violations.
derivs.F    = 2.*x;     % Cost gradient
derivs.Cleq = 2.*x-4;   % Nonlinear inequality gradient
end

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) sdoExampleCostFunctionWithLog(p),ps);

Model evaluated at 3 samples.

sdo.evaluate returns the information stored in the Log field of the cost function.

info.Log

ans=3×1 cell array
    {[1.0629]}
    {[1.0812]}
    {[0.9254]}

Input Arguments

fcn — Function to be evaluated by sdo.evaluate

function handle

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.

params — Model parameters and states

sdo.ParameterSpace object | sdo.GriddedSpace object | vector of parameter objects

Model parameters and states, specified as one of the following:

• An sdo.ParameterSpace object.

• An sdo.GriddedSpace object.

• A vector of parameter objects, which you typically generate using sdo.getParameterFromModel. To specify the parameters in this way, you must use the syntax that specifies the param_samples input argument.

param_samples — Parameter samples

table

Parameter samples, specified as a table. Typically, you use sdo.sample to generate the samples. 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.

num_samples — Number of parameter samples

finite positive integer

Number of parameter samples to be generated, specified as a finite positive integer.

opts — Evaluation options

sdo.EvaluateOptions object

Evaluation options, specified as an sdo.EvaluateOptions object.

Output Arguments

y — Cost function evaluation

table

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 the parameter samples with the param_samples argument, Ns is equal to the number of rows of param_samples. Otherwise, sdo.evaluate generates the samples, and:

• If params is a sdo.ParameterSpace object, then Ns = 2Np+1, where Np is the number of parameters in params.

• If params is a sdo.GriddedSpace containing only gridded parameters, then Ns is the number of samples in the grid, as specified in the gridding options of params.

info — Evaluation information

structure

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

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, set 'UseParallel' to true using sdo.EvaluateOptions.

For more information, see Use Parallel Computing for Sensitivity Analysis.

Version History

Introduced in R2014a

R2025a: Specify number of parameter samples as input argument

You can now choose to specify only the number of parameter samples instead of their values as the input argument in the sdo.evaluate function.