optimset {neldermead}

Configures and returns an optimization data structure.

Description

This function creates or updates a list which can be used to modify the behaviour of optimization methods. The goal of this function is to manage the options list with a set of fields (for example, 'MaxFunEvals', 'MaxIter', etc...). The user can create a new list 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 passes the list to an optimization function so that the algorithm uses the options configured by the user.

Usage

  optimset(method = NULL,...)

Arguments

method

If provided, the method calls the optimset.method function. If the content of method is recognized, a default set of options are returned. The only current recognized character strings are 'fminsearch' and 'fminbnd'.

...

Additional arguments which would be included in the options output if the method argument is not used. See Details.

Details

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. The goal of the optimset function is to simplify the management of input arguments, by gathering all the parameters into a single list.

While the current implementation of the optimset function only supports the fminsearch and fminbnd 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.

Optimization parameters that are returned by the optimset function and that can be defined in ... are the following:

Display

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

'off'

The algorithm displays no message at all.

'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 or iterations of the maximum number of function evaluations is reached and warns the user of a convergence problem.

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

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

FunValCheck

A logical flag to enable the checking of function values.

MaxFunEvals

The maximum number of evaluations of the cost function.

MaxIter

The maximum number of iterations.

OutputFcn

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

PlotFcns

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

TolFun

The absolute tolerance on function value.

TolX

The absolute tolerance on the variable x.

nbMatch

Specific to Box method: the number of consecutive times the TolFun criteria must be met to terminate the optimization.

boundsAlpha

Specific to Box method: the parameter used to project the vertices into the bounds in Box's algorithm

boxScaling

Specific to Box method: the scaling coefficient used to scale the trial point for function improvement or into the constraints of Box's algorithm

alphaMin

Specific to Box method: the minimum value of alpha when scaling the vertices of the simplex into nonlinear constraints in Box's algorithm

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:

myfun <- function(x, optimValues, state)

where the input parameters are:

x

The current point estimate.

optimValues

A list which contains the following fields:

funccount

The number of function evaluations.

fval

The best function value.

iteration

The current iteration number.

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'

when the algorithm is initializing,

'iter'

when the algorithm is performing iterations,

'done'

when the algorithm is terminated.

Value

Return a list with the following fields: Display, FunValCheck, MaxFunEvals, MaxIter, OutputFcn, PlotFcns, TolFun, TolX, nbMatch, boundsAlpha, boxScaling, and alphaMin.

Author(s)

Author of Scilab neldermead module: Michael Baudin (INRIA - Digiteo)

Author of R adaptation: Sebastien Bihorel ([e-mail])

See Also

optimset.method,fminsearch, fminbnd

Examples

  optimset()
  optimset(Display='iter')
  optimset(method='fminbnd')