optimset

Description

This function creates or updates a data structure which can be used on modify the behaviour of optimization methods. The goal of this function is to manage the "options" data structure, which is a struct with a set of fields (for example, "MaxFunEvals", "MaxIter", etc...). The user can create a new structure with empty fields or create a new structure with default fields which correspond to a particular algorithm. The user can also configure each field and set it to a particular value. Finally, the user pass the structure to an optimization function so that the algorithm uses the options configured by the user.

In the following, we analyse the various ways to call the optimset function.

The following syntax

options = optimset ()

creates a new data structure where the fields have been set to the empty matrix (i.e. []).

The following syntax

options = optimset ( funname )

creates a new data structure where the default parameters which correspond to the "funname" function have been set. For example,

options = optimset ( "fminsearch" )

returns a new data structure where the default parameters which correspond to the "fminsearch" function have been set.

The following syntax

options = optimset ( oldoptions , key , value )

creates a new data structure where all fields from the "oldoptions" structure have been copied, except the field corresponding to the "key", which has been set to "value".

Arguments

key

a string. The following keys are available :

• "Display"

• "FunValCheck"

• "MaxFunEvals"

• "MaxIter"

• "OutputFcn"

• "PlotFcns"

value

the value of the parameter

options

A struct which contains the following fields. By default, all fields are empty. Specific settings are associated with a particular function name.

options.Display

The verbose level. The default value is "notify". The following is a list of available verbose levels.

• options.Display = "off": the algorithm displays no message at all.

• options.Display = "notify": the algorithm displays message if the termination criteria is not reached at the end of the optimization. This may happen if the maximum number of iterations of the maximum number of function evaluations is reached and warns the user of a convergence problem.

• options.Display = "final": the algorithm displays a message at the end of the optimization, showing the number of iterations, the number of function evaluations and the status of the optimization. This option includes the messages generated by the "notify" option i.e. warns in case of a convergence problem.

• options.Display = "iter": the algorithm displays a one-line message at each iteration. This option includes the messages generated by the "notify" option i.e. warns in case of a convergence problem. It also includes the message generated by the "final" option.

options.FunValCheck

A boolean to enable the checking of function values.

options.MaxFunEvals

The maximum number of evaluations of the cost function.

options.MaxIter

The maximum number of iterations.

options.OutputFcn

A function which is called at each iteration to print out intermediate state of the optimization algorithm (for example into a log file).

options.PlotFcns

A function which is called at each iteration to plot the intermediate state of the optimization algorithm (for example into a 2D graphic).

options.TolFun

The absolute tolerance on function value.

options.TolX

The absolute tolerance on the variable x.

funname

A string containing the name of an optimization function which takes the options structure as input argument. Currently, the only possible value is "fminsearch".

Design

Most optimization algorithms require many algorithmic parameters such as the number of iterations or the number of function evaluations. If these parameters are given to the optimization function as input parameters, this forces both the user and the developer to manage many input parameters. For example, the "optim" function provides more than 20 input arguments. The goal of the optimset function is to simplify the management of input arguments, by gathering all the parameters into a single data structure.

While the current implementation of the "optimset" function only supports the fminsearch function, it is designed to be extended to as many optimization function as required. Because all optimization algorithms do not require the same parameters, the data structure aims at remaining flexible. But, most of the time, most parameters are the same from algorithm to algorithm, for example, the tolerance parameters which drive the termination criteria are often the same, even if the termination criteria itself is not the same.

Output and plot functions

The "OutputFcn" and "PlotFcns" options accept as argument a function (or a list of functions). In the client optimization algorithm, this output or plot function is called back once per iteration. It can be used by the user to display a message in the console, write into a file, etc...

The output or plot function is expected to have the following definition:

function myfun(x, optimValues, state)

where the input parameters are:

• x: the current point

• optimValues: a struct which contains the following fields

  • optimValues.funccount: the number of function evaluations

  • optimValues.fval: the best function value

  • optimValues.iteration: the current iteration number

  • optimValues.procedure: the type of step performed. This string depends on the specific algorithm see fminsearch for details.

• state: the state of the algorithm. The following states are available : "init", "iter" and "done".

  • "init", when the algorithm is initializing,

  • "iter", when the algorithm is performing iterations,

  • "done", when the algorithm is terminated.

Example #1

In the following example, we create an empty optimization structure.

op = optimset ()

Example #2

In the following example, we create an optimization structure with all fields set to specific settings.

function y=myoutputfun(x)
  y = x;
endfunction
function y=myplotfun(x)
  y = x;
endfunction
op = optimset ("Display","iter",...
               "FunValCheck","on",...
               "MaxFunEvals",100,...
               "MaxIter",110,...
               "OutputFcn",myoutputfun,...
               "PlotFcns",myplotfun,...
               "TolFun",1.e-12,...
               "TolX",1.e-13)

Example #3

In the following example, we create an optimization structure with all fields set to the default settings for the "fminsearch" optimization function.

op = optimset ("fminsearch")

See also

• optimget — Queries an optimization data structure.