dlarray

用于自定义的深度学习数组

说明

深度学习数组使用可选的数据格式标签存储数据，以用于自定义训练循环，并通过自动微分使函数能够计算和使用导数。

提示

对于大多数深度学习任务，您可以使用预训练神经网络，并使其适应您自己的数据。有关说明如何使用迁移学习来重新训练卷积神经网络以对一组新图像进行分类的示例，请参阅Retrain Neural Network to Classify New Images。您也可以使用 trainnet 和 trainingOptions 函数从头创建和训练神经网络。

如果 trainingOptions 函数没有提供您的任务所需的训练选项，则您可以使用自动微分创建自定义训练循环。要了解详细信息，请参阅Train Network Using Custom Training Loop。

如果 trainnet 函数没有提供您的任务所需的损失函数，您可以将 trainnet 的自定义损失函数指定为函数句柄。对于需要比预测值和目标值更多输入的损失函数（例如，需要访问神经网络或额外输入的损失函数），请使用自定义训练循环来训练模型。要了解详细信息，请参阅Train Network Using Custom Training Loop。

如果 Deep Learning Toolbox™ 没有提供您的任务所需的层，则您可以创建一个自定义层。要了解详细信息，请参阅定义自定义深度学习层。对于无法指定为由层组成的网络的模型，可以将模型定义为函数。要了解详细信息，请参阅Train Network Using Model Function。

有关对哪项任务使用哪种训练方法的详细信息，请参阅Train Deep Learning Model in MATLAB。

创建对象

语法

dlX = dlarray(X)

dlX = dlarray(X,fmt)

dlX = dlarray(v,dim)

描述

dlX = dlarray(X) 返回一个表示 X 的 dlarray 对象。如果 X 是 dlarray，则 dlX 是 X 的副本。

示例

dlX = dlarray(X,fmt) 根据 fmt 中的数据格式，使用维度标签对 dlX 中的数据进行格式化处理。维度标签有助于在函数之间传递深度学习数据。有关维度标签的详细信息，请参阅用法。如果 X 是格式化的 dlarray，则 fmt 会替换现有格式。

示例

dlX = dlarray(v,dim) 接受向量 v 和单精度字符格式 dim，并返回列向量 dlarray。dlX 的第一个维度具有维度标签 dim，第二个（单一）维度具有维度标签 'U'。

示例

输入参量

全部展开

`X` — 数据数组
`double` 或 `single` 数据类型的数值数组 | `logical` 数组 | `gpuArray` 对象 | `dlarray` 对象

数据数组，指定为 double 或 single 数据类型的数值数组、logical 数组、gpuArray 对象或 dlarray 对象。X 必须是全数组，而非稀疏数组。

示例: rand(31*23,23)

数据类型: single | double | logical
复数支持: 是

`fmt` — 数据格式
字符向量 | 字符串标量

数据格式，指定为字符串标量或字符向量。字符串中的每个字符必须为以下维度标签之一：

"S" - 空间
"C" - 通道
"B" - 批量
"T" - 时间
"U" - 未指定

您可以指定多个标注为 "S" 或 "U" 的维度。每个 "C"、"B" 和 "T" 标签最多可以使用一次。该软件忽略第二个维度后的单一尾部 "U" 维度。

当您创建格式化的 dlarray 对象时，软件会自动置换维度，使格式的维度采用以下顺序：

"S"
"C"
"B"
"T"
"U"

例如，如果您指定 "TCB" 格式（时间、通道、批量），则软件会自动置换维度，使其具有 "CBT" 格式（通道、批量、时间）。

fmt 包含的维度标签数必须至少与输入数据的维数相同。如果您指定的维度标签数超过该维数，则 dlarray 会为额外的标签创建空（单一）维度。

下表列出了常见数据类型的推荐数据格式。

数据	示例
数据	形状	数据格式
二维图像	h×w×c×n 数值数组，其中 h、w、c 和 n 分别是图像的高度、宽度、通道数和观测值数量。	`"SSCB"`
三维图像	h×w×d×c×n 数值数组，其中 h、w、d、c 和 n 分别是图像的高度、宽度、深度、通道数和图像观测值数量。	`"SSSCB"`
向量序列	c×s×n 矩阵，其中 c 是序列的特征数，s 是序列长度，n 是序列观测值数。	`"CTB"`
二维图像序列	h×w×c×s×n 数组，其中 h、w 和 c 分别对应于图像的高度、宽度和通道数，s 是序列长度，n 是图像序列观测值数。	`"SSCTB"`
三维图像序列	h×w×d×c×s×n 数组，其中 h、w、d 和 c 分别对应于图像的高度、宽度、深度和通道数量，s 是序列长度，n 是图像序列观测值数。	`"SSSCTB"`
特征	c×n 数组，其中 c 是特征数量，n 是观测值数量。	`"CB"`

`v` — 数据向量
双精度或单精度数据类型的数值向量 | 逻辑向量 | `dlarray` 向量对象

