Surrogate Optimization Options

Algorithm Control

To control the surrogate optimization algorithm, use the following options.

ConstraintTolerance — The constraint tolerance is not used as a stopping criterion. It is used to determine feasibility with respect to nonlinear constraints. The tolerance is satisfied when max(fun(x).Ineq) <= ConstraintTolerance, and otherwise is violated. The default value is 1e-3.
InitialPoints — Specify initial points in one of two ways.
- Matrix — Each row of the matrix represents an initial point. The length of each row is the same as the number of elements in the bounds lb or ub. The number of rows is arbitrary. surrogateopt uses all the rows to construct the initial surrogate. If there are fewer than MinSurrogatePoints rows, then surrogateopt generates the remaining initial points. surrogateopt evaluates the objective function at each initial point.
- Structure — The structure contains the field X and, optionally, the fields Fval and Ineq. The X field contains a matrix where each row represents an initial point. The Fval field contains a vector representing the objective function values at each point in X. Passing Fval saves time for the solver, because otherwise the solver evaluates the objective function value at each initial point. The Ineq field contains a matrix containing nonlinear inequality constraint values. Each row of Ineq represents one initial point, and each column represents a nonlinear constraint function value at that point. Passing Ineq saves time for the solver, because otherwise the solver evaluates the constraint function values at each initial point.
MinSurrogatePoints — Number of initial points used for constructing the surrogate. Larger values lead to a more accurate finished surrogate, but take more time to finish the surrogate. surrogateopt creates this number of random points after each switch to the random generation phase. See Surrogate Optimization Algorithm.
When BatchUpdateInterval > 1, the minimum number of random sample points used to create a surrogate is the larger of MinSurrogatePoints and BatchUpdateInterval.
MinSampleDistance — This option controls two aspects of the algorithm.
- During the phase to estimate the minimum value of the surrogate, the algorithm generates random points at which to evaluate the surrogate. If any of these points are closer than MinSampleDistance to any previous point whose objective function value was evaluated, then surrogateopt discards the newly generated points and does not evaluate them.
- If surrogateopt discards all of the random points, then it does not try to minimize the surrogate and, instead, switches to the random generation phase. If the surrogateoptplot plot function is running, then it marks this switch with a blue vertical line.
BatchUpdateInterval — This option controls three aspects of the algorithm:
- Number of function evaluations before the surrogate is updated.
- Number of points to pass in a vectorized evaluation. When UseVectorized is true, surrogateopt passes a matrix of size BatchUpdateInterval-by-nvar, where nvar is the number of problem variables. Each row of the matrix represents one evaluation point. For the final iteration (the one that causes MaxFunctionEvaluations function evaluations), if MaxFunctionEvaluations is not an integer multiple of BatchUpdateInterval, surrogateopt passes a matrix with fewer than BatchUpdateInterval rows.
- When BatchUpdateInterval > 1, the minimum number of random sample points used to create a surrogate is the larger of MinSurrogatePoints and BatchUpdateInterval.
Output functions and plot functions are updated after each batch is evaluated completely.

For details, see Surrogate Optimization Algorithm.

Stopping Criteria

Generally, the algorithm stops only when it reaches a limit that you set in the solver options. Additionally, a plot function or output function can halt the solver.

Stopping Option	Stopping Test	Exit Flag
`MaxFunctionEvaluations`	The solver stops after it completes `MaxFunctionEvaluations` function evaluations. When computing in parallel, the solver stops all workers after a worker returns with the final function evaluation, leaving some computations incomplete and unused.	`0`
`MaxTime`	The solver stops after it reaches `MaxTime` seconds from the start of the optimization, as measured by `tic` / `toc`. The solver does not interrupt a function evaluation in progress, so the actual compute time can exceed `MaxTime`.	`0`
`ObjectiveLimit`	The solver stops if an objective function value of a feasible point is less than `ObjectiveLimit`.	`1`
`OutputFcn` or `PlotFcn`	An `OutputFcn` or `PlotFcn` can halt the iterations.	`-1`
Bounds `lb` and `ub`	If an entry in `lb` exceeds the corresponding entry in `ub`, the solver stops because the bounds are inconsistent.	`-2`

