optim_doc: Common optimization options

Next: Parameter structures, Previous: Common frontend options, Up: Top [Index]

## 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` 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, 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 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`.

Next: Parameter structures, Previous: Common frontend options, Up: Top [Index]