optim_doc: nonlin_residmin

Next: nonlin_curvefit, Up: Residual optimization [Index]

### 2.1 Frontend nonlin_residmin for non-linear residual minimization

Function File: [p, resid, cvg, outp] = nonlin_residmin (f, pin)
Function File: [p, resid, cvg, outp] = nonlin_residmin (f, pin, settings)

  Frontend for nonlinear minimization of residuals returned by a model function.

  The functions supplied by the user have a minimal interface; any additionally needed constants (e.g. observed values) can be supplied by wrapping the user functions into anonymous functions.

  The following description applies to usage with vector-based parameter handling. Differences in usage for structure-based parameter handling will be explained separately.

  f: function returning the array of residuals. It gets a column vector of real parameters as argument. In gradient determination, this function may be called with an informational second argument, whose content depends on the function for gradient determination.

  pin: real column vector of initial parameters.

  settings: structure whose fields stand for optional settings referred to below. The fields can be set by `optimset()`.

  The returned values are the column vector of final parameters p, the final array of residuals resid, an integer cvg indicating if and how optimization succeeded or failed, and a structure outp with additional information, curently with the fields: `niter`, the number of iterations and `user_interaction`, information on user stops (see settings). The backend may define additional fields. If the backend supports it, outp has a field `lambda` with determined Lagrange multipliers of any constraints, seperated into subfields `lower` and `upper` for bounds, `eqlin` and `ineqlin` for linear equality and inequality constraints (except bounds), respectively, and `eqnonlin` and `ineqnonlin` for general equality and inequality constraints, respectively. cvg is greater than zero for success and less than or equal to zero for failure; its possible values depend on the used backend and currently can be `0` (maximum number of iterations exceeded), `2` (parameter change less than specified precision in two consecutive iterations), or `3` (improvement in objective function – e.g. sum of squares – less than specified), or `-1` (algorithm aborted by a user function).

  See also: nonlin_curvefit.

#### Settings

The fields of the settings structure can be set with (octave)optimset.

For settings common to all frontends (including these for statistics) see Common frontend options.

For additional settings common to all optimization frontends see Common optimization options.

#### Specific defaults:

`Algorithm`: | "lm_svd_feasible"

#### Additional settings:

`weights`

  Array of weights for the residuals. Dimensions must match.

`dfdp`

  Function computing the Jacobian of the residuals with respect to the parameters, assuming residuals are reshaped to a column vector. Default: real finite differences. Will be called with the column vector of parameters and an informational structure as arguments. If `dfdp` was specified by the user, the informational structure has the fields `f`: value of residuals for current parameters, reshaped to a column vector, `fixed`: logical vector indicating which parameters are not optimized, so these partial derivatives need not be computed and can be set to zero, `diffp`, `diff_onesided`, `lbound`, `ubound`: identical to the user settings of this name, `plabels`: 1-dimensional cell-array of column-cell-arrays, each column with labels for all parameters; the first column contains the numerical indices of the parameters; the second and third columns, present for structure based parameter handling, see Parameter structures, contain the names of the parameters and the subindices of the parameters, see Non-scalar parameters, respectively. The default jacobian function will call the model function with the second argument set with fields `f`: as the `f` passed to the jacobian function, `plabels`: cell-array of 1x1 cell-arrays with the entries of the column-cell-arrays of `plabels` as passed to the jacobian function corresponding to current parameter, `side`: `0` for one-sided interval, `1` or `2`, respectively, for the sides of a two-sided interval, and `parallel`: logical scalar indicating parallel computation of partial derivatives. This information can be useful if the model function can omit some computations depending on the currently computed partial derivative.

`complex_step_derivative_f`

  Logical scalar, default: `false`. Estimate Jacobian of model function with complex step derivative approximation. Use only if you know that your model function is suitable for this. No user function for the Jacobian (`dfdp`) must be specified.

`plot_cmd`

  Function enabling backend to plot results or intermediate results. Will be called with current computed residuals. Default: plot nothing. This setting is deprecated and will disappear. Please use `user_interaction` instead ( see Common optimization options).

#### Structure based parameter handling

Please see Parameter structures.

#### Backend information

Please see Residual optimization and choose backend from menu under ‘Optimization backends’.

Next: nonlin_curvefit, Up: Residual optimization [Index]