Main Content


Evaluate deep learning model for custom training loops


Use dlfeval to evaluate custom deep learning models for custom training loops.


For most deep learning tasks, you can use a pretrained network and adapt it to your own data. For an example showing how to use transfer learning to retrain a convolutional neural network to classify a new set of images, see Train Deep Learning Network to Classify New Images. Alternatively, you can create and train networks from scratch using layerGraph objects with the trainNetwork and trainingOptions functions.

If the trainingOptions function does not provide the training options that you need for your task, then you can create a custom training loop using automatic differentiation. To learn more, see Define Deep Learning Network for Custom Training Loops.


[y1,...,yk] = dlfeval(fun,x1,...,xn) evaluates the deep learning array function fun at the input arguments x1,...,xn. Functions passed to dlfeval can contain calls to dlgradient, which compute gradients from the inputs x1,...,xn by using automatic differentiation.


collapse all

Rosenbrock's function is a standard test function for optimization. The rosenbrock.m helper function computes the function value and uses automatic differentiation to compute its gradient.

type rosenbrock.m
function [y,dydx] = rosenbrock(x)

y = 100*(x(2) - x(1).^2).^2 + (1 - x(1)).^2;
dydx = dlgradient(y,x);


To evaluate Rosenbrock's function and its gradient at the point [–1,2], create a dlarray of the point and then call dlfeval on the function handle @rosenbrock.

x0 = dlarray([-1,2]);
[fval,gradval] = dlfeval(@rosenbrock,x0)
fval = 
  1x1 dlarray


gradval = 
  1x2 dlarray

   396   200

Alternatively, define Rosenbrock's function as a function of two inputs, x1 and x2.

type rosenbrock2.m
function [y,dydx1,dydx2] = rosenbrock2(x1,x2)

y = 100*(x2 - x1.^2).^2 + (1 - x1).^2;
[dydx1,dydx2] = dlgradient(y,x1,x2);


Call dlfeval to evaluate rosenbrock2 on two dlarray arguments representing the inputs –1 and 2.

x1 = dlarray(-1);
x2 = dlarray(2);
[fval,dydx1,dydx2] = dlfeval(@rosenbrock2,x1,x2)
fval = 
  1x1 dlarray


dydx1 = 
  1x1 dlarray


dydx2 = 
  1x1 dlarray


Plot the gradient of Rosenbrock's function for several points in the unit square. First, initialize the arrays representing the evaluation points and the output of the function.

[X1 X2] = meshgrid(linspace(0,1,10));
X1 = dlarray(X1(:));
X2 = dlarray(X2(:));
Y = dlarray(zeros(size(X1)));
DYDX1 = Y;
DYDX2 = Y;

Evaluate the function in a loop. Plot the result using quiver.

for i = 1:length(X1)
    [Y(i),DYDX1(i),DYDX2(i)] = dlfeval(@rosenbrock2,X1(i),X2(i));

Figure contains an axes. The axes contains an object of type quiver.

Input Arguments

collapse all

Function to evaluate, specified as a function handle. If fun includes a dlgradient call, then dlfeval evaluates the gradient by using automatic differentiation. In this gradient evaluation, each argument of the dlgradient call must be a dlarray or a cell array, structure, or table containing a dlarray. The number of input arguments to dlfeval must be the same as the number of input arguments to fun.

Example: @rosenbrock

Data Types: function_handle

Function arguments, specified as any MATLAB data type or a dlnetwork object.

An input argument xj that is a variable of differentiation in a dlgradient call must be a traced dlarray or a cell array, structure, or table containing a traced dlarray. An extra variable such as a hyperparameter or constant data array does not have to be a dlarray.

To evaluate gradients for deep learning, you can provide a dlnetwork object as a function argument and evaluate the forward pass of the network inside fun.

Example: dlarray([1 2;3 4])

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | table | cell | function_handle | categorical | datetime | duration | calendarDuration | fi

Output Arguments

collapse all

Function outputs, returned as any data type. If the output results from a dlgradient call, the output is a dlarray.


Introduced in R2019b