MATLAB: FunctionTolerance parameter has no effect on fmincon – is it a bug

bugfminconMATLABOptimization Toolboxoptimoptions

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?

Best Answer

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.
Related Question