Transition trainNetwork, SeriesNetwork, and DAGNetwork Code to dlnetwork Workflows

R2026b

Starting in R2024a, the trainNetwork function and related functionality (such as SeriesNetwork and DAGNetwork objects) are not recommended. Use dlnetwork objects, the trainnet function, and related functionality instead.

There are no plans to remove these functions and objects. However, dlnetwork objects and the trainnet function have these advantages:

  • dlnetwork objects are a unified data type that supports network building, prediction, built-in training, visualization, compression, verification, and custom training loops.

  • dlnetwork objects support a wider range of network architectures that you can create or import from external platforms.

  • The trainnet function enables you to specify loss functions. You can choose from built-in loss functions or specify a custom loss function.

  • Training and prediction with dlnetwork objects are typically faster than with SeriesNetwork and DAGNetwork objects.

Tip

To learn more about transitioning legacy neural network code (for example, functionality that relates to the network object) see Transition Legacy Neural Network Code to dlnetwork Workflows.

Recommended Workflow Examples

In most cases, taking code from examples and adapting it for your task is the easiest option. These examples show the recommended workflows for common deep learning tasks:

TaskExample
Image classificationCreate Simple Deep Learning Neural Network for Classification
Transfer learningRetrain Neural Network to Classify New Images
Sequence classificationSequence Classification Using Deep Learning
Numeric featuresTrain Network with Numeric Features

For greater flexibility or to reproduce algorithms exactly, you can write a custom training loop. For more information, see Custom Training Loops.

Update Training Code

The trainNetwork function uses output layers (such as classificationLayer and regressionLayer objects) to determine the loss function. The trainnet function instead takes a loss function as an input argument, so you do not need an output layer.

When updating your training code, note these key differences:

  • Remove output layers (for example, classificationLayer and regressionLayer objects) from the layer array or graph.

  • Specify the loss function using the trainnet function. For classification tasks, you can use "crossentropy". For regression tasks, you can use "mse".

  • Replace layerGraph objects with dlnetwork objects.

  • The trainnet function returns a dlnetwork object (not a SeriesNetwork or DAGNetwork object).

This table shows how to update typical trainNetwork code to use the trainnet function.

TaskNot RecommendedRecommended
Train classification network 
layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    reluLayer
    fullyConnectedLayer(10)
    softmaxLayer
    classificationLayer];

net = trainNetwork(data,layers,options);
 
layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    reluLayer
    fullyConnectedLayer(10)
    softmaxLayer];

net = trainnet(data,layers,"crossentropy",options);
Train regression network 
layers = [
    featureInputLayer(12)
    fullyConnectedLayer(25)
    reluLayer
    fullyConnectedLayer(1)
    regressionLayer];

net = trainNetwork(X,T,layers,options);
 
layers = [
    featureInputLayer(12)
    fullyConnectedLayer(25)
    reluLayer
    fullyConnectedLayer(1)];

net = trainnet(X,T,layers,"mse",options);
Train classification network with weights 
layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    reluLayer
    fullyConnectedLayer(10)
    softmaxLayer
    classificationLayer(ClassWeights=weights)];

net = trainNetwork(data,layers,options);
 
layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    reluLayer
    fullyConnectedLayer(10)
    softmaxLayer];

weights = dlarray(weights,"C");
lossFcn = @(Y,T) crossentropy(Y,T,weights);
net = trainnet(data,layers,lossFcn,options);

Update Prediction Code

The classify and predict functions for SeriesNetwork and DAGNetwork objects are not recommended. For dlnetwork objects, use the minibatchpredict function for multiple observations, or the predict function for a single observation.

This table shows how to update prediction code.

TaskNot RecommendedRecommended
Predict labels 
Y = classify(net,X);
 
scores = minibatchpredict(net,X);
Y = scores2label(scores,classNames);
Predict numeric values 
Y = predict(net,X);
 
Y = minibatchpredict(net,X);
Extract activations 
Y = activations(net,X,layerName);
 
Y = minibatchpredict(net,X,Outputs=layerName);

% Or, for a single observation:
Y = predict(net,X,Outputs=layerName);
Predict labels and update state 
[net,Y] = classifyAndUpdateState(net,X);
 
[scores,state] = predict(net,X);
Y = scores2label(scores,classNames);
net.State = state;
Predict numeric values and update state 
[net,Y] = predictAndUpdateState(net,X);
 
[Y,state] = predict(net,X);
net.State = state;

Convert Existing Networks

If you have existing trained SeriesNetwork or DAGNetwork objects, then you can convert them to dlnetwork objects using the dag2dlnetwork function. This function converts any SeriesNetwork or DAGNetwork object to a dlnetwork object and removes the output layer.