数据向量，指定为双精度或单精度数据类型的数值向量、逻辑向量或 dlarray 向量对象。这里，“向量”表示只有一个非单一维度的任何数组。

示例: rand(100,1)

`dim` — 维度标签
单字符

维度标签，指定为 fmt 允许类型的单字符。

示例: "S"

示例: 'S'

输出参量

全部展开

`dlX` — 深度学习数组
`dlarray` 对象

深度学习数组，以 dlarray 对象形式返回。dlX 支持使用 dlgradient 和 dlfeval 进行自动微分。如果您提供 fmt 参量，则 dlX 会有标签。

如果 X 是数值数组或逻辑数组，则 dlX 会包含其数据，这些数据可能会根据 fmt 中的数据格式重新排序。
如果 X 是 gpuArray，则 dlX 中的数据也在 GPU 上。使用 dlX 的后续计算在 GPU 上执行。

用途

使用 dlarray 数据格式，您可以执行下表中的函数，并确保数据具有适当的形状。

函数	运算	验证输入维度	影响输入维度大小
`avgpool`	计算由池大小参数定义的移动矩形（或立方体）空间 (`'S'`) 区域上的输入数据的平均值。	`'S'`	`'S'`
`batchnorm`	对输入数据的每个通道 (`'C'`) 中包含的值进行归一化。	`'C'`
`crossentropy`	计算估计值和目标值之间的交叉熵，按批量 (`'B'`) 维度的大小取平均值。	`'S'`、`'C'`、`'B'`、`'T'`、`'U'`（估计值数组和目标数组的大小必须相同。）	`'S'`、`'C'`、`'B'`、`'T'`、`'U'`（输出是未格式化的标量。）
`dlconv`	使用滤波器数组，匹配输入的空间 (`'S'`) 维度和通道 (`'C'`) 维度（函数）的数量，并添加恒定偏置，来计算输入数据的深度学习卷积。	`'S'`, `'C'`	`'S'`, `'C'`
`dltranspconv`	使用滤波器数组，匹配输入的空间 (`'S'`) 维度和通道 (`'C'`) 维度（的函数）的数量，并添加恒定偏置，来计算输入数据的深度学习转置卷积。	`'S'`, `'C'`	`'S'`, `'C'`
`fullyconnect`	计算输入数据的加权和，并对每个批量 (`'B'`) 维度和时间 (`'T'`) 维度应用偏置。	`'S'`, `'C'`, `'U'`	`'S'`、`'C'`、`'B'`、`'T'`、`'U'`（输出始终采用数据格式 `'CB'`、`'CT'` 或 `'CTB'`。）
`gru`	对输入数据应用门控循环单元计算。	`'S'`, `'C'`, `'T'`	`'C'`
`lstm`	对输入数据应用长短期记忆计算。	`'S'`, `'C'`, `'T'`	`'C'`
`maxpool`	计算由池大小参数定义的移动矩形空间 (`'S'`) 区域上的输入数据的最大值。	`'S'`	`'S'`
`maxunpool`	计算空间 (`'S'`) 维度上的去池化运算。	`'S'`	`'S'`
`mse`	计算估计值和目标值之间的半均方误差，按批量 (`'B'`) 维度的大小取平均值。	`'S'`、`'C'`、`'B'`、`'T'`、`'U'`（估计值数组和目标数组的大小必须相同。）	`'S'`、`'C'`、`'B'`、`'T'`、`'U'`（输出是未格式化的标量。）
`softmax`	对输入数据的每个通道 (`'C'`) 应用 softmax 激活。	`'C'`

这些函数要求每个维度都有一个标签。您可以通过以格式化 dlarray 的形式提供第一个输入，或通过使用函数的 'DataFormat' 名称-值参量，来指定维度标签格式。

dlarray 强制应用 'SCBTU' 的维度标签顺序。这种强制操作消除了运算中的多义性语义，此类语义会隐式匹配输入之间的标签。dlarray 还强制要求维度标签 'C'、'B' 和 'T' 每个最多只能出现一次。使用这些维度标签的函数接受每个标签最多有一个维度。

dlarray 提供的函数可用于获取与 dlarray 相关联的数据格式 (dims)、删除数据格式 (stripdims) 以及获取与特定维度标签相关联的维度 (finddim)。

有关 dlarray 如何处理格式的详细信息，请参阅Notable dlarray Behaviors。

对象函数

`avgpool`	Pool data to average values over spatial dimensions
`batchnorm`	Normalize data across all observations for each channel independently
`crossentropy`	Cross-entropy loss for classification tasks
`indexcrossentropy`	Index cross-entropy loss for classification tasks
`dims`	`dlarray` 对象的数据格式
`dlconv`	Deep learning convolution
`dldivergence`	Divergence of deep learning data
`dlgradient`	Compute gradients for custom training loops using automatic differentiation
`dljacobian`	Jacobian matrix deep learning operation
`dllaplacian`	Laplacian of deep learning data
`dltranspconv`	Deep learning transposed convolution
`extractdata`	从 `dlarray` 中提取数据
`finddim`	Find dimensions with specified label
`fullyconnect`	Sum all weighted input data and apply a bias
`gru`	Gated recurrent unit
`leakyrelu`	Apply leaky rectified linear unit activation
`lstm`	Long short-term memory
`maxpool`	Pool data to maximum value
`maxunpool`	Unpool the output of a maximum pooling operation
`mse`	Half mean squared error
`relu`	应用修正线性单元激活
`sigmoid`	应用 sigmoid 激活
`softmax`	Apply softmax activation to channel dimension
`stripdims`	Remove `dlarray` data format

