Specify options by creating an options
structure
using the optimoptions
function as follows:
options = optimoptions(@simulannealbnd,'Param1',value1,'Param2',value2, ...);
Each option in this section is listed by its field name in the options
structure.
For example, InitialTemperature
refers to the corresponding
field of the options
structure.
Plot options enable you to plot data from the simulated annealing solver while it is running.
PlotInterval
specifies the number of iterations
between consecutive calls to the plot function.
To display a plot when calling simulannealbnd
from
the command line, set the PlotFcn
field of options
to
be a function handle to the plot function. You can specify any of
the following plots:
@saplotbestf
plots the best objective
function value.
@saplotbestx
plots the current
best point.
@saplotf
plots the current function
value.
@saplotx
plots the current point.
@saplotstopping
plots stopping
criteria levels.
@saplottemperature
plots the temperature
at each iteration.
@myfun
plots a custom plot function,
where myfun
is the name of your function. See Structure of the Plot Functions for a description
of the syntax.
For example, to display the best objective plot, set options
as
follows
options = optimoptions(@simulannealbnd,'PlotFcn',@saplotbestf);
To display multiple plots, use the cell array syntax
options = optimoptions(@simulannealbnd,'PlotFcn',{@plotfun1,@plotfun2, ...});
where @plotfun1
, @plotfun2
,
and so on are function handles to the plot functions.
If you specify more than one plot function, all plots appear as subplots in the same window. Right-click any subplot to obtain a larger version in a separate figure window.
The first line of a plot function has the form
function stop = plotfun(options,optimvalues,flag)
The input arguments to the function are
options
— Options structure
created using optimoptions
.
optimvalues
—
Structure containing information about the current state of the solver.
The structure contains the following fields:
x
— Current point
fval
— Objective function
value at x
bestx
— Best point found
so far
bestfval
— Objective function
value at best point
temperature
— Current temperature
iteration
— Current iteration
funccount
— Number of function
evaluations
t0
— Start time for algorithm
k
— Annealing parameter
flag
— Current state in
which the plot function is called. The possible values for flag
are
'init'
— Initialization
state
'iter'
— Iteration state
'done'
— Final state
The output argument stop
provides a way to
stop the algorithm at the current iteration. stop
can
have the following values:
false
— The algorithm continues
to the next iteration.
true
— The algorithm terminates
at the current iteration.
Temperature options specify how the temperature will be lowered at each iteration over the course of the algorithm.
InitialTemperature
— Initial
temperature at the start of the algorithm. The default is 100
.
The initial temperature can be a vector with the same length as x
,
the vector of unknowns. simulannealbnd
expands
a scalar initial temperature into a vector.
TemperatureFcn
— Function
used to update the temperature schedule. Let k denote
the annealing parameter. (The annealing parameter is the same as the
iteration number until reannealing.) The options are:
@temperatureexp
— The temperature
is equal to InitialTemperature * 0.95^k.
This is the default.
@temperaturefast
— The temperature
is equal to InitialTemperature / k.
@temperatureboltz
— The
temperature is equal to InitialTemperature / ln(k).
@myfun
—
Uses a custom function, myfun
, to update temperature.
The syntax is:
temperature = myfun(optimValues,options)
where optimValues
is a structure described
in Structure of the Plot Functions. options
is
either created with optimoptions
, or consists
of default options, if you did not create an options structure. Both
the annealing parameter optimValues.k
and the temperature optimValues.temperature
are
vectors with length equal to the number of elements of the current
point x
. For example, the function temperaturefast
is:
temperature = options.InitialTemperature./optimValues.k;
Algorithm settings define algorithmic specific parameters used in generating new points at each iteration.
Parameters that can be specified for simulannealbnd
are:
DataType
— Type of data
to use in the objective function. Choices:
'double'
(default) — A vector
of type double
.
'custom'
— Any other data
type. You must provide a 'custom'
annealing function.
You cannot use a hybrid function.
AnnealingFcn
— Function
used to generate new points for the next iteration. The choices are:
@annealingfast
— The step
has length temperature, with direction uniformly at random. This is
the default.
@annealingboltz
— The step
has length square root of temperature, with direction uniformly at
random.
@myfun
—
Uses a custom annealing algorithm, myfun
. The syntax
is:
newx = myfun(optimValues,problem)
optimValues
is
a structure described in Structure of the Output Function, and problem
is
a structure containing the following information:objective
: function handle to the
objective function
x0
: the start point
nvar
: number of decision variables
lb
: lower bound on decision variables
ub
: upper bound on decision variables
For example, the current position is optimValues.x
,
and the current objective function value is problem.objective(optimValues.x)
.
You can write a custom objective function by modifying the saannealingfcntemplate.m
file.
To keep all iterates within bounds, have your custom annealing function
call sahonorbounds
as the final command.
ReannealInterval
— Number
of points accepted before reannealing. The default value is 100
.
AcceptanceFcn
— Function
used to determine whether a new point is accepted or not. The choices
are:
@acceptancesa
— Simulated
annealing acceptance function, the default. If the new objective function
value is less than the old, the new point is always accepted. Otherwise,
the new point is accepted at random with a probability depending on
the difference in objective function values and on the current temperature.
The acceptance probability is
$$\frac{1}{1+\mathrm{exp}\left(\frac{\Delta}{\mathrm{max}(T)}\right)}\text{\hspace{0.17em}},$$
where Δ = new objective – old objective, and T is the current temperature. Since both Δ and T are positive, the probability of acceptance is between 0 and 1/2. Smaller temperature leads to smaller acceptance probability. Also, larger Δ leads to smaller acceptance probability.
@myfun
—
A custom acceptance function, myfun
. The syntax
is:
acceptpoint = myfun(optimValues,newx,newfval);
optimValues
is
a structure described in Structure of the Output Function, newx
is
the point being evaluated for acceptance, and newfval
is
the objective function at newx
. acceptpoint
is
a Boolean, with value true
to accept newx
,
and false
to reject newx
.A hybrid function is another minimization function that runs
during or at the end of iterations of the solver. HybridInterval
specifies
the interval (if not never
or end
)
at which the hybrid function is called. You can specify a hybrid function
using the HybridFcn
option. The choices are:
[]
— No hybrid function.
@fminsearch
— Uses the MATLAB^{®} function fminsearch
to perform unconstrained minimization.
@patternsearch
— Uses patternsearch
to perform constrained or unconstrained
minimization.
@fminunc
— Uses the Optimization Toolbox™ function fminunc
to perform unconstrained minimization.
@fmincon
— Uses the Optimization Toolbox function fmincon
to perform constrained minimization.
Note:
Ensure that your hybrid function accepts your problem constraints.
Otherwise, |
You can set separate options for the hybrid function. Use optimset
for fminsearch
,
or optimoptions
for fmincon
, patternsearch
,
or fminunc
. For example:
hybridopts = optimoptions('fminunc','Display','iter','Algorithm','quasi-newton');
simulannealbnd
options
structure
as follows:options = optimoptions(@simulannealbnd,options,'HybridFcn',{@fminunc,hybridopts});
hybridopts
must
exist before you set options
.See Include a Hybrid Function for an example.
Stopping criteria determine what causes the algorithm to terminate. You can specify the following options:
FunctionTolerance
— The
algorithm runs until the average change in value of the objective
function in StallIterLim
iterations is less than FunctionTolerance
.
The default value is 1e-6
.
MaxIterations
— The algorithm
stops if the number of iterations exceeds this maximum number of iterations.
You can specify the maximum number of iterations as a positive integer
or Inf
. Inf
is the default.
MaxFunctionEvaluations
specifies
the maximum number of evaluations of the objective function. The algorithm
stops if the number of function evaluations exceeds the maximum number
of function evaluations. The allowed maximum is 3000*numberofvariables
.
MaxTime
specifies the maximum time
in seconds the algorithm runs before stopping.
ObjectiveLimit
— The algorithm
stops if the best objective function value is less than or equal to
the value of ObjectiveLimit
.
Output functions are functions that the algorithm calls at each
iteration. The default value is to have no output function, []
.
You must first create an output function using the syntax described
in Structure of the Output Function.
Using the Optimization app:
Specify Output function as @myfun
,
where myfun
is the name of your function.
To pass extra parameters in the output function, use Anonymous Functions (Optimization Toolbox).
For multiple output functions, enter a cell array
of output function handles: {@myfun1,@myfun2,...}
.
At the command line:
options = optimoptions(@simulannealbnd,'OutputFcn',@myfun);
For multiple output functions, enter a cell array:
options = optimoptions(@simulannealbnd,'OutputFcn',{@myfun1,@myfun2,...});
To see a template that you can use to write your own output functions, enter
edit saoutputfcntemplate
at the MATLAB command line.
The output function has the following calling syntax.
[stop,options,optchanged] = myfun(options,optimvalues,flag)
The function has the following input arguments:
options
— Options structure
created using optimoptions
.
optimvalues
— Structure
containing information about the current state of the solver. The
structure contains the following fields:
x
— Current point
fval
— Objective function
value at x
bestx
— Best point found
so far
bestfval
— Objective function
value at best point
temperature
— Current temperature,
a vector the same length as x
iteration
— Current iteration
funccount
— Number of function
evaluations
t0
— Start time for algorithm
k
— Annealing parameter,
a vector the same length as x
flag
— Current state in
which the output function is called. The possible values for flag
are
'init'
— Initialization
state
'iter'
— Iteration state
'done'
— Final state
Passing Extra Parameters (Optimization Toolbox) explains how to provide additional parameters to the output function.
The output function returns the following arguments:
stop
— Provides a way to
stop the algorithm at the current iteration. stop
can
have the following values:
false
— The algorithm continues
to the next iteration.
true
— The algorithm terminates
at the current iteration.
options
— Options structure
modified by the output function.
optchanged
— A boolean flag
indicating changes were made to options
. This must
be set to true
if options are changed.
Use the Display
option to specify how much
information is displayed at the command line while the algorithm is
running. The available options are
off
— No output is displayed.
This is the default value for an options structure created using optimoptions
.
iter
— Information is displayed
at each iteration.
diagnose
— Information is
displayed at each iteration. In addition, the diagnostic lists some
problem information and the options that have been changed from the
defaults.
final
— The reason for stopping
is displayed. This is the default.
Both iter
and diagnose
display
the following information:
Iteration
— Iteration number
f-count
— Cumulative number
of objective function evaluations
Best f(x)
— Best objective
function value
Current f(x)
— Current objective
function value
Mean Temperature
— Mean
temperature function value