net = dag2dlnetwork(trainedNet);

Update Network Architecture Code

If you construct network architectures using layerGraph objects, then you can build dlnetwork objects directly instead. The dlnetwork object supports the same network building functions (such as addLayers and connectLayers), so you can reuse the same function calls to edit the network.

TaskNot RecommendedRecommended
Create network with branching 
layers = ...;
lgraph = layerGraph(layers);

layers = ...;
lgraph = addLayers(lgraph,layers);

lgraph = connectLayers(lgraph,"in","conv_skip");
lgraph = connectLayers(lgraph,"relu_skip","add/in2");
 
net = dlnetwork;

layers = ...;
net = addLayers(net,layers);

layers = ...;
net = addLayers(net,layers);

net = connectLayers(net,"in","conv_skip");
net = connectLayers(net,"relu_skip","add/in2");

When you create a neural network with branching, such as neural networks with skip connections, start with an empty dlnetwork object and build on it. This approach prevents the software from initializing the learnable parameters before you finish building the network. If the neural network does not have an input layer, is misconfigured, or is not complete, then the layer array input syntax dlnetwork(layers) fails because the software cannot initialize the learnable parameters of the network. Alternatively, to convert a layer array to a dlnetwork object without initializing the learnable parameters, use net = dlnetwork(layers,Initialize=false).

Working with Pretrained Image Networks

If you use pretrained network functions that return SeriesNetwork or DAGNetwork objects (such as alexnet, vgg16, or resnet50), then use the imagePretrainedNetwork function instead. This function returns a dlnetwork object and automatically adjusts the network for transfer learning workflows, so you do not need to edit the network layers.

TaskNot RecommendedRecommended
Make predictions with pretrained image classification network 
net = googlenet;
Y = classify(net,X);
 
net = imagePretrainedNetwork("googlenet");
scores = minibatchpredict(net,X);
Y = scores2label(scores,classNames);
Set up pretrained image classification network for transfer learning 
net = resnet50;
lgraph = layerGraph(net);

layer = fullyConnectedLayer(numClasses,Name="fc_new");
lgraph = replaceLayer(lgraph,"fc1000",layer);

layer = softmaxLayer(Name="softmax_new");
lgraph = replaceLayer(lgraph,"fc1000_softmax",layer);

layer = classificationLayer(Name="output_new");
lgraph = replaceLayer(lgraph,"ClassificationLayer_fc1000",layer);

net = trainNetwork(data,lgraph,options);
 
net = imagePretrainedNetwork("resnet50", ...
    NumClasses=numClasses);
net = trainnet(data,net,"crossentropy",options);

Summary of Recommendations

This table summarizes the functions and objects that are not recommended and their recommended replacements.

CategoryNot RecommendedRecommendation
Training

trainNetwork

Use trainnet with an explicit loss function.

Network types

SeriesNetwork

Use dlnetwork objects. To convert existing objects, use dag2dlnetwork.

DAGNetwork

Network building

LayerGraph, assembleNetwork

Create dlnetwork objects directly from layer arrays.

Output layers

classificationLayer, ClassificationOutputLayer, regressionLayer, RegressionOutputLayer

Remove output layers and specify the loss function directly in trainnet. Use "crossentropy" for classification and "mse" for regression.

Prediction

classify

Use minibatchpredict followed by scores2label.

predict (SeriesNetwork, DAGNetwork)

Use minibatchpredict or predict (dlnetwork).

Layer activations

activations

Use minibatchpredict or predict with the Outputs argument.

Stateful prediction

classifyAndUpdateState, predictAndUpdateState

Use predict and update the network state manually using net.State = state.

Pretrained networks

alexnet, darknet19, darknet53, densenet201, efficientnetb0, googlenet, inceptionresnetv2, inceptionv3, mobilenetv2, nasnetlarge, nasnetmobile, resnet18, resnet50, resnet101, shufflenet, squeezenet, vgg16, vgg19, xception

Use imagePretrainedNetwork, which returns a dlnetwork object.

Network architecture helpers

resnetLayers, resnet3dLayers

Use resnetNetwork and resnet3dNetwork, which have the same syntax and return dlnetwork objects.

Sequence folding

sequenceFoldingLayer, sequenceUnfoldingLayer

Most dlnetwork architectures do not require sequence folding or unfolding layers. If you need to reshape data for downstream layers, then use a functionLayer object instead.

Import helpers

findPlaceholderLayers, PlaceholderLayer

Use importNetworkFromTensorFlow or importNetworkFromONNX, which return dlnetwork objects without placeholder layers.

For more specific information, refer to the reference page of the affected functionality.

See Also

| | | | | | |

Topics