## Simulated Annealing Options

### Set Simulated Annealing Options at the Command Line

Specify options by creating an `options`

object 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
`options`

. For example, `InitialTemperature`

refers to the corresponding field of `options`

.

### Plot Options

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
built-in plot function name or 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.

#### Structure of the Plot Functions

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 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

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 any options. 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

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:wherenewx = 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:whereacceptpoint = 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`

.

### Hybrid Function Options

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,
`simulannealbnd`

throws an error.

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`

as
follows:options = optimoptions(@simulannealbnd,options,... 'HybridFcn',{@fminunc,hybridopts});

`hybridopts`

must exist before you set `options`

.See Hybrid Scheme in the Genetic Algorithm for an example. See When to Use a Hybrid Function.

### Stopping Criteria Options

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 of a feasible point is less than`ObjectiveLimit`

.

### Output Function Options

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.

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 of function handles:

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.

#### Structure of the Output Function

The output function has the following calling syntax.

[stop,options,optchanged] = myfun(options,optimvalues,flag)

The function has the following input arguments:

`options`

— Options 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 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 as 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.

### Display Options

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`options`

exported from the Optimization app.`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 for options created using`optimoptions`

.

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