dlarray 还允许执行数值、矩阵和其他运算的函数。请参阅List of Functions with dlarray Support中的完整列表。

示例

全部折叠

创建未格式化的 `dlarray`

打开实时脚本

从矩阵创建未格式化的 dlarray。

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

dlX = 
  3x5 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

创建格式化的 `dlarray`

打开实时脚本

创建数据格式包含维度标签 'S' 和 'C' 的 dlarray。

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

dlX = 
  3(S) x 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

如果您以相反的顺序指定维度标签，则 dlarray 会隐式地对基础数据进行重新排序。

dlX = dlarray(X,'CS')

dlX = 
  5(S) x 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

创建格式化的 `dlarray` 向量

打开实时脚本

创建第一个维度标签为 'T' 的 dlarray 向量。dlarray 自动创建的第二个维度标签是 'U'。

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

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

    0.5377
    1.8339
   -2.2588
    0.8622
    0.3188
   -1.3077

如果您为 X 指定行向量，则 dlarray 会隐式地将结果重新排序为列向量。

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

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

    0.5377
    1.8339
   -2.2588
    0.8622
    0.3188
   -1.3077

提示

dlgradient 调用必须在函数内部。要获取梯度的数值，您必须使用 dlfeval 计算函数，并且函数的参量必须是 dlarray。请参阅Use Automatic Differentiation In Deep Learning Toolbox。
为了能够正确计算梯度，dlfeval 调用的函数必须仅使用 dlarray 支持的函数。请参阅List of Functions with dlarray Support。

扩展功能

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

有关用法建议和支持 dlarray 代码生成的函数列表，请参阅Code Generation for dlarray (MATLAB Coder)。有关如何使用 dlnetwork 和 dlarray 对象为经过训练的变分自编码器 (VAE) 网络生成 MEX 的示例，请参阅Generate Digit Images Using Variational Autoencoder on Intel CPUs (MATLAB Coder)。

有关 dlarray 代码生成的限制，请参阅dlarray Limitations for Code Generation (MATLAB Coder)。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

用法说明和限制：

有关用法建议和支持 dlarray 代码生成的函数列表，请参阅Code Generation for dlarray (GPU Coder)。有关如何使用 dlnetwork 和 dlarray 对象为经过训练的变分自编码器 (VAE) 网络生成 CUDA^® MEX 的示例，请参阅Generate Digit Images on NVIDIA GPU Using Variational Autoencoder (GPU Coder)。

有关 dlarray 代码生成的限制，请参阅dlarray Limitations for Code Generation (GPU Coder)。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

dlarray 函数完全支持 GPU 数组。要在 GPU 上运行该函数，请将输入数据指定为 gpuArray (Parallel Computing Toolbox)。有关详细信息，请参阅在 GPU 上运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2019b 中推出

全部展开

R2022b: `dlarray` 输入和输出的代码生成行为变化

在 R2022b 中，生成的代码会为入口函数的 dlarray 输入和输出创建结构体。Data 是您可以直接访问的公共字段。

在以前的版本中，生成的代码使用类来表示入口函数的 dlarray 输入和输出。在这些版本中，您需要使用初始化函数 init 来访问 Data 字段。

另请参阅

dlarray

说明

创建对象

语法

描述

输入参量

X — 数据数组 double 或 single 数据类型的数值数组 | logical 数组 | gpuArray 对象 | dlarray 对象

fmt — 数据格式 字符向量 | 字符串标量

v — 数据向量 双精度或单精度数据类型的数值向量 | 逻辑向量 | dlarray 向量对象

dim — 维度标签 单字符

输出参量

dlX — 深度学习数组 dlarray 对象

用途

对象函数

示例

创建未格式化的 dlarray

创建格式化的 dlarray

创建格式化的 dlarray 向量

提示

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

版本历史记录

R2022b: dlarray 输入和输出的代码生成行为变化

另请参阅

主题

WeChat

`X` — 数据数组
`double` 或 `single` 数据类型的数值数组 | `logical` 数组 | `gpuArray` 对象 | `dlarray` 对象

`fmt` — 数据格式
字符向量 | 字符串标量

`v` — 数据向量
双精度或单精度数据类型的数值向量 | 逻辑向量 | `dlarray` 向量对象

`dim` — 维度标签
单字符

`dlX` — 深度学习数组
`dlarray` 对象

创建未格式化的 `dlarray`

创建格式化的 `dlarray`

创建格式化的 `dlarray` 向量

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

R2022b: `dlarray` 输入和输出的代码生成行为变化