Command-Line Display

Set the Display option to control what surrogateopt returns to the command line.

'final' — Return only the exit message. This is the default behavior.
'iter' — Return iterative display.
'off' or the equivalent 'none' — No command-line display.

With an iterative display, the solver returns the following information in table format.

F-count — Number of function evaluations
Time(s) — Time in seconds since the solver started
Best Fval — Lowest objective function value obtained
Current Fval — Latest objective function value
Trial Type — Algorithm giving the evaluated point, either random or adaptive. For details, see Surrogate Optimization Algorithm.

When the objective function returns a nonlinear constraint, the iterative display of Best Fval and Current Fval changes. Instead, the titles are Best and Current, and each displays two columns, (Fval, Infeas).

When a point is feasible, surrogateopt displays the function value, and shows - as the infeasibility.
When a point is infeasible, surrogateopt displays the maximum infeasibility among all nonlinear constraint functions (a positive number), and shows - as the function value.
Once surrogateopt finds a feasible point, subsequent entries in the Best column show only the smallest function value found, and show - as the best infeasibility.

With iterative display, the solver also returns problem information before the table:

Number of variables
Type of objective function (scalar or none)
Number of inequalities

Output Function

An output function can halt the solver or perform a computation at each iteration. To include an output function, set the OutputFcn option to @myoutputfcn, where myoutputfcn is a function with the syntax described in the next paragraph. This syntax is the same as for Optimization Toolbox™ output functions, but with different meanings of the x and optimValues arguments. For information about those output functions, see Output Function and Plot Function Syntax. For an example of an output function, see Optimal Component Choice Using surrogateopt.

The syntax of an output function is:

stop = outfun(x,optimValues,state)

surrogateopt passes the values of x, optimValues, and state to the output function (outfun, in this case) at each iteration. The output function returns stop, a Boolean value (true or false) indicating whether to stop surrogateopt.

x — The input argument x is the best point found so far, meaning the point with the lowest objective function value.
optimValues — This input argument is a structure containing the following fields. For more information about these fields, see Surrogate Optimization Algorithm.

optimValues Structure

Field Name	Contents
`constrviolation`	Maximum constraint violation of best point, `max(optimValues.ineq)`
`currentConstrviolation`	Maximum constraint violation of current point, `max(optimValues.currentIneq)`
`currentFlag`	How the current point was created. `'initial'` — Initial point passed in `options.InitialPoints` `'random'` — Random sample within the bounds `'adaptive'` — Result of the solver trying to minimize the surrogate
`currentFval`	Objective function value at the current point
`currentIneq`	Constraint violation vector of current point, `fun(currentX).Ineq`
`currentX`	Current point
`elapsedtime`	Time in seconds since the solver started
`flag`	How the best point was created `'initial'` — Initial point passed in `options.InitialPoints` `'random'` — Random sample within the bounds `'adaptive'` — Result of the solver trying to minimize the surrogate
`funccount`	Total number of objective function evaluations
`fval`	Lowest objective function value encountered
`incumbentConstrviolation`	Maximum constraint violation of current point, `max(optimValues.incumbentIneq)`
`incumbentIneq`	Constraint violation vector of incumbent point, `fun(incumbentX).Ineq`
`incumbentFlag`	How the incumbent point was created `'initial'` — Initial point passed in `options.InitialPoints` `'random'` — Random sample within the bounds `'adaptive'` — Result of the solver trying to minimize the surrogate
`incumbentFval`	Objective function value at the incumbent point
`incumbentX`	Incumbent point, meaning the best point found since the last phase shift to random sampling
`ineq`	Constraint violation vector of best point, `fun(x).Ineq`
`iteration`	Number of iterations completed. Equal to `funccount`, except during the `'iter'` state, when `iteration` is equal to `funccount` – 1. This field allows `surrogateopt` to use the same plot functions as some other solvers
`surrogateReset`	Boolean value indicating that the current iteration resets the model and switches to random sampling
`surrogateResetCount`	Total number of times that `surrogateReset` is `true`

