# optimbase_terminate

Checks if the algorithm is terminated.

## Calling Sequence

                [opt, terminate, status] = optimbase_terminate(opt, previousfopt, currentfopt, previousxopt, currentxopt)

## 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 algorithme 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 &gt;= 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 &gt;= 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) &lg; 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` otpion.

  %f

    then the tolerance on x is just skipped.

  %t

    if the following condition

                           norm(currentxopt - previousxopt) &lg; 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