optimbase_terminate

Argument

opt

The object of TOPTIM type (tlist).

previousfopt

A vector of doubles, the previous value of the cost function.

currentfopt

A vector of doubles, the current value of the cost function.

previousxopt

A vector of doubles, the previous x optimum.

currentxopt

A vector of doubles, the current x optimum.

terminate

A boolean.

terminate = %t if the algorithm must terminate.

terminate = %f if the algorithm must continue.

status

A string.

If terminate = %t, the detailed status of the termination corresponds to :

"maxiter"

The maximum number of iterations, provided by the -maxiter option, is reached.

"maxfuneval"

The maximum number of function evaluations, provided by the -maxfunevals option, is reached.

"tolf"

The tolerance on the function value is reached. This status is associated with the -tolfunmethod, -tolfunabsolute and -tolfunrelative options.

"tolx"

The tolerance on x is reached. This status is associated with the -tolxmethod, -tolxabsolute and -tolxrelative options.

Description

The optimbase_terminate function returns a boolean:

• %t if the algorithm is terminated,

• %f if the algorithm must continue.

If the -verbosetermination option is enabled, messages are printed detailing the termination intermediate steps.

The optimbase_terminate function uses a set of rules to compute if the termination occurs, which leads to an optimization status which is equal to one of the following: "continue", "maxiter", "maxfunevals", "tolf", "tolx". The set of rules is the following.

• By default, the status is "continue", and the terminate flag is %f.

• The number of iterations is examined and compared to the -maxiter option. If the following condition

  iterations >= maxiter

  is true, then the status is set to "maxiter" and terminate is set to %t.

• The number of function evaluations and compared to the -maxfunevals option is examined. I the following condition

  funevals >= maxfunevals

  is true, then the status is set to "maxfunevals" and terminate is set to %t.

• The tolerance on function value is examined depending on the value of the -tolfunmethod option.

  "disabled"

  then the tolerance on f is just skipped.

  "enabled"

  if the following condition

  abs(currentfopt) < tolfunrelative * abs(previousfopt) + tolfunabsolute

  is true, then the status is set to "tolf" and terminate is set to %t.

  The relative termination criteria on the function value works well if the function value at optimum is near zero. In that case, the function value at initial guess fx0 may be used as previousfopt.

  The absolute termination criteria on the function value works if the user has an accurate idea of the optimum function value.

• The tolerance on x is examined depending on the value of the -tolxmethod option.

  %f

  then the tolerance on x is just skipped.

  %t

  if the following condition

  norm(currentxopt - previousxopt) < tolxrelative * norm(currentxopt) + tolxabsolute

  is true, then the status is set to "tolx" and terminate is set to %t.

  The relative termination criteria on x works well if x at optimum is different form zero. In that case, the condition measures the distance between two iterates.

  The absolute termination criteria on x works if the user has an accurate idea of the scale of the optimum x. If the optimum x is nea 0, the relative tolerance will not work and the absolute tolerance is more appropriate.

Example

In the following example, ones searches to solve f(x) = 0 thanks dichotomy method. An optimization object is created and configured (number of variables, initial point, maximum number of iterations, ...). The -verbose option is enabled so that messages are generated during the algorithm, are printed.

function [f, index]=fun(x, index)
    f = 2*x - 4;
endfunction

a = -5;
b = 5;
x0 = (a+b)/2;

// Creation of the object
opt = optimbase_new();

// Configures the object
opt = optimbase_configure(opt,"-numberofvariables",2);
opt = optimbase_configure(opt, "-x0", x0);
opt = optimbase_configure(opt, "-tolxrelative", 10*%eps);
opt = optimbase_configure(opt, "-maxiter", 30);
opt = optimbase_configure(opt, "-function", fun);
opt = optimbase_configure(opt,"-verbose",1);

function x=Dicho(opt, a, b)
    xk = optimbase_cget(opt, "-x0");
    [opt, fx0, index] = optimbase_function (opt , xk , 1);
    opt = optimbase_set ( opt , "-xopt" , xk );
    opt = optimbase_set ( opt , "-fopt" , fx0 );
    terminate = %f;
    while ~terminate
        [opt, f, index] = optimbase_function(opt, xk, 1);
        [opt, g, index] = optimbase_function(opt, a, 1);
        if g*f <= 0 then
            b = xk;
        else
            a = xk;
        end
        x = (a + b)/2;
        opt = optimbase_incriter(opt);
        [opt, terminate, status] = optimbase_terminate(opt, optimbase_get(opt, "-fopt"), f, xk, x);
        opt = optimbase_set ( opt , "-xopt" , x );
        opt = optimbase_set ( opt , "-fopt" , f );
        xk = x;
    end
endfunction

x = Dicho(opt,a,b)

See also

• optimbase_function — Calls cost function.