Common optimization options (optim

9 Options common to all optimization frontends

All frontends for optimization (nonlin_min, nonlin_residmin, nonlin_curvefit) accept the following options, settable with (octave)optimset.

Settings handled within the frontend

Algorithm: String specifying the backend.
complex_step_derivative_inequc,
complex_step_derivative_equc: Logical scalars, default: false. Estimate Jacobian of general inequality constraints and equality constraints, respectively, with complex step derivative approximation. Use only if you know that your function of general inequality constraints or function of general equality constraints, respectively, is suitable for this. No user function for the respective Jacobian must be specified.

Settings passed to the backend

Which of these options are actually honored is noted in the descriptions of the individual backends.

lbound,

ubound

Column vectors of lower and upper bounds for parameters. Default: -Inf and +Inf, respectively. The bounds are non-strict, i.e. parameters are allowed to be exactly equal to a bound. The default function for gradients or Jacobians will respect bounds (but no further inequality constraints) in finite differencing if the backend respects bounds even during the course of optimization.

inequc

Further inequality constraints. Cell-array containing up to four entries, two entries for linear inequality constraints and/or one or two entries for general inequality constraints. Either linear or general constraints may be the first entries, but the two entries for linear constraints must be adjacent and, if two entries are given for general constraints, they also must be adjacent. The two entries for linear constraints are a matrix (say m) and a vector (say v), specifying linear inequality constraints of the form m.' * parameters + v >= 0. The first entry for general constraints must be a differentiable column-vector valued function (say h), specifying general inequality constraints of the form h (p[, idx]) >= 0; p is the column vector of optimized paraters and the optional argument idx, given only if the function accepts it, is a logical index. h has to return the values of all constraints if idx is not given. It may choose to return only the indexed constraints if idx is given (so computation of the other constraints can be spared); in this case, the additional setting f_inequc_idx has to be set to true. In gradient determination, this function may be called with an informational third argument (only if the function accepts it), whose content depends on the function for gradient determination. If a second entry for general inequality constraints is given, it must be a function computing the jacobian of the constraints with respect to the parameters. For this function, the description of the setting dfdp, see dfdp, applies, with 2 exceptions: 1) it is called with 3 arguments (but with the 2nd and 3rd argument only if it accepts them) since it has an additional argument idx, a logical index, at second position, indicating which rows of the jacobian must be returned (if the function chooses to return only indexed rows, the additional setting df_inequc_idx has to be set to true). 2) the default jacobian function calls h with 3 arguments, since the argument idx is also supplied. Note that specifying linear constraints as general constraints will generally waste performance, even if further, non-linear, general constraints are also specified.

f_inequc_idx,

df_inequc_idx

Indicate that functions for general inequality constraints or their jacobian, respectively, return only the values or derivatives for the indexed parameters. See description of setting inequc above.

equc

Equality constraints. Specified the same way as inequality constraints (see inequc above).

f_equc_idx,

df_equc_idx

As f_inequc_idx and df_inequc_idx above, but for equality constraints.

cpiv

Function for complementary pivoting, usable in algorithms for constraints. Default: cpiv_bard. Only the default function is supplied with the package.

TolFun

Minimum fractional improvement in objective function (e.g. sum of squares) in an iteration (termination criterium). Default: .0001.

TolX

Minimum fractional change in a norm of the parameters in an iteration (termination criterium). Default: backend specific.

MaxIter

Maximum number of iterations (termination criterium). Default: backend-specific.

fract_prec

Column Vector, minimum fractional changes of corresponding parameters in an iteration (termination criterium if violated in two consecutive iterations). Default: backend-specific.

max_fract_change

Column Vector, enforced maximum fractional changes in corresponding parameters in an iteration. Default: backend-specific.

Display

String indicating the degree of verbosity. Default: "off". Possible values are currently "off" (no messages) and "iter" (some messages after each iteration). Support of this setting and its exact interpretation are backend-specific.

debug

Logical scalar, default: false. Will be passed to the backend, which might print debugging information if true.

FunValCheck

If "on", the output of user functions will be sanity-checked. Default: "off".

user_interaction

Handle to a user function or cell-array with a number of these. Functions must have this interface:

[stop, info] = some_user_function (p, vals,
                                               state);

If stop is true, the algorithm stops. In info information about the reason for stopping can be returned in a free format. info can be set to be empty, but it must be set. Note that this is different from the otherwise similar Matlab setting OutputFcn. The functions will be called by the algorithms at the start with state set to init, after each iteration with state set to iter, and at the end with state set to done. p contains the current parameters, and vals is a structure with other current values, the possible fields are currently:

iteration: number of the current iteration,
fval: value of objective function (for scalar optimization),
residual: residuals (for residual-based optimization),
model_y: in nonlin_curvefit, the output of the model function,
observations: in nonlin_curvefit, the constant observations,
model_x: in nonlin_curvefit, the constant argument x.

Information about the output of these functions when they were called the last time (possibly causing a stop) will be contained in the output outp of the frontend in field user_interaction. Subfield stop is a vector containing the stop outputs of each function, subfield info is a cell-array containing the output info of each function. In the case of a stop, the output cvg of the frontent will be -1.