Many solvers allow you to supply a function that calculates first derivatives (gradients or Jacobians) of objective or constraint functions. You can check whether the derivatives calculated by your function match finite-difference approximations. This check can help you diagnose whether your derivative function is correct.

If a component of the gradient function is less than

`1`

, “match” means the absolute difference of the gradient function and the finite-difference approximation of that component is less than`1e-6`

.Otherwise, “match” means that the relative difference is less than

`1e-6`

.

The `CheckGradients`

option causes the solver
to check the supplied derivative against a finite-difference approximation
at just one point. If the finite-difference and supplied derivatives
do not match, the solver errors. If the derivatives match to within `1e-6`

,
the solver reports the calculated differences, and continues iterating
without further derivative checks. Solvers check the match at a point
that is a small random perturbation of the initial point `x0`

,
modified to be within any bounds. Solvers do not include the computations
for `CheckGradients`

in the function count; see Iterations and Function Counts.

At the MATLAB

^{®}command line:Set the

`SpecifyObjectiveGradient`

or`SpecifyConstraintGradient`

options to`true`

using`optimoptions`

. Make sure your objective or constraint functions supply the appropriate derivatives.Set the

`CheckGradients`

option to`true`

.

Using the Optimization app:

In the

**Problem Setup and Results**pane, choose**Derivatives**:**Objective function**:`Gradient supplied`

or**Nonlinear constraint function**:**Derivatives**:`Gradient supplied`

. Make sure your objective or constraint functions supply the appropriate derivatives.In the

**Options**pane, check**User-supplied derivatives > Validate user-supplied derivatives**

Central finite differences are more accurate than the default forward finite differences. To use central finite differences:

At the MATLAB command line, set

`FiniteDifferenceType`

option to`'central'`

using`optimoptions`

.Using the Optimization app, in the

**Approximated derivatives**pane, set**Type**to`central differences`

.

Consider the problem of minimizing the Rosenbrock function within
the unit disk as described in Solve a Constrained Nonlinear Problem, Solver-Based. The `rosenboth`

function
calculates the objective function and its gradient:

function [f g H] = rosenboth(x) f = 100*(x(2) - x(1)^2)^2 + (1-x(1))^2; if nargout > 1 g = [-400*(x(2)-x(1)^2)*x(1)-2*(1-x(1)); 200*(x(2)-x(1)^2)]; if nargout > 2 H = [1200*x(1)^2-400*x(2)+2, -400*x(1); -400*x(1), 200]; end end

`rosenboth`

calculates the Hessian, too, but
this example does not use the Hessian.

The `unitdisk2`

function correctly calculates
the constraint function and its gradient:

function [c,ceq,gc,gceq] = unitdisk2(x) c = x(1)^2 + x(2)^2 - 1; ceq = [ ]; if nargout > 2 gc = [2*x(1);2*x(2)]; gceq = []; end

The `unitdiskb`

function incorrectly calculates
gradient of the constraint function:

function [c ceq gc gceq] = unitdiskb(x) c = x(1)^2 + x(2)^2 - 1; ceq = [ ]; if nargout > 2 gc = [x(1);x(2)]; % Gradient incorrect: off by a factor of 2 gceq = []; end

Set the options to use the interior-point algorithm, gradient of objective and constraint functions, and the

`CheckGradients`

option:% For reproducibility--CheckGradients randomly perturbs the initial point rng(0,'twister'); options = optimoptions(@fmincon,'Algorithm','interior-point',... 'CheckGradients',true,'SpecifyObjectiveGradient',true,'SpecifyConstraintGradient',true);

Solve the minimization with

`fmincon`

using the erroneous`unitdiskb`

constraint function:[x fval exitflag output] = fmincon(@rosenboth,... [-1;2],[],[],[],[],[],[],@unitdiskb,options); ____________________________________________________________ Derivative Check Information Objective function derivatives: Maximum relative difference between user-supplied and finite-difference derivatives = 1.84768e-008. Nonlinear inequality constraint derivatives: Maximum relative difference between user-supplied and finite-difference derivatives = 1. User-supplied constraint derivative element (2,1): 1.99838 Finite-difference constraint derivative element (2,1): 3.99675 ____________________________________________________________ Error using validateFirstDerivatives Derivative Check failed: User-supplied and forward finite-difference derivatives do not match within 1e-006 relative tolerance. Error in fmincon at 805 validateFirstDerivatives(funfcn,confcn,X, ...

The constraint function does not match the calculated gradient, encouraging you to check the function for an error.

Replace the

`unitdiskb`

constraint function with`unitdisk2`

and run the minimization again:[x fval exitflag output] = fmincon(@rosenboth,... [-1;2],[],[],[],[],[],[],@unitdisk2,options); ____________________________________________________________ Derivative Check Information Objective function derivatives: Maximum relative difference between user-supplied and finite-difference derivatives = 1.28553e-008. Nonlinear inequality constraint derivatives: Maximum relative difference between user-supplied and finite-difference derivatives = 1.46443e-008. Derivative Check successfully passed. ____________________________________________________________ Local minimum found that satisfies the constraints...

The Optimization app warns that it will be removed in a future release.

To set up the example using correct derivative functions, but
starting from `[0 0]`

, using the Optimization app:

Launch the Optimization app by entering

`optimtool`

at the command line.Set the

**Problem Setup and Results**pane to match the following figure:Set the

**Options**pane to match the following figure:Press the

**Start**button under**Run solver and view results**.The output screen displays

The forward finite difference approximation is inaccurate enough near

`[0 0]`

that the derivative check fails.To use the more accurate central differences, select

`central differences`

in the**Approximated derivatives > Type**pane:Click

**Run solver and view results > Clear Results**, then**Start**. This time the derivative check is successful:

The derivative check also succeeds when you select the initial
point `[-1 2]`

, or most random points.