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

FunctionDescription
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 each input channel across a mini-batch. To speed up training of convolutional neural networks 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 categorical cross-entropy loss between network predictions and target values for multiclass classification problems.
dlconv The convolution operation applies sliding filters to the input data. Use 1-D and 2-D filters with ungrouped or grouped convolutions and 3-D filters with ungrouped convolutions.
dltranspconv The transposed convolution operation upsamples feature maps.
fullyconnect The fully connect operation multiplies the input by a weight matrix and then adds a bias vector.
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 problems.
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

FunctionDescription
dimsThis function returns the dimension labels of a dlarray.
dlfevalThis function evaluates a dlarray function using automatic differentiation.
dlgradientThis function computes gradients using automatic differentiation.
extractdataThis function extracts the data from a dlarray.
finddimThis function finds the indices of dlarray dimensions with a given label.
stripdimsThis function removes the dimension labels from a dlarray.

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

FunctionNotes and Limitations
abs

The output dlarray has the same data format as the input dlarray.

cos
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, -

Binary Element-wise Operators

FunctionNotes and Limitations
minus, -

If the two dlarray inputs have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

plus, +
power, .^
  • If the two dlarray inputs have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

  • 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 have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

times, .*

Reduction Functions

FunctionNotes 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

FunctionNotes and Limitations
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 dlarray inputs that have dimension labels, the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

min

Other Math Operators

FunctionNotes 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 unlabeled.

mrdivide, /

The second dlarray input must be a scalar. The output dlarray has the same data format as the first dlarray input.

mtimes, *

One dlarray input can have dimension labels only when the other input is an unlabeled scalar. In this case, the output dlarray has the same dimension labels as the labeled dlarray input.

Logical Operations

FunctionNotes and Limitations
all

The output dlarray has the same data format as the input dlarray.

and, &

If the two dlarray inputs have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

any

The output dlarray has the same data format as the input dlarray.

eq, ==

If the two dlarray inputs have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

ge, >=
gt, >
le, <=
lt, <
ne, ~=
not, ~

The output dlarray has the same data format as the input dlarray.

or, |

If the two dlarray inputs have dimension labels, then the output dlarray has a combination of both of their dimension labels. The function uses implicit expansion to combine the inputs. For more information, see Implicit Expansion with Dimension Labels.

xor

Size Manipulation Functions

FunctionNotes and Limitations
reshape

The output dlarray has no dimension labels, even if the input dlarray has them.

squeeze

If the input dlarray has dimension labels, the function removes the labels belonging to singleton dimensions. Two-dimensional dlarray objects are unaffected by squeeze. If the input dlarray has more than two labeled dimensions, and its third and above dimensions are singletons, then the function discards these dimensions and their labels.

Transposition Operations

FunctionNotes and Limitations
ctranspose, '

If the input dlarray has dimension labels, then both dimension labels must be the same. The function performs transposition implicitly, and transposes directly only if necessary for other operations.

permute

If the input dlarray has dimension labels, 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 has dimension labels, then both dimension labels must be the same. The function performs transposition implicitly, and transposes directly only if necessary for other operations.

Concatenation Functions

FunctionNotes and Limitations
cat

The dlarray inputs must have matching labels or be unlabeled. Mixed labeled and unlabeled inputs are supported. If any dlarray inputs have dimension labels, then the output dlarray has the same labels.

horzcat
vertcat

Conversion Functions

FunctionNotes 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 has the same dimension labels 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 has the same dimension labels as the input A.

double

The output is a dlarray that contains data of type double.

gather
  • 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
  • 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

For a nonscalar input dlarray, the output is a dlarray that contains data of type logical. However, if the input is scalar, then the output is a basic (non-dlarray) logical value. To avoid this behavior, use dlX~=0 instead of logical(dlX). The command dlX~=0 always returns a dlarray that contains data of type logical, even for scalar inputs.

singleThe output is a dlarray that contains data of type single.

Comparison Functions

FunctionNotes 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 is equal and if they both have either the same dimension labels or no dimension labels.

isequaln
  • The syntax with more than two input arguments is not supported.

  • Two dlarray inputs are equal if the numeric data they represent is equal (treating NaNs as equal) and if they both have either the same dimension labels or no dimension labels.

Data Type Identification Functions

FunctionNotes and Limitations
isfloat

The software applies the function to the underlying data of an input dlarray.

islogical
isnumeric
isreal

Because dlarray does not support complex numbers, this function always returns true for a dlarray input.

Size Identification Functions

FunctionNotes and Limitations
iscolumnThis 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.
ismatrixThis 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.
isrowThis 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.
isscalarN/A
isvectorThis 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.
lengthN/A
ndims

If the input dlarray dlX has dimension labels, then ndims(dlX) returns the number of dimension labels, even if some of the labeled dimensions are trailing singleton dimensions.

numelN/A
size

If the input dlarray dlX has dimension labels, 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

FunctionNotes and Limitations
falseOnly the 'like' syntax is supported for dlarray.
inf
nan
ones
rand
randn
true
zeros

String and Character Functions

FunctionNotes and Limitations
composeN/A
fprintf
int2str
mat2str
num2str
sprintf

Notable dlarray Behaviors

Implicit Expansion with Dimension Labels

Some functions use implicit expansion to combine two dlarray inputs that have dimension labels. The function introduces singleton dimensions (dimensions of size 1) with dimension labels into the inputs, as necessary, to make their dimensions 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 labels of one dlarray input do not need to be a subset of the labels 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 dimension 'S' 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 labeled 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 labeled 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 Dimension Labels.

Indexing

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

  • dlX(idx1,...,idxn) returns a dlarray with the same dimension labels as dlX if n is greater than or equal to ndims(dlX). Otherwise, it returns a dlarray without dimension labels.

  • If you set dlY(idx1,...,idxn) = dlX, then dlY has the same dimension labels as before, although the software might add or remove trailing 'U' labels. The dimension labels of dlX have no impact on this operation.

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.

See Also

| | |

Related Topics