## Write a Cost Function

A cost function is a MATLAB® function that evaluates your design requirements using design variable values. After writing and saving the cost function, you can use it for estimation, optimization, or sensitivity analysis at the command line.

When you optimize or estimate model parameters, you provide the saved cost function as an input to `sdo.optimize`. At every optimization iteration, `sdo.optimize` calls this function and uses the function output to decide the optimization direction. When you perform sensitivity analysis using `sdo.evaluate`, you generate sample values of the design variables and evaluate the cost function for each sample value using `sdo.evaluate`.

### Anatomy of a Cost Function

To understand the parts of a cost function, consider the following sample function `myCostFunc`. For a design variable x, `myCostFunc` evaluates the objective x2 and the nonlinearity constraint x2-4x+1 <= 0.

```function [vals,derivs] = myCostFunc(params) % Extract the current design variable values from the parameter object, params. x = params.Value; % Compute the requirements (objective and constraint violations) and % assign them to vals, the output of the cost function. vals.F = x.^2; vals.Cleq = x.^2-4*x+1; % Compute the cost and constraint derivatives. derivs.F = 2*x; derivs.Cleq = 2*x-4; end```

This cost function performs the following tasks:

1. Specifies the inputs of the cost function.

A cost function must have as input, `params`, a vector of the design variables to be estimated, optimized, or used for sensitivity analysis. Design variables are model parameter objects (`param.Continuous` objects) or model initial states (`param.State` objects).

Since the cost function is called repeatedly during estimation, optimization, or evaluation, you can specify additional inputs to the cost function to help reduce code redundancy and computation cost. For more information, see Specify Inputs of the Cost Function.

2. Computes the requirements.

Requirements can be objectives and constraints based on model parameters, model signals, or linearized models. In this sample cost function, the requirements are based on the design variable x, a model parameter. The cost function first extracts the current values of the design variables and then computes the requirements.

For information about computing requirements based on model parameters, model signals, or linearized models, see Compute Requirements.

3. Specifies the requirement values as outputs, `vals` and `derivs`, of the cost function.

A cost function must return `vals`, a structure with one or more fields that specify the values of the objective and constraint violations.

The output can optionally include `derivs`, a structure with one or more fields that specify the values of the gradients of the objective and constraint violations. For more information, see Specify Outputs of the Cost Function.

After saving the cost function as a MATLAB file `myCostFunc.m`, to perform the optimization, use the cost function as an input to `sdo.optimize`.

`[param_opt,opt_info] = sdo.optimize(@myCostFunc,params)`

When performing sensitivity analysis, to compute the requirements in the cost function for a range of design variable sample values `paramsamples`, use the cost function as an input to `sdo.evaluate`.

`[y,info] = sdo.evaluate(@myCostFunc,paramsamples)`

### Specify Inputs of the Cost Function

The sample cost function `myCostFunc` takes one input, `params`.

`function [vals,derivs] = myCostFunc(params)`

A cost function must have as input, `params`, a vector of the design variables to be estimated, optimized, or used for sensitivity analysis. Design variables are model parameter objects (`param.Continuous` objects) or model initial states (`param.State` objects). You obtain `params` by using the `sdo.getParameterFromModel` and `sdo.getStateFromModel` commands.

#### Specify Multiple Inputs

Because the cost function is called repeatedly during estimation, optimization, or evaluation, you can specify additional inputs to the cost function to help reduce code redundancy and computation cost. However, `sdo.optimize` and `sdo.evaluate` accept a cost function with only one input argument. To use a cost function that accepts more than one input argument, you use an anonymous function. Suppose that the `myCostFunc_multi_inputs.m` file specifies a cost function that takes `params` and `arg1` as inputs. For example, you can make the model name an input argument, `arg1`, and configure the cost function to be used for multiple models. Then, assuming that all input arguments are variables in the workspace, specify an anonymous function `myCostFunc2`, and use it as an input to `sdo.optimize` or `sdo.evaluate`.

```myCostFunc2 = @(params) myCostFunc_multi_inputs(params,arg1); [param_opt,opt_info] = sdo.optimize(@myCostFunc2,params);```

You can also specify additional inputs using convenience objects provided by Simulink® Design Optimization™ software. You create convenience objects once and pass them as an input to the cost function to reduce code redundancy and computation cost.

For example, you can create a simulator (`sdo.SimulationTest` object) to simulate your model using alternative model parameters without modifying the model, and pass the simulator to your cost function.

