# 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(___,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

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

## Version History

Introduced in R2014a