optimset — Configures and returns an optimization data structure.
options = optimset ()
options = optimset ( funname )
options = optimset ( key , value )
options = optimset ( key1 , value1 , key2 , value2, ... )
options = optimset ( oldoptions , key , value )
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 calling sequence
options = optimset ()
creates a new data structure where the fields have been set to the empty matrix (i.e. []).
The following calling sequence
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 calling sequence
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".
a string. The following keys are available :
"Display"
"FunValCheck"
"MaxFunEvals"
"MaxIter"
"OutputFcn"
"PlotFcns"
the value of the parameter
A struct which contains the following fields. By default, all fields are empty. Specific settings are associated with a particular function name.
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.
A boolean to enable the checking of function values.
The maximum number of evaluations of the cost function.
The maximum number of iterations.
A function which is called at each iteration to print out intermediate state of the optimization algorithm (for example into a log file).
A function which is called at each iteration to plot the intermediate state of the optimization algorithm (for example into a 2D graphic).
The absolute tolerance on function value.
The absolute tolerance on the variable x.
A string containing the name of an optimization function which takes the options structure as input argument. Currently, the only possible value is "fminsearch".
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 developper 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.
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.
In the following example, we create an optimization structure with all fields set to specific settings.
op = optimset ("Display","iter",...
"FunValCheck","on",...
"MaxFunEvals",100,...
"MaxIter",110,...
"OutputFcn",myoutputfun,...
"PlotFcns",myplotfun,...
"TolFun",1.e-12,...
"TolX",1.e-13)