List of Functions with dlarray Support

List of Functions with `dlarray` Support

Deep Learning Toolbox Functions with `dlarray` Support

These tables list and briefly describe the Deep Learning Toolbox™ functions that operate on dlarray objects.

Deep Learning Operations

Function	Description
`avgpool`	The average pooling operation performs downsampling by dividing the input into pooling regions and computing the average value of each region.
`batchnorm`	The batch normalization operation normalizes the input data across all observations for each channel independently. To speed up training of the convolutional neural network and reduce the sensitivity to network initialization, use batch normalization between convolution and nonlinear operations such as `relu`.
`crossentropy`	The cross-entropy operation computes the cross-entropy loss between network predictions and target values for single-label and multi-label classification tasks.
`crosschannelnorm`	The cross-channel normalization operation uses local responses in different channels to normalize each activation. Cross-channel normalization typically follows a `relu` operation. Cross-channel normalization is also known as local response normalization.
`ctc`	The CTC operation computes the connectionist temporal classification (CTC) loss between unaligned sequences.
`dlconv`	The convolution operation applies sliding filters to the input data. Use the `dlconv` function for deep learning convolution, grouped convolution, and channel-wise separable convolution.
`dltranspconv`	The transposed convolution operation upsamples feature maps.
`embed`	The embed operation converts numeric indices to numeric vectors, where the indices correspond to discrete data. Use embeddings to map discrete data such as categorical values or words to numeric vectors.
`fullyconnect`	The fully connect operation multiplies the input by a weight matrix and then adds a bias vector.
`groupnorm`	The group normalization operation normalizes the input data across grouped subsets of channels for each observation independently. To speed up training of the convolutional neural network and reduce the sensitivity to network initialization, use group normalization between convolution and nonlinear operations such as `relu`.
`gru`	The gated recurrent unit (GRU) operation allows a network to learn dependencies between time steps in time series and sequence data.
`huber`	The Huber operation computes the Huber loss between network predictions and target values for regression tasks. When the `'TransitionPoint'` option is 1, this is also known as smooth L₁ loss.
`instancenorm`	The instance normalization operation normalizes the input data across each channel for each observation independently. To improve the convergence of training the convolutional neural network and reduce the sensitivity to network hyperparameters, use instance normalization between convolution and nonlinear operations such as `relu`.
`layernorm`	The layer normalization operation normalizes the input data across all channels for each observation independently. To speed up training of recurrent and multi-layer perceptron neural networks and reduce the sensitivity to network initialization, use layer normalization after the learnable operations, such as LSTM and fully connect operations.
`leakyrelu`	The leaky rectified linear unit (ReLU) activation operation performs a nonlinear threshold operation, where any input value less than zero is multiplied by a fixed scale factor.
`lstm`	The long short-term memory (LSTM) operation allows a network to learn long-term dependencies between time steps in time series and sequence data.
`maxpool`	The maximum pooling operation performs downsampling by dividing the input into pooling regions and computing the maximum value of each region.
`maxunpool`	The maximum unpooling operation unpools the output of a maximum pooling operation by upsampling and padding with zeros.
`mse`	The half mean squared error operation computes the half mean squared error loss between network predictions and target values for regression tasks.
`onehotdecode`	The one-hot decode operation decodes probability vectors, such as the output of a classification network, into classification labels. The input `A` can be a `dlarray`. If `A` is formatted, the function ignores the data format.
`relu`	The rectified linear unit (ReLU) activation operation performs a nonlinear threshold operation, where any input value less than zero is set to zero.
`sigmoid`	The sigmoid activation operation applies the sigmoid function to the input data.
`softmax`	The softmax activation operation applies the softmax function to the channel dimension of the input data.

`dlarray`-Specific Functions

Function	Description
`dims`	This function returns the data format of a `dlarray`.
`dlfeval`	This function evaluates a `dlarray` function using automatic differentiation.
`dlgradient`	This function computes gradients using automatic differentiation.
`extractdata`	This function extracts the data from a `dlarray`.
`finddim`	This function finds the indices of `dlarray` dimensions with a given dimension label.
`stripdims`	This function removes the data format from a `dlarray`.

