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 whenmax(fun(x).Ineq) <= ConstraintTolerance
, and otherwise is violated. The default value is1e3
.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
orub
. The number of rows is arbitrary.surrogateopt
uses all the rows to construct the initial surrogate. If there are fewer thanMinSurrogatePoints
rows, thensurrogateopt
generates the remaining initial points.surrogateopt
evaluates the objective function at each initial point.Structure — The structure contains the field
X
and, optionally, the fieldsFval
andIneq
. TheX
field contains a matrix where each row represents an initial point. TheFval
field contains a vector representing the objective function values at each point inX
. PassingFval
saves time for the solver, because otherwise the solver evaluates the objective function value at each initial point. TheIneq
field contains a matrix containing nonlinear inequality constraint values. Each row ofIneq
represents one initial point, and each column represents a nonlinear constraint function value at that point. PassingIneq
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 ofMinSurrogatePoints
andBatchUpdateInterval
.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, thensurrogateopt
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 thesurrogateoptplot
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
istrue
,surrogateopt
passes a matrix of sizeBatchUpdateInterval
bynvar
, wherenvar
is the number of problem variables. Each row of the matrix represents one evaluation point. For the final iteration (the one that causesMaxFunctionEvaluations
function evaluations), ifMaxFunctionEvaluations
is not an integer multiple ofBatchUpdateInterval
,surrogateopt
passes a matrix with fewer thanBatchUpdateInterval
rows.When
BatchUpdateInterval
> 1, the minimum number of random sample points used to create a surrogate is the larger ofMinSurrogatePoints
andBatchUpdateInterval
.
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
 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 
CommandLine 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 commandline display.
With an iterative display, the solver returns the following information in table format.
Fcount
— Number of function evaluationsTime(s)
— Time in seconds since the solver startedBest Fval
— Lowest objective function value obtainedCurrent Fval
— Latest objective function valueTrial Type
— Algorithm giving the evaluated point, eitherrandom
oradaptive
. 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 theBest
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 argumentx
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.

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

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

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

surrogateReset  Boolean value indicating that the current iteration resets the model and switches to random sampling 
surrogateResetCount  Total number of times that

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 argumentsx
andoptimValues.fval
are empty ([]
) becausesurrogateopt
is designed for timeconsuming 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 forsurrogateopt
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 builtin 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 as red and feasible points as blue.
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 Vectorized Surrogate Optimization for Custom Parallel Simulation.
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.
Checkpoint File
When you set the name of a checkpoint file using the
CheckpointFile
option, surrogateopt
writes data to the file after each iteration, 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.
Note
Checkpointing takes time. This overhead is especially noticeable for functions that otherwise take little time to evaluate.
Warning
Do not resume surrogateopt
from a checkpoint file created with a
different MATLAB version. surrogateopt
can throw an error or give
inconsistent results.