```simulator = sdo.SimulationTest(model) myCostFunc2 = @(params) myCostFunc_multi_inputs(params,arg1,arg2,simulator); [param_opt,opt_info] = sdo.optimize(@myCostFunc2,params);```

For more information about the available convenience objects, see Convenience Objects as Additional Inputs. For an example, see Design Optimization to Meet a Custom Objective (Code).

### Compute Requirements

The sample cost function `myCostFunc` computes the requirements based on a model parameter `x`. In general, requirements can be objectives or constraints based on model parameters, model signals, or linearized models. As seen in `myCostFunc`, you can use MATLAB functions to compute the requirements. You can also use the requirements objects that Simulink Design Optimization software provides. These objects enable you to specify requirements such as step-response characteristics, gain and phase margin bounds, and Bode magnitude bounds. You can use the `evalRequirement` method of these objects to evaluate the objective and constraint violations. For a list of available requirement objects, see Convenience Objects as Additional Inputs.

#### Parameter-Based Requirements

If you have requirements on model parameters, in the cost function you first extract the current parameter values, and then compute the requirements.

1. Extract the current parameter value from `params`.

`x = params.Value;`
2. Compute the requirement, and specify it as `vals`, the output of the cost function.

Suppose that the objective to be computed is x2 and the constraint is the nonlinearity constraint x2-4x+1.

```vals.F = x.^2; vals.Cleq = x.^2-4*x+1;```

In the context of optimization, x2 is minimized subject to satisfying the constraints. For sensitivity analysis, the cost and constraints are evaluated for all values of the parameter `params`.

For more information about the output of a cost function, see Specify Outputs of the Cost Function.

For an example of a cost function with a parameter-based requirement, see Design Optimization to Meet a Custom Objective (Code). In this example, you minimize the cylinder cross-sectional area, a design variable in a hydraulic cylinder.

#### Model Signal Requirements

If you have requirements on model signals, in the cost function you simulate the model using current design variable values, extract the signal of interest, and compute the requirement on the signal.

1. Simulate the model using the current design variable values in `param`. There are multiple ways to simulate your model:

• Using `sdo.SimulationTest` object — If an `sdo.SimulationTest` object, `simulator`, is a cost function input, you update the model parameter values using the `Parameters` property of the simulator. Then use `sim` to simulate the model.

```simulator.Parameters = params; simulator = sim(simulator);```

For an example, see Design Optimization to Meet a Custom Objective (Code).

• Using `sdo.Experiment` object — If you are performing parameter estimation based on input-output data defined in an `sdo.Experiment` object, `exp`, update the design variable values associated with the experiment using the `setEstimatedValues` method. Create a simulator using the `createSimulator` method, and simulate the model using the updated model configuration.

```exp = setEstimatedValues(exp,params); simulator = createSimulator(exp,simulator); simulator = sim(simulator);```

For an example, see Estimate Model Parameters Per Experiment (Code).

• Using `sim` command — If you are not using `sdo.SimulationTest` or `sdo.Experiment` objects, use `sdo.setValueInModel` to update the model parameter values, and then call `sim` to simulate the model.

```sdo.setValueInModel('model_name',param); LoggedData = sim('model_name');```
2. Extract the logged signal of interest, `SignalOfInterest`.

Use the `SignalLoggingName` model parameter to get the simulation log name.

```logName = get_param(simulator.ModelName,'SignalLoggingName'); simLog = get(simulator.LoggedData,logName); Sig = get(simLog,'SignalOfInterest')```
3. Evaluate the requirement, and specify it as the output of the cost function.

For example, if you specified a step-response bound on a signal using a `sdo.requirements.StepResponseEnvelope` object, `StepResp`, you can use the `evalRequirement` method of the object to evaluate the objective and constraint violations.

`vals.Cleq = evalRequirement(StepResp,SignalOfInterest.Values);`

For an example, see Design Optimization to Meet Step Response Requirements (Code). For more information about the output of a cost function, see Specify Outputs of the Cost Function.

#### Linearization-Based Requirements

If you are optimizing or evaluating frequency-domain requirements, in the cost function you linearize the model, and compute the requirement values. Linearizing the model requires Simulink Control Design™ software.

Use the `SystemLoggingInfo` property of `sdo.SimulationTest` to specify linear systems to log when simulating the model. For an example, see Design Optimization to Meet Frequency-Domain Requirements (Code). Alternatively, use `linearize` (Simulink Control Design) to linearize the model.

Note

For models in Simulink fast restart mode, you cannot use the `linearize` command.

### Specify Outputs of the Cost Function

