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.
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.
For details, see Surrogate Optimization Algorithm.
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 it obtains an objective function value 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 |
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
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 Integer Optimization with Custom Output Function.
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.
|
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 | Same as |
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 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.
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 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.
If 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.
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:
CheckpointFile
Display
MaxFunctionEvaluations
MaxTime
MinSurrogatePoints
ObjectiveLimit
OutputFcn
PlotFcn
UseParallel
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.