Domain-Specific Functions with `dlarray` Support

These tables list and briefly describe the domain-specific functions that operate on dlarray objects.

Computer Vision

Function	Description
`generalizedDice` (Computer Vision Toolbox)	Measure the similarity between two `dlarray` objects that represent segmented images, using a generalized Dice metric that accounts for class weighting.

Image Processing

Function	Description
`depthToSpace` (Image Processing Toolbox)	Rearrange `dlarray` data from the depth dimension into spatial blocks.
`dlresize` (Image Processing Toolbox)	Resize the spatial dimensions of a `dlarray`.
`multissim` (Image Processing Toolbox)	Measure the similarity between two `dlarray` objects that represent 2-D images, using the multiscale structural similarity (MS-SSIM) metric.
`multissim3` (Image Processing Toolbox)	Measure the similarity between two `dlarray` objects that represent 3-D images, using the 3-D MS-SSIM metric.
`psnr` (Image Processing Toolbox)	Measure the similarity between two `dlarray` objects that represent images using the peak signal-to-noise ratio (PSNR) metric.
`spaceToDepth` (Image Processing Toolbox)	Rearrange spatial blocks of `dlarray` data into the depth dimension.

Signal Processing

Function	Description
`dlstft` (Signal Processing Toolbox)	Compute short-time Fourier transform.

MATLAB Functions with `dlarray` Support

Many MATLAB^® functions operate on dlarray objects. These tables list the usage notes and limitations for these functions when you use dlarray arguments.

Unary Element-wise Functions

Function	Notes and Limitations
`abs`	The output `dlarray` has the same data format as the input `dlarray`.
`acos`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, each element x in the input `dlarray` must have ∣x∣ ≤ 1 .
`acosh`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, each element x in the input `dlarray` must have x ≥ 1.
`acot`	The output `dlarray` has the same data format as the input `dlarray`.
`acsc`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, each element x in the input `dlarray` must have ∣x∣ ≥ 1.
`asec`
`asin`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, each element x in the input `dlarray` must have ∣x∣ ≤ 1.
`asinh`	The output `dlarray` has the same data format as the input `dlarray`.
`atan`
`atan2`
`atanh`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, each element x in the input `dlarray` must have ∣x∣ ≤ 1.
`cos`	The output `dlarray` has the same data format as the input `dlarray`.
`cosh`
`cot`
`csc`
`exp`
`log`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, the input `dlarray` must have nonnegative values.
`sec`	The output `dlarray` has the same data format as the input `dlarray`.
`sign`
`sin`
`sinh`
`sqrt`	The output `dlarray` has the same data format as the input `dlarray`. Because `dlarray` does not support complex numbers, the input `dlarray` must have nonnegative values.
`tan`	The output `dlarray` has the same data format as the input `dlarray`.
`tanh`
`uminus`, `-`
`uplus`, `+`

Binary Element-wise Operators

Function	Notes and Limitations
`minus`, `-`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats.
`plus`, `+`
`power`, `.^`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats. Because `dlarray` does not support complex numbers, the software generates an error if any element of the output is complex.
`rdivide`, `./`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats.
`times`, `.*`

Reduction Functions

Function	Notes and Limitations
`mean`	The output `dlarray` has the same data format as the input `dlarray`. The `'omitnan'` option is not supported. If the input `dlarray` is on the GPU, the `'native'` option is not supported.
`prod`	The output `dlarray` has the same data format as the input `dlarray`. The `'omitnan'` option is not supported.
`sum`

Extrema Functions

