FunctionTolerance parameter has no effect on fmincon - is it a bug?

The FunctionTolerance parameter specified with the optimoptions function has no effect on the fmincon solver. Here is an example:

options = optimoptions(@fmincon, 'FunctionTolerance', 1, 'Display', 'iter');
fmincon(@(x) rastriginsfcn (x), [4, 4], [], [], [], [], [-5.12, -5.12], ...
  [5.12, 5.12], [], options)

The solver produces the following output:

                                            First-order      Norm of
 Iter F-count            f(x)  Feasibility   optimality         step
    0       3    3.200000e+01    0.000e+00    7.947e+00
    1       7    2.972638e+01    0.000e+00    5.588e+01    5.192e+00
    2      12    2.384965e+00    0.000e+00    1.253e+01    1.917e+00
    3      17    2.350732e+00    0.000e+00    1.182e+01    8.742e-02
    4      20    1.989923e+00    0.000e+00    3.434e-02    4.261e-02
    5      23    1.989918e+00    0.000e+00    4.849e-03    1.484e-04
    6      26    1.989918e+00    0.000e+00    4.849e-05    4.239e-06
    7      29    1.989918e+00    0.000e+00    4.848e-07    5.641e-08

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the default value of the optimality tolerance,
and constraints are satisfied to within the default value of the constraint tolerance.

<stopping criteria details>

ans =

     -0.9950   -0.9950

If the FunctionTolerance parameter were considered, then the optimization would stop at the third iteration because the difference between the objective function values was less than 1. However, that did not happen.

Is such behavior a bug?

Answer 1

[John D'Errico]

I'm not sure I've call it a bug.

optimoptions('fmincon','functionTolerance',1)
ans = 
  fmincon options:

     Options used by current Algorithm ('interior-point'):
     (Other available algorithms: 'active-set', 'sqp', 'trust-region-reflective')

     Set properties:
       No options set.

     Default properties:
                      Algorithm: 'interior-point'
                 CheckGradients: 0
            ConstraintTolerance: 1e-06
                        Display: 'final'
       FiniteDifferenceStepSize: 'sqrt(eps)'
           FiniteDifferenceType: 'forward'
           HessianApproximation: 'bfgs'
                     HessianFcn: []
             HessianMultiplyFcn: []
                    HonorBounds: 1
         MaxFunctionEvaluations: 3000
                  MaxIterations: 1000
                 ObjectiveLimit: -1e+20
            OptimalityTolerance: 1e-06
                      OutputFcn: []
                        PlotFcn: []
                   ScaleProblem: 0
      SpecifyConstraintGradient: 0
       SpecifyObjectiveGradient: 0
                  StepTolerance: 1e-10
            SubproblemAlgorithm: 'factorization'
                       TypicalX: 'ones(numberOfVariables,1)'
                    UseParallel: 0

Note that FunctionTolerance is NOT in the list. While you may WANT it to use that parameter, it appears that fmincon will blithely ignore you.

[Gaik Tamazian]

John, thanks for pointing it out. That's very odd: the stopping criteria based on the change of the objective function value is conventional and commonly used in a number of optimization solvers. I see no reason why fmincon ignores it.

[Steve Grikschat]

By the way, if you want fmincon to not ignore you, try setting options.Algorithm to trust-region-reflective.

[Gaik Tamazian]

Steve, thanks. I have already realized that the interior-point algorithm does not support the function value stopping criterion. Alan Weiss described how various algorithms implemented in fmincon treat the criterion in this thread .

Answer 2

[Gaik Tamazian]

I found a post by Alan Weiss who explained that the function value stopping criterion depends on the algorithm used. Indeed, the interior-point algorithm does not support it at all.

Answer 3

[Alan Weiss]

The documentation is certainly lacking on this subject. Sorry about this lacuna. I will correct the documentation in a future release.

Meanwhile, as John showed, the optimoptions function enables you to check which options are used by each solver and each algorithm.

Alan Weiss

MATLAB mathematical toolbox documentation

[Gaik Tamazian]

Thank you, Alan. It will be great to have the updated documentation in a future MATLAB release.