The sample cost function `myCostFunc` outputs `vals`, a structure with fields that specify the values of the objective and constraint violations. The second output is `derivs`, a structure with fields that specify the derivatives of the objective and constraint.

`function [vals,derivs] = myCostFunc(params)`

A cost function must output `vals`, a structure with one or more of the following fields that specify the values of the objective and constraint violations:

• `F` — Value of the cost or objective evaluated at `param`.

• `Cleq` — Value of the nonlinear inequality constraint violations evaluated at `param`. For optimization, the solver ensures `Cleq``0`.

• `Ceq` — Value of the nonlinear equality constraint violations evaluated at `param`. For optimization, the solver ensures `Ceq = 0`.

• `leq` — Value of the linear inequality constraint violations evaluated at `param`. For optimization, the solver ensures `leq``0`.

• `eq` — Value of the linear equality constraint violations evaluated at `param`. For optimization, the solver ensures `eq = 0`.

• `Log` — Additional optional information from evaluation.

If you have multiple constraints of one type, concatenate the values into a vector, and specify this vector as the corresponding field value. For instance, if you have a hydraulic cylinder, you can specify nonlinear inequality constraints on the piston position (`Cleq1`) and cylinder pressure (`Cleq2`). In this case, specify the `Cleq` field of the output structure `vals` as:

`vals.Cleq = [Cleq1; Cleq2];`

For an example, see Design Optimization to Meet a Custom Objective (Code).

By default, the `sdo.optimize` command computes the objective and constraint gradients using numeric perturbation. You can also optionally return the gradients as an additional cost function output, `derivs`. Where `derivs` must contain the derivatives of all applicable objective and constraint violations and is specified as a structure with one or more of the following fields:

• `F` — Derivatives of the cost or objective.

• `Cleq` — Derivatives of the nonlinear inequality constraints.

• `Ceq` — Derivatives of the nonlinear equality constraints.

The derivatives are not required for sensitivity analysis. For estimation or optimization, specify the `GradFcn` property of `sdo.OptimizeOptions` as `'on'`.

#### Multiple Objectives

Simulink Design Optimization software does not support multi-objective optimization. However, you can return the objective value (`vals.F`) as a vector that represents the multiple objective values. The software sums the elements of the vector and minimizes this sum. The exception to this behavior is in the use of the nonlinear least squares (`lsqnonlin`) optimization method. The nonlinear least squares method, used for parameter estimation, requires that you return the error residuals as a vector. In this case, the software minimizes the sum square of this vector. If you are tracking multiple signals and using `lsqnonlin`, then concatenate the error residuals for the different signals into one vector. Specify this vector as the `F` field value.

For an example of single-objective optimization using the gradient descent method, see Design Optimization to Meet a Custom Objective (Code).

For an example of multiple-objective optimization using the nonlinear least squares method, see Estimate Model Parameters Per Experiment (Code).

### Convenience Objects as Additional Inputs

A cost function must have as input, `params`, a vector of the design variables to be estimated, optimized, or used for sensitivity analysis. You can specify additional inputs to the cost function using convenience objects provided by the Simulink Design Optimization software. You create convenience objects once and pass them as an input to the cost function to reduce code redundancy and computation cost. For information about specifying additional inputs to the cost function, see Specify Multiple Inputs.

Convenience ObjectClass NameDescription
Simulator objects`sdo.SimulationTest`

Use the simulator object to simulate the model using alternative inputs, model parameters, and initial-state values without modifying the model. Use the `SystemLoggingInfo` property of `sdo.SimulationTest` to specify linear systems to log when you have frequency-domain requirements.

In the cost function, use the `sim` method to simulate the model. Then extract the model response from the object, and evaluate the requirements.

For an example, see Design Optimization to Meet a Custom Objective (Code).

Note

To perform estimation, optimization, or evaluation using Simulink fast restart, it is necessary to create the simulator before the cost function, and then pass the simulator to the cost function.

Requirements objects

Use these objects to specify time-domain and frequency-domain costs or constraints that depend on the design variable values.

In the cost function, use the `evalRequirement` method of the object to evaluate how closely the current design variables satisfy your design requirement.

For an example, see Design Optimization to Meet Step Response Requirements (Code).

Experiment objects`sdo.Experiment`

Use an experiment object to specify the input-output data, model parameters, and initial-state values for parameter estimation.

In the cost function, update the design variable values associated with the experiment using the `setEstimatedValues` method. Then, to simulate the model using the updated model configuration, create a simulator using the `createSimulator` method.

For an example, see Estimate Model Parameters Per Experiment (Code).