Function	Notes and Limitations
`ceil`	The output `dlarray` has the same data format as the input `dlarray`.
`eps`	The output `dlarray` has the same data format as the input `dlarray`. Use `eps(ones(‘like’, x))` to get a scalar epsilon value based on the data type of a `dlarray` `x`.
`fix`	The output `dlarray` has the same data format as the input `dlarray`.
`floor`	The output `dlarray` has the same data format as the input `dlarray`.
`max`	When you find the maximum or minimum elements of a single `dlarray`, the output `dlarray` has the same data format as the input `dlarray`. When you find the maximum or minimum elements between two formatted `dlarray` inputs, the output `dlarray` has a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats. The index output argument is not traced and cannot be used with automatic differentiation. For more information, see Use Automatic Differentiation In Deep Learning Toolbox.
`min`
`rescale`	If the first input `dlarray` `A` is unformatted, all additional inputs must be unformatted. If the first input `dlarray` `A` is formatted, all additional inputs must either be unformatted scalars, or have data formats that are a subset of the data format of `A`. In this case, each dimension must either be singleton or match the length of the corresponding dimension of `A`.
`round`	Only the syntax `Y = round(X)` is supported. The output `dlarray` has the same data format as the input `dlarray`.

Other Math Operations

Function	Notes and Limitations
`colon`, `:`	The supported operations are: `a:b` `a:b:c` For information on indexing into a `dlarray`, see Indexing. All inputs must be real scalars. The output `dlarray` is unformatted.
`interp1`	Sample points input `x` must be a finite, increasing vector without repeating elements. `method` must be `'linear'` or `'nearest'`. The piecewise polynomial syntax (`'pp'`) is not supported. Only the sample values input `v` can be a formatted `dlarray`. All other inputs must be unformatted. If `v` is a formatted `dlarray`, query points input `xq` must be a vector, and the output `vq` has the same data format as `v`.
`mrdivide`, `/`	The second `dlarray` input must be a scalar. The output `dlarray` has the same data format as the first `dlarray` input.
`mtimes`, `*`	One input can be a formatted `dlarray` only when the other input is an unformatted scalar. In this case, the output `dlarray` has the same data format as the formatted `dlarray` input. Multiplying a `dlarray` with a non-`dlarray` sparse matrix is supported only when both inputs are non-scalar.
`pagemtimes`	One input can be a formatted `dlarray` only when the other input is unformatted, with scalar pages. In this case, the output `dlarray` has the same data format as the formatted `dlarray` input.

Logical Operations

Function	Notes and Limitations
`all`	The output `dlarray` has the same data format as the input `dlarray`.
`and`, `&`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats.
`any`	The output `dlarray` has the same data format as the input `dlarray`.
`eq`, `==`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats.
`ge`, `>=`
`gt`, `>`
`le`, `<=`
`lt`, `<`
`ne`, `~=`
`not`, `~`	The output `dlarray` has the same data format as the input `dlarray`.
`or`, `\|`	If the two `dlarray` inputs are formatted, then the output `dlarray` is formatted with a combination of both of their data formats. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Data Formats.
`xor`

Size Manipulation Functions

Function	Notes and Limitations
`reshape`	The output `dlarray` is unformatted, even if the input `dlarray` is formatted.
`squeeze`	Two-dimensional `dlarray` objects are unaffected by `squeeze`. If the input `dlarray` is formatted, the function removes dimension labels belonging to singleton dimensions. If the input `dlarray` has more than two dimensions and its third and above dimensions are singleton, then the function discards these dimensions and their labels.

Transposition Operations

Function	Notes and Limitations
`ctranspose`, `'`	If the input `dlarray` is formatted, then the labels of both dimensions must be the same. The function performs transposition implicitly, and transposes directly only if necessary for other operations.
`permute`	If the input `dlarray` is formatted, then the permutation must be among only those dimensions that have the same label. The function performs permutations implicitly, and permutes directly only if necessary for other operations.
`transpose`, `.'`	If the input `dlarray` is formatted, then the labels of both dimensions must be the same. The function performs transposition implicitly, and transposes directly only if necessary for other operations.

Concatenation Functions

Function	Notes and Limitations
`cat`	The `dlarray` inputs must have matching formats or be unformatted. Mixed formatted and unformatted inputs are supported. If any `dlarray` inputs are formatted, then the output `dlarray` is formatted with the same data format.
`horzcat`
`vertcat`

