dlarray

R2026b

Deep learning array for customization

Description

A deep learning array stores data with optional data format labels for custom training loops, and enables functions to compute and use derivatives through automatic differentiation.

Tip

For most deep learning tasks, you can use a pretrained neural 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 Retrain Neural Network to Classify New Images. Alternatively, you can create and train neural networks from scratch using the trainnet 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 Train Network Using Custom Training Loop.

If the trainnet function does not provide the loss function that you need for your task, then you can specify a custom loss function to the trainnet as a function handle. For loss functions that require more inputs than the predictions and targets (for example, loss functions that require access to the neural network or additional inputs), train the model using a custom training loop. To learn more, see Train Network Using Custom Training Loop.

If Deep Learning Toolbox™ does not provide the layers you need for your task, then you can create a custom layer. To learn more, see Define Custom Deep Learning Layers. For models that cannot be specified as networks of layers, you can define the model as a function. To learn more, see Train Network Using Model Function.

For more information about which training method to use for which task, see Train Deep Learning Model in MATLAB.

Creation

Syntax

dlX = dlarray(X)

dlX = dlarray(X,fmt)

dlX = dlarray(v,dim)

Description

dlX = dlarray(X) returns a dlarray object representing X. If X is a dlarray object, dlX is a copy of X.

dlX = dlarray(X,fmt) formats the data in dlX with dimension labels according to the data format in fmt. Dimension labels help in passing deep learning data between functions. For more information on dimension labels, see Deep Learning Data Formats.

Setting fmt to "" does not remove formats from data. Use stripdims instead.

dlX = dlarray(v,dim) accepts a vector v and a single character format dim, and returns a column vector dlarray. The first dimension of dlX has the dimension label dim, and the second (singleton) dimension has the dimension label 'U'.

Input Arguments

X — Data array

numeric array of data type double or single | logical array | gpuArray object | dlarray object

Data array, specified as a numeric array of data type double or single, a logical array, a gpuArray object, or a dlarray object. X must be full, not sparse.

Example: rand(31*23,23)

Data Types: single | double | logical
Complex Number Support: Yes

fmt — Data format

"" (default) | character vector | string scalar

Data format, specified as a string scalar or a character vector.

If fmt is "", then the format of dlX depends on the input X:

• If X is a not a formatted dlarray object, then the output dlX has no format.

• If X is a formatted dlarray object, then the output dlX has the same format as X.

Warning

Setting fmt to "" does not remove formats from data. Use stripdims instead.

If fmt is nonempty, then each character in the string must be one of the following dimension labels:

• "S" — Spatial

• "C" — Channel

• "B" — Batch

• "T" — Time

• "U" — Unspecified

You can specify multiple dimensions labeled "S" or "U". You can use the labels "C", "B", and "T" at most once each. The software ignores singleton trailing "U" dimensions after the second dimension.

When you create a formatted dlarray object, the software automatically permutes the dimensions such that the format has dimensions in this order:

• "S"

• "C"

• "B"

• "T"

• "U"

For example, if you specify a format of "TCB" (time, channel, batch), then the software automatically permutes the dimensions so that it has format "CBT" (channel, batch, time).

If fmt is nonempty, then it must contain at least the same number of dimension labels as the number of dimensions of the input data. If you specify more than that number of dimension labels, dlarray creates empty (singleton) dimensions for the additional labels.

The following table indicates recommended data formats for common types of data.

Data	Example
	Shape	Data Format
2-D images	h-by-w-by-c-by-n numeric array, where h, w, c and n are the height, width, number of channels of the images, and number of observations, respectively.	"SSCB"
3-D images	h-by-w-by-d-by-c-by-n numeric array, where h, w, d, c and n are the height, width, depth, number of channels of the images, and number of image observations, respectively.	"SSSCB"
Vector sequences	c-by-s-by-n matrix, where c is the number of features of the sequence, s is the sequence length, and n is the number of sequence observations.	"CTB"
2-D image sequences	h-by-w-by-c-by-s-by-n array, where h, w, and c correspond to the height, width, and number of channels of the image, respectively, s is the sequence length, and n is the number of image sequence observations.	"SSCTB"
3-D image sequences	h-by-w-by-d-by-c-by-s-by-n array, where h, w, d, and c correspond to the height, width, depth, and number of channels of the image, respectively, s is the sequence length, and n is the number of image sequence observations.	"SSSCTB"
Features	c-by-n array, where c is the number of features, and n is the number of observations.	"CB"

v — Data vector

numeric vector of data type double or single | logical vector | dlarray vector object

Data vector, specified as a numeric vector of data type double or single, logical vector, or dlarray vector object. Here, "vector" means any array with exactly one nonsingleton dimension.

Example: rand(100,1)

dim — Dimension label

single character

Dimension label, specified as a single character of the type allowed for fmt.

Example: "S"

Example: 'S'

Output Arguments

dlX — Deep learning array

dlarray object

Deep learning array, returned as a dlarray object. dlX enables automatic differentiation using dlgradient and dlfeval. If you supply the fmt argument, dlX has labels.

• If X is a numeric or logical array, dlX contains its data, possibly reordered because of the data format in fmt.

• If X is a gpuArray, the data in dlX is also on the GPU. Subsequent calculations using dlX are performed on the GPU.

Object Functions

dims	Data format of dlarray object
dlgradient	Compute gradients for custom training loops using automatic differentiation
extractdata	Extract data from dlarray object
finddim	Find dimensions with specified label
stripdims	Remove dlarray data format

