Function File: [p, objf, cvg, outp] = nonlin_min (f, pin)

Function File: [p, objf, cvg, outp] = nonlin_min (f, pin, settings)

Frontend for nonlinear minimization of a scalar objective function.

The functions supplied by the user have a minimal interface; any additionally needed constants 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: objective function. It gets a column vector of real parameters as argument. In gradient determination, this function may be called with an informational second argument (if the function accepts it), 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 value of the objective function objf, an integer cvg indicating if and how optimization succeeded or failed, and a structure outp with additional information, curently with possible fields: niter, the number of iterations, nobjf, the number of objective function calls (indirect calls by gradient function not counted), lambda, the lambda of constraints at the result, and user_interaction, information on user stops (see settings). The backend may define additional fields. 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), 1 (success without further specification of criteria), 2 (parameter change less than specified precision in two consecutive iterations), 3 (improvement in objective function less than specified), -1 (algorithm aborted by a user function), or -4 (algorithm got stuck).

For settings, type optim_doc ("nonlin_min").

For desription of structure-based parameter handling, type optim_doc ("parameter structures").

For description of individual backends, type optim_doc ("scalar optimization") and choose the backend in the menu.

Demonstration 1

 ## Example for default optimization (Levenberg/Marquardt with
 ## BFGS), one non-linear equality constraint. Constrained optimum is
 ## at p = [0; 1].
 objective_function = @ (p) p(1)^2 + p(2)^2;
 pin = [-2; 5];
 constraint_function = @ (p) p(1)^2 + 1 - p(2);
 [p, objf, cvg, outp] = nonlin_min (objective_function, pin, optimset ("equc", {constraint_function}))

p =

  -1.0909e-08
   1.0000e+00

objf = 1.0000
cvg = 3
outp =

  scalar structure containing the fields:

    user_interaction =

      scalar structure containing the fields:

        stop = [](0x1)
        info = {}(0x1)

    niter = 7
    nobjf = 12

Demonstration 2

The following code

 ## Example for simulated annealing, two parameters, "trace_steps"
 ## is true;
 t_init = .2;
 t_min = .002;
 mu_t = 1.002;
 iters_fixed_t = 10;
 init_p = [2; 2];
 max_rand_step = [.2; .2];
 [p, objf, cvg, outp] = nonlin_min (@ (p) (p(1)/10)^2 + (p(2)/10)^2 + .1 * (-cos(4*p(1)) - cos(4*p(2))), init_p, optimset ("algorithm", "siman", "max_rand_step", max_rand_step, "t_init", t_init, "T_min", t_min, "mu_t", mu_t, "iters_fixed_T", iters_fixed_t, "trace_steps", true));
 p
 objf
 x = (outp.trace(:, 1) - 1) * iters_fixed_t + outp.trace(:, 2);
 x(1) = 0;
 plot (x, cat (2, outp.trace(:, 3:end), t_init ./ (mu_t .^ outp.trace(:, 1))))
 legend ({"objective function value", "p(1)", "p(2)", "Temperature"})
 xlabel ("subiteration")

Produces the following output

p =

  -1.5542e+00
  -8.8629e-03

objf = -0.1756

and the following figure

Figure 1

Package: optim