Conversion Functions

Function	Notes and Limitations
`cast`	`cast(dlA,newdatatype)` copies the data in the `dlarray` `dlA` into a `dlarray` of the underlying data type `newdatatype`. The `newdatatype` option must be `'double'`, `'single'`, or `'logical'`. The output `dlarray` is formatted with the same data format as `dlA`. `cast(A,'like',Y)` returns an array of the same type as `Y`. If `Y` is a `dlarray`, then the output is a `dlarray` that has the same underlying data type as `Y`. If `Y` is on the GPU, then the output is on the GPU. If both `A` and `Y` are `dlarray` objects, then the output `dlarray` is formatted with the same data format as the input `A`.
`double`	The output is a `dlarray` that contains data of type `double`.
`gather` (Parallel Computing Toolbox)	The supported syntaxes are: `dlX = gather(dlA)` `[dlX,dlY,dlZ,...] = gather(dlA,dlB,dlC,...)` `gather(dlA)` returns a `dlarray` containing numeric or logical data. This function applies `gather` to the underlying data in the `dlarray` `dlA`. If `dlA` is on the GPU, then `dlX` is in the local workspace, not on the GPU. If `dlA` is in the local workspace (not on the GPU), then `dlX` is equal to `dlA`. `gather(dlA,dlB,dlC,...)` gathers multiple arrays.
`gpuArray` (Parallel Computing Toolbox)	This function requires Parallel Computing Toolbox™. `gpuArray` returns a `dlarray` containing a `gpuArray`. This function applies `gpuArray` to the underlying data. If the input `dlarray` is in the local workspace, then its data is moved to the GPU and internally represented as a `gpuArray`. If the input `dlarray` is on the GPU, then the output `dlarray` is equal to the input `dlarray`.
`logical`	The output is a `dlarray` that contains data of type `logical`.
`single`	The output is a `dlarray` that contains data of type `single`.

Comparison Functions

Function	Notes and Limitations
`isequal`	The syntax with more than two input arguments is not supported. Two `dlarray` inputs are equal if the numeric data they represent are equal and if they both are either formatted with the same data format or unformatted.
`isequaln`	The syntax with more than two input arguments is not supported. Two `dlarray` inputs are equal if the numeric data they represent are equal (treating `NaN`s as equal) and if they both are either formatted with the same data format or unformatted.

Data Type and Value Identification Functions

Function	Notes and Limitations
`isdlarray`	N/A
`isfinite`	The software applies the function to the underlying data of an input `dlarray`.
`isfloat`
`isgpuarray` (Parallel Computing Toolbox)
`isinf`
`islogical`
`isnan`
`isnumeric`
`isreal`	Because `dlarray` does not support complex numbers, this function always returns `true` for a `dlarray` input.
`isUnderlyingType`	N/A
`mustBeUnderlyingType`
`underlyingType`

Size Identification Functions

Function	Notes and Limitations
`iscolumn`	This function returns `true` for a `dlarray` that is a column vector, where each dimension except the first is a singleton. For example, a 3-by-1-by-1 `dlarray` is a column vector.
`ismatrix`	This function returns `true` for `dlarray` objects with only two dimensions and for `dlarray` objects where each dimension except the first two is a singleton. For example, a 3-by-4-by-1 `dlarray` is a matrix.
`isrow`	This function returns `true` for a `dlarray` that is a row vector, where each dimension except the second is a singleton. For example, a 1-by-3-by-1 `dlarray` is a row vector.
`isscalar`	N/A
`isvector`	This function returns `true` for a `dlarray` that is a row vector or column vector. Note that `isvector` does not consider a 1-by-1-by-3 `dlarray` to be a vector.
`length`	N/A
`ndims`	If the input `dlarray` `dlX` is formatted, then `ndims(dlX)` returns the number of dimension labels, even if some of the labeled dimensions are trailing singleton dimensions.
`numel`	N/A
`size`	If the input `dlarray` `dlX` is formatted, then `size(dlX)` returns a vector of length equal to the number of dimension labels, even if some of the labeled dimensions are trailing singleton dimensions.