A dlarray also allows functions for numeric, matrix, and other operations. See the full list in List of Functions with dlarray Support.

Examples

Create Unformatted dlarray

Create an unformatted dlarray from a matrix.

X = randn(3,5);
dlX = dlarray(X)

dlX = 
  3×5 dlarray

    0.5377    0.8622   -0.4336    2.7694    0.7254
    1.8339    0.3188    0.3426   -1.3499   -0.0631
   -2.2588   -1.3077    3.5784    3.0349    0.7147

Create Formatted dlarray

Create a dlarray that has a data format containing the dimension labels 'S' and 'C'.

X = randn(3,5);
dlX = dlarray(X,'SC')

dlX = 
  3(S) × 5(C) dlarray

    0.5377    0.8622   -0.4336    2.7694    0.7254
    1.8339    0.3188    0.3426   -1.3499   -0.0631
   -2.2588   -1.3077    3.5784    3.0349    0.7147

If you specify the dimension labels in the opposite order, dlarray implicitly reorders the underlying data.

dlX = dlarray(X,'CS')

dlX = 
  5(S) × 3(C) dlarray

    0.5377    1.8339   -2.2588
    0.8622    0.3188   -1.3077
   -0.4336    0.3426    3.5784
    2.7694   -1.3499    3.0349
    0.7254   -0.0631    0.7147

Create Formatted dlarray Vector

Create a dlarray vector with the first dimension label 'T'. The second dimension label, which dlarray creates automatically, is 'U'.

X = randn(6,1);
dlX = dlarray(X,'T')

dlX = 
  6(T) × 1(U) dlarray

    0.5377
    1.8339
   -2.2588
    0.8622
    0.3188
   -1.3077

If you specify a row vector for X, dlarray implicitly reorders the result to be a column vector.

X = X';
dlX = dlarray(X,'T')

dlX = 
  6(T) × 1(U) dlarray

    0.5377
    1.8339
   -2.2588
    0.8622
    0.3188
   -1.3077

More About

Deep Learning Data Formats

Most deep learning networks and functions operate on different dimensions of the input data in different ways.

For example, an LSTM operation iterates over the time dimension of the input data, and a batch normalization operation normalizes over the batch dimension of the input data.

Data can have many different types of layouts:

• Data can have different numbers of dimensions. For example, you can represent image and video data as 4-D and 5-D arrays, respectively.

• Dimensions of data can represent different things. For example, image data has two spatial dimensions, one channel dimension, and one batch dimension.

• Data can have dimensions in multiple permutations. For example, you can represent a batch of sequences as a 3-D array with dimensions corresponding to channels, time steps, and observations. These dimensions can be in any order.

To provide input data with labeled dimensions or input data with additional layout information, you can use data formats.

A deep learning data format is a string of characters, where each character describes the type of the corresponding data dimension. The characters are:

• "S" — Spatial

• "C" — Channel

• "B" — Batch

• "T" — Time

• "U" — Unspecified

For example, suppose you have an array that represents a batch of sequences where the first, second, and third dimensions correspond to channels, observations, and time steps, respectively. You can describe the data as having the format "CBT" (channel, batch, time).

Providing formatted data can be easier than reshaping and preprocessing your data. For example, if you have sequence data, where the first, second, and third dimensions correspond to channels, observations, and time steps, respectively, then you can specify the string "CBT" instead of permuting and preprocessing the data to have the layout required by the software.

To create formatted input data, specify the format using the fmt argument. For example, for an array X that represents a batch of sequences, where the first, second, and third dimension correspond to channels, observations, and time steps, respectively, specify:

X = dlarray(X,"CBT");

For more information, see Deep Learning Data Formats.

Tips

• A dlgradient call must be inside a function. To obtain a numeric value of a gradient, you must evaluate the function using dlfeval, and the argument to the function must be a dlarray. See Use Automatic Differentiation In Deep Learning Toolbox.

• To enable the correct evaluation of gradients, dlfeval must call functions that use only supported functions for dlarray. See List of Functions with dlarray Support.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

For usage recommendations, list of functions and limitations with dlarray code generation support, see Code Generation for dlarray (MATLAB Coder). For an example showing how to use dlnetwork and dlarray objects to generate MEX for a trained variational autoencoder (VAE) network, see Generate Digit Images Using Variational Autoencoder on Intel CPUs (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

For usage recommendations, list of functions and limitations with dlarray code generation support, see Code Generation for dlarray (GPU Coder). For an example showing how to use dlnetwork and dlarray objects to generate CUDA^® MEX for a trained variational autoencoder (VAE) network, see Generate Digit Images on NVIDIA GPU Using Variational Autoencoder (GPU Coder).

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The dlarray function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2019b

R2026b: Code generation supports numeric inputs and unformatted dlarray inputs for predict

Starting in R2026b, you can pass numeric arrays and unformatted dlarray objects directly to the predict function of a dlnetwork object for code generation.

For more information, see Code Generation for dlarray (MATLAB Coder).

R2022b: Code generation behavior change for dlarray inputs and outputs

In R2022b, the generated code creates structures for the dlarray inputs and outputs of entry-point functions. Data is a public field that you can directly access.

In previous releases, the generated code uses class to represent the dlarray inputs and outputs of entry-point functions. In these releases, you use the initializing function init to access the Data field.