state — This input argument is the state of the algorithm, specified as one of these values.
- 'init' — The algorithm is in the initial state before the first iteration. When the algorithm is in this state, you can set up plot axes or other data structures or open files.
  Note
  When state is 'init', the input arguments x and optimValues.fval are empty ([]) because surrogateopt is designed for time-consuming objective functions, and so does not evaluate the objective function before calling the initialization step.
- 'iter' — The algorithm just evaluated the objective function. You perform most calculations and view most displays when the algorithm is in this state.
- 'done' — The algorithm performed its final objective function evaluation. When the algorithm is in this state, you can close files, finish plots, or prepare in other ways for surrogateopt to stop.

Plot Function

A plot function displays information at each iteration. You can pause or halt the solver by clicking buttons on the plot. To include a plot function, set the PlotFcn option to a function name or function handle or cell array of function names or handles to plot functions. The four built-in plot functions are:

'optimplotfvalconstr' (default) — Plot the best feasible objective function value found as a line plot. If there is no objective function, plot the maximum nonlinear constraint violation as a line plot.
- The plot shows infeasible points in one color and feasible points in another.
- If there is no objective function, the plot title shows the number of feasible solutions.
'optimplotfval' — Shows the best function value. If you do not choose a plot function, surrogateopt uses @optimplotfval.
'optimplotx' — Shows the best point found as a bar plot.
'surrogateoptplot' — Shows the current objective function value, best function value, and information about the algorithm phase. See Interpret surrogateoptplot.

You can write a custom plot function using the syntax of an Output Function. For an example, examine the code for surrogateoptplot by entering type surrogateoptplot at the MATLAB^® command line.

Parallel Computing

When you set the UseParallel option to true, surrogateopt computes in parallel. Computing in parallel requires a Parallel Computing Toolbox™ license. For details, see Surrogate Optimization Algorithm.

You cannot specify both UseParallel = true and UseVectorized = true. If you set both to true, the solver ignores UseVectorized and attempts to compute in parallel using a parallel pool, if possible.

Vectorized Computing

When you set the UseVectorized option to true, surrogateopt passes a matrix to the objective function. Each row of the matrix represents one point to evaluate. The matrix has options.BatchUpdateInterval rows; however, the matrix can have fewer rows during the final iteration. Use this option for custom parallel computing, as shown in Optimize Simulink Model in Parallel.

Checkpoint File

When you set the name of a checkpoint file using the CheckpointFile option, surrogateopt writes data to the file after each iteration (as long as at least 10 seconds have elapsed since the last time it wrote data or this is the last write), which enables the function to resume the optimization from the current state. When restarting, surrogateopt does not evaluate the objective function value at previously evaluated points.

A checkpoint file can be a file path such as "C:\Documents\MATLAB\check1.mat" or a file name such as 'checkpoint1June2019.mat'. If you specify a file name without a path, surrogateopt saves the checkpoint file in the current folder.

You can change only the following options when resuming the optimization:

BatchUpdateInterval
CheckpointFile
Display
MaxFunctionEvaluations
MaxTime
MinSurrogatePoints
ObjectiveLimit
OutputFcn
PlotFcn
UseParallel
UseVectorized

To resume the optimization from a checkpoint file, call surrogateopt with the file name as the first argument.

[x,fval,exitflag,output] = surrogateopt('check1.mat')

To resume the optimization using new options, include the new options as the second argument.

opts = optimoptions(options,'MaxFunctionEvaluations',500);
[x,fval,exitflag,output] = surrogateopt('check1.mat',opts)

During the restart, surrogateopt runs any output functions and plot functions, based on the original function evaluations. So, for example, you can create a different plot based on an optimization that already ran. See Work with Checkpoint Files.

Note

surrogateopt does not save all details of the state in the checkpoint file. Therefore, subsequent iterations can differ from the iterations that the solver takes without stopping at the checkpointed state.

Warning

Do not resume surrogateopt from a checkpoint file created with a different MATLAB version. surrogateopt can throw an error or give inconsistent results.