Creator Functions

Function	Notes and Limitations
`false`	Only the `'like'` syntax is supported for `dlarray`.
`inf`
`nan`
`ones`
`rand`
`randi`
`randn`
`true`
`zeros`

String and Character Functions

Function	Notes and Limitations
`compose`	N/A
`fprintf`
`int2str`
`mat2str`
`num2str`
`sprintf`

Notable dlarray Behaviors

Implicit Expansion with Data Formats

Some functions use implicit expansion to combine two formatted dlarray inputs. The function introduces labeled singleton dimensions (dimensions of size 1) into the inputs, as necessary, to make their formats match. The function inserts singleton dimensions at the end of each block of dimensions with the same label.

To see an example of this behavior, enter the following code.

X = ones(2,3,2);
dlX = dlarray(X,'SCB')
Y = 1:3;
dlY = dlarray(Y,'C')
dlZ = dlX.*dlY

dlX = 

  2(S) × 3(C) × 2(B) dlarray


(:,:,1) =

     1     1     1
     1     1     1


(:,:,2) =

     1     1     1
     1     1     1


dlY = 

  3(C) × 1(U) dlarray

     1
     2
     3


dlZ = 

  2(S) × 3(C) × 2(B) dlarray


(:,:,1) =

     1     2     3
     1     2     3


(:,:,2) =

     1     2     3
     1     2     3

In this example, dlZ(i,j,k) = dlX(i,j,k).*dlY(j) for indices i, j, and k. The second dimension of dlZ (labeled 'C') corresponds to the second dimension of dlX and the first dimension of dlY.

In general, the format of one dlarray input does not need to be a subset of the format of another dlarray input. For example, if dlX and dlY are input arguments with dims(dlX) = 'SCB' and dims(dlY) = 'SSCT', then the output dlZ has dims(dlZ) = 'SSCBT'. The 'S' dimension of dlX maps to the first 'S' dimension of dlY.

Special 'U' Dimension Behavior

The 'U' dimension of a dlarray behaves differently from other labeled dimensions in that it exhibits the standard MATLAB singleton dimension behavior. You can think of a formatted dlarray as having infinitely many 'U' dimensions of size 1 following the dimensions returned by size.

The software discards a 'U' label unless the dimension is nonsingleton or it is one of the first two dimensions of the dlarray.

To see an example of this behavior, enter the following code.

X = ones(2,2);
dlX = dlarray(X,'SC')
dlX(:,:,2) = 2

dlX = 

  2(S) × 2(C) dlarray

     1     1
     1     1


dlX = 

  2(S) × 2(C) × 2(U) dlarray


(:,:,1) =

     1     1
     1     1


(:,:,2) =

     2     2
     2     2

In this example, the software expands a formatted two-dimensional dlarray to a three-dimensional dlarray, and labels the third dimension with 'U' by default. For an example of how the 'U' dimension is used in implicit expansion, see Implicit Expansion with Data Formats.

Indexing

Indexing with a dlarray is supported and exhibits the following behaviors:

dlX(idx1,...,idxn) returns a dlarray with the same data format as dlX if n is greater than or equal to ndims(dlX). Otherwise, it returns an unformatted dlarray.
If you set dlY(idx1,...,idxn) = dlX, then the data format of dlY is preserved, although the software might add or remove trailing 'U' dimension labels. The data format of dlX has no impact on this operation.
If you delete parts of a dlarray using dlX(idx1,…,idxn) = [], then the data format of dlX is preserved if n is greater than or equal to ndims(dlX). Otherwise, dlX is returned unformatted.

Round-off Error

When you use a function with a dlarray input, the order of the operations within the function can change based on the internal storage order of the dlarray. This change can result in differences on the order of round-off for two dlarray objects that are otherwise equal.

Documentation