2. OpBuilders

2.1. Abs

builder::Op Abs(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的绝对值

(2.1.1)\[Abs(input) = \left|input\right| \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Abs(input);
auto out2 = builder::Abs(input, result_type);

语义详见: Abs

2.2. AbsGrad

builder::Op AbsGrad(builder::Op grad_output,
                    builder::Op input,
                    builder::Type result_type = builder::Type());

总结: 计算以下 Abs 输入 input 的梯度

(2.2.1)\[Abs(input) = \left|input\right| \]
参数:
  • grad_output - Abs 输出的梯度

  • input - Abs 输入

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度,与 input 维度相同、数据类型相同。

示例代码:

auto grad_input1 = builder::AbsGrad(grad_output, input);
auto grad_input2 = builder::AbsGrad(grad_output, input, result_type);

语义详见: semantics-abs_grad

2.3. Acos

builder::Op Acos(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的反余弦

(2.3.1)\[Acos(input)=\frac{1}{cos(input)} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Acos(input);
auto out2 = builder::Acos(input, result_type);

语义详见: Acos

2.4. Add

builder::Op Add(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator+(builder::Op lhs, builder::Op rhs);

总结: 逐元素计算输入 lhsrhs 之和, 并将各个位置的输出元素保存到返回结果中。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator+ 获得相同的效果。

(2.4.1)\[Add(lhs, rhs) = lhs + rhs \]
参数:
  • lhs - 需要相加的左值

  • rhs - 需要相加的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Add(lhs, rhs);
auto out2 = builder::Add(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Add(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs + rhs;

语义详见: Add

2.5. AddGrad

builder::Op AddGrad(builder::Op grad_output,
                    builder::Op lhs,
                    builder::Op rhs,
                    std::vector<int64_t> broadcast_dimensions,
                    std::experimental::optional<float> alpha,
                    builder::Type result_type);

总结: 计算以下 Add 输入的梯度

(2.5.1)\[Add(lhs, rhs, alpha) = lhs + rhs * alpha \]
参数:
  • grad_output - Add 输出的梯度

  • lhs - Add 左输入

  • rhs - Add 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • alpha - (可选)右操作数 rhs 的乘数。默认为1,即 \(Add(lhs, rhs) = lhs + rhs\)

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto out1 = builder::AddGrad(grad_output, lhs, rhs);
auto out2 = builder::AddGrad(grad_output, lhs, rhs, broadcast_dimensions);
auto out3 = builder::AddGrad(grad_output, lhs, rhs, broadcast_dimensions, alpha);
auto out4 = builder::AddGrad(grad_output, lhs, rhs, broadcast_dimensions, alpha, result_type);

语义详见: semantics-add_grad

2.6. And

builder::Op And(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator&&(builder::Op lhs, builder::Op rhs);

总结: 逐元素对输入 lhsrhs 进行逻辑与计算。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator&& 获得相同的效果。

(2.6.1)\[And(lhs, rhs) = lhs \&\& rhs \]
参数:
  • lhs - 左输入 Op,数据类型必须为 pred

  • rhs - 右输入 Op,数据类型必须为 pred

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须为 pred,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::And(lhs, rhs);
auto out2 = builder::And(lhs, rhs, broadcast_dimensions);
auto out3 = builder::And(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs && rhs;

语义详见: And

2.7. ArgMax

builder::Op ArgMax(builder::Op input,
                   int64_t axis = 0,
                   bool keepdim = true,
                   bool select_last_index = false,
                   builder::Type result_type = builder::Type());

总结: 沿参数 axis 计算输入 input 的最大元素的索引。

参数:
  • input - 输入 Op

  • axis - (可选)指定对输入 Op 进行运算的轴, axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • keepdim - (可选)指定是否在输出 Op 中保留减小的维度。如果 keepdimtrue ,则输出 Op 与输入 input 具有相同的维度(减少的维度除外,减少的维度大小变为1),默认值为 false

  • select_last_index - (可选)指定返回值是选择最大元素第一次出现的索引,还是最后一次出现的索引。默认 select_last_indexfalse,即选择最大值第一次出现的索引。

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回最大元素的索引,维度与 keepdim 相关,数据类型为 int64 或者 int32。如果设置 result_type 数据类型为 int32,返回 Op 数据类型为 int32,否则返回 int64。

示例代码:

auto out1 = builder::ArgMax(input, axis, keepdim, select_last_index);
auto out2 = builder::ArgMax(input, axis, keepdim, select_last_index, result_type);

语义详见: ArgMax

2.8. ArgMin

builder::Op ArgMin(builder::Op input,
                   int64_t axis = 0,
                   bool keepdim = true,
                   bool select_last_index = false,
                   builder::Type result_type = builder::Type());

总结: 沿参数 axis 计算输入 input 的最小元素的索引。

参数:
  • input - 输入 Op

  • axis - (可选)指定对输入 Op 进行运算的轴, axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • keepdim - (可选)指定是否在输出 Op 中保留减小的维度。如果 keepdimtrue ,则输出 Op 与输入 input 具有相同的维度(减少的维度除外,减少的维度大小变为1),默认值为 false

  • select_last_index - (可选)指定返回值是选择最小元素第一次出现的索引,还是最后一次出现的索引。默认 select_last_indexfalse,即选择最小值第一次出现的索引。

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回最小元素的索引,维度与 keepdim 相关,数据类型为 int64 或者 int32。如果设置 result_type 数据类型为 int32,返回 Op 数据类型为 int32,否则返回 int64。

示例代码:

auto out1 = builder::ArgMin(input, axis, keepdim, select_last_index);
auto out2 = builder::ArgMin(input, axis, keepdim, select_last_index, result_type);

语义详见: ArgMin

2.9. ArgSort

builder::Op ArgSort(builder::Op input,
                    int64_t axis = 0,
                    bool descending = false,
                    bool only_return_indices = true,
                    bool stable = false,
                    builder::Type result_type = builder::Type());

总结: 对输入 input 沿给定轴 axis 进行排序,输出排序后数据的索引,以及对应的数据。

参数:
  • input - 输入 Op

  • axis - (可选)指定对输入 Op 进行运算的轴, axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • descending - (可选)指定排序的方向。如果设置为 true,算法按照降序排序。如果设置为 false,按升序排序。默认为 false

  • only_return_indices - (可选)指定是否只返回排序后数据的索引。如果设置为 true,则只返回索引。如果设置为 false,则同时返回索引和数据。默认为 true

  • stable - (可选)指定是否使用稳定排序算法。如果设置为 true,则使用稳定排序。如果设置为 false,则使用不稳定排序。默认为 false

  • result_type - (可选)指定返回值的类型

返回值:
  • only_return_indices =  true - 返回排序后的索引 Op,维度与 input 一致,如果设置 result_type 数据类型为 int32,返回 Op 数据类型为 int32,否则返回 int64。

  • only_return_indices = false - 返回 Tuple Op,第一组输出为排序后的数据,维度和数据类型与 input 一致;第二组输出为排序后数据的索引,如果设置 result_type 数据类型为 int32,返回 Op 数据类型为 int32,否则返回 int64。

示例代码:

auto out = builder::ArgSort(input, axis, descending, only_return_indices, stable);

语义详见: semantics-argsort

2.10. ArgSortGrad

builder::Op ArgSortGrad(builder::Op grad_output,
                        builder::Op indices,
                        int64_t axis = 0,
                        bool descending = false,
                        builder::Type result_type = builder::Type());

总结: 计算 ArgSort 输入 input 的梯度, ArgSort 定义如下:

builder::Op ArgSort(builder::Op input,
                    int64_t axis = 0,
                    bool descending = false,
                    bool only_return_indices = true,
                    bool stable = false,
                    builder::Type result_type = builder::Type());
参数:
  • grad_output - ArgSort 输出的梯度

  • indices - ArgSort 输出索引

  • axis - (可选) ArgSort 对输入 input 进行运算的轴, axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • descending - (可选) ArgSort 排序的方向。如果设置为 true,算法按照降序排序。如果设置为 false,按升序排序。默认为 false

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 ArgSort 输入 input 的梯度

示例代码:

auto out = builder::ArgSortGrad(grad_output, indices, axis, descending);

语义详见: semantics-argsort_grad

2.11. Asin

builder::Op Asin(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的反正弦

(2.11.1)\[Asin(input)=\frac{1}{sin(input)} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Asin(input);
auto out2 = builder::Asin(input, result_type);

语义详见: Asin

2.12. Asinh

builder::Op Asinh(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的反双曲正弦

(2.12.1)\[Asinh(input)=\frac{1}{sinh(input)} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Asinh(input);
auto out2 = builder::Asinh(input, result_type);

语义详见: Asinh

2.13. Atan

builder::Op Atan(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的反正切

(2.13.1)\[Atan(input)=\frac{1}{tan(input)} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Atan(input);
auto out2 = builder::Atan(input, result_type);

语义详见: Atan

2.14. AtanGrad

builder::Op AtanGrad(builder::Op grad_output,
                     builder::Op input,
                     builder::Type result_type = builder::Type());

总结: 逐元素计算 Atan 输入 input 的梯度

(2.14.1)\[Atan(input)=\frac{1}{tan(input)}\]
(2.14.2)\[grad\_in=grad\_out * \frac{1}{1+input^{2}}\]
参数:
  • grad_output - Atan 输出的梯度

  • input - Atan 输入

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度,与 input 维度相同、数据类型相同。

示例代码:

auto grad_input1 = builder::AtanGrad(grad_output, input);
auto grad_input2 = builder::AtanGrad(grad_output, input, result_type);

语义详见: semantics-atan_grad

2.15. Atan2

builder::Op Atan2(builder::Op lhs,
                  builder::Op rhs,
                  std::vector<int64_t> broadcast_dimensions = {},
                  builder::Type result_type = builder::Type());

总结:lhs/rhs 进行逐元素的反正切运算

(2.15.1)\[Atan(lhs, rhs)=\frac{1}{tan(\frac{lhs}{rhs})} \]
参数:
  • lhs - 需要相加的左值

  • rhs - 需要相加的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入 input 相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Atan2(lhs, rhs, broadcast_dimensions);

语义详见: Atan2

2.16. Atanh

builder::Op Atanh(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的反双曲值

(2.16.1)\[Atanh(input)=\frac{1}{tanh(input)} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Atanh(input);
auto out2 = builder::Atanh(input, result_type);

语义详见: Atanh

2.17. AveragePool

builder::Op AveragePool(builder::Op input,
                        std::vector<int64_t> axes,
                        std::vector<int64_t> kernel_shape,
                        bool ceil_mode = false,
                        bool count_include_pad = false,
                        std::vector<int64_t> strides = {},
                        std::vector<int64_t> padding = {},
                        const char* auto_pad = nullptr,
                        builder::Type result_type = builder::Type());

builder::Op AveragePool(builder::Op input,
                        std::vector<int64_t> axes,
                        std::vector<int64_t> kernel_shape,
                        bool ceil_mode = false,
                        bool count_include_pad = false,
                        std::vector<int64_t> strides = {},
                        std::vector<std::vector<int64_t>> padding = {{}},
                        const char* auto_pad = nullptr,
                        builder::Type result_type = builder::Type());

总结: 在输入 input 上应用平均池化操作,支持 1-D,2-D, 3-D 池化。

参数:
  • input - 输入 Op

  • axes - 输入进行池化操作的轴

  • kernel_shape - 池化核大小。

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • cound_include_pad - 计算边缘值时是否包括填充像素。默认为 false,不包括 pad。

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

std::vector<float> value = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16};
builder::Type in_type({1, 1, 4, 4}, builder::PrimitiveType::F32());
auto input = builder::Const(builder, static_cast<void *>(value.data()), in_type);
// 2-D average pool
auto out1 = builder::AveragePool(input,
                                 {2, 3} /*axes*/,
                                 {3, 3} /*kernel_shape*/,
                                 true /*ceil_mode*/,
                                 false /*count_include_pad*/,
                                 {2, 2} /*strides*/,
                                 {0, 1, 0, 1} /*padding*/,
                                 nullptr /*auto_pad*/);
auto out2 = builder::AveragePool(input,
                                 {2, 3} /*axes*/,
                                 {3, 3} /*kernel_shape*/,
                                 true /*ceil_mode*/,
                                 false /*count_include_pad*/,
                                 {2, 2} /*strides*/,
                                 {{0, 1}, {0, 1}} /*padding*/,
                                 nullptr /*auto_pad*/);

语义详见: AveragePool

2.18. AveragePoolGrad

builder::Op AveragePoolGrad(builder::Op grad_output,
                            std::vector<int64_t> axes,
                            std::vector<int64_t> grad_size,
                            std::vector<int64_t> kernel_shape,
                            std::vector<int64_t> strides = {},
                            bool ceil_mode = false,
                            bool count_include_pad = false,
                            std::vector<int64_t> padding = {},
                            builder::Type result_type = builder::Type());

builder::Op AveragePoolGrad(builder::Op grad_output,
                            std::vector<int64_t> axes,
                            std::vector<int64_t> grad_size,
                            std::vector<int64_t> kernel_shape,
                            std::vector<int64_t> strides = {},
                            bool ceil_mode = false,
                            bool count_include_pad = false,
                            std::vector<std::vector<int64_t>> padding = {{}},
                            builder::Type result_type = builder::Type());

总结: 计算 AveragePool 输入 input 的梯度。

参数:
  • grad_output - AveragePool 输出的梯度

  • axes - 输入进行池化操作的轴

  • grad_size - AveragePool 输入的维度 shape 信息

  • kernel_shape - 池化核大小

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • cound_include_pad - 计算边缘值时是否包括填充像素。默认为 false,不包括 pad。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

std::vector<float> value = {1.0, 2.0};
builder::Type grad_out_type({1, 1, 2, 1}, builder::PrimitiveType::F32());
auto grad_output = builder::Const(builder, static_cast<void *>(value.data()), grad_out_type);
// 2-D average pool grad
auto out1 = builder::AveragePoolGrad(grad_output,
                                     {1, 2} /*axes*/,
                                     {1, 3, 5, 1} /*grad_size*/,
                                     {2, 2} /*kernel_shape*/,
                                     {2, 2} /*strides*/,
                                     false /*ceil_mode*/,
                                     false /*count_include_pad*/,
                                     {0, 0, 0, 0} /*padding*/);
auto out2 = builder::AveragePoolGrad(grad_output,
                                     {1, 2} /*axes*/,
                                     {1, 3, 5, 1} /*grad_size*/,
                                     {2, 2} /*kernel_shape*/,
                                     {2, 2} /*strides*/,
                                     false /*ceil_mode*/,
                                     false /*count_include_pad*/,
                                     {{0, 0}, {0, 0}} /*padding*/);

语义详见: semantics-average_pool_grad

2.19. BatchNormGrad

builder::Op BatchNormGrad(builder::Op input,
                          builder::Op scale,
                          builder::Op saved_mean,
                          builder::Op saved_variance,
                          builder::Op grad_output,
                          float epsilon,
                          int64_t feature_index,
                          builder::Type result_type = builder::Type());

总结: 计算 BatchNorm 输入 input 的梯度

参数:
  • input - 输入 Op

  • scale - 应用于 BatchNorm 输出,维度大小为 [C]C 为 channel 大小

  • saved_mean - BatchNorm 的输出,当前 batch 的均值

  • saved_variance - BatchNorm 的输出,当前 batch 的方差

  • grad_output - BatchNorm 归一化输出的梯度

  • epsilon - 为了数值稳定加在分母上的值

  • feature_index - 指定输入 input 的 feature 维度

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度

示例代码:

std::vector<float> in_data             = {0.422912f, 0.359912f, 0.272663f, 0.618909f,
                                          0.091751f, 0.041123f, 0.065497f, 0.408299f};
std::vector<float> scale_data          = {1.0f, 2.0f};
std::vector<float> saved_mean_data     = {0.213205f, 0.357060f};
std::vector<float> saved_variance_data = {0.028027f, 0.057004f};
std::vector<float> grad_out_data       = {0.125f, 0.321f, 0.242f, 0.184f,
                                          0.495f, 0.618f, 0.258f, 0.314f};

auto builder = std::make_shared<builder::Builder>();
builder->SetShapeInference(true);

auto input             = builder::Const(builder, static_cast<void*>(in_data.data()),
                                     builder::Type({1, 2, 2, 2}, builder::PrimitiveType::F32()));
auto scale          = builder::Const(builder, static_cast<void*>(scale_data.data()),
                                     builder::Type({2}, builder::PrimitiveType::F32()));
auto saved_mean     = builder::Const(builder, static_cast<void*>(saved_mean_data.data()),
                                     builder::Type({2}, builder::PrimitiveType::F32()));
auto saved_variance = builder::Const(builder, static_cast<void*>(saved_variance_data.data()),
                                     builder::Type({2}, builder::PrimitiveType::F32()));
auto grad_output       = builder::Const(builder, static_cast<void*>(grad_out_data.data()),
                                     builder::Type({2}, builder::PrimitiveType::F32()));

auto grad_input = builder::BatchNormGrad(input, scale, saved_mean, saved_variance, grad_output, 0.001f, 2);

语义详见: BatchNormGrad

2.20. BatchNormInference

builder::Op BatchNormInference(builder::Op input,
                               builder::Op scale,
                               builder::Op bias,
                               builder::Op mean,
                               builder::Op variance,
                               float epsilon,
                               int64_t feature_index,
                               builder::Type result_type = builder::Type());

总结: 用于推理或者训练 eval 阶段,计算输入 input 的 BatchNorm 归一化。对于特征维度中的每个特征,该操作计算所有其他维度的均值和方差,并使用均值和方差对输入张量中的每个元素进行归一化。

BatchNormInference 相当于调用 BatchNormTraining,而不计算每个 batch 的均值和方差,而是使用输入均值和方差作为估计值,目的是减少推理延迟,因此称为 BatchNormInference。

参数:
  • input - 输入 Op

  • scale - 应用于 BatchNorm 输出,维度大小为 [C]C 为 channel 大小

  • bias - 应用于 BatchNorm 输出,维度大小为 [C]C 为 channel 大小

  • mean - BatchNorm 的输出,当前 batch 的均值

  • variance - BatchNorm 的输出,当前 batch 的方差

  • epsilon - 为了数值稳定加在分母上的值

  • feature_index - 指定输入 input 的 feature 维度

  • result_type - (可选)指定输出的类型

返回值:
  • BatchNorm 归一化输出

示例代码:

std::vector<float> in_data       = {0.42291,   0.359912,  0.272663,  0.618909,
                                    0.106967,  0.602868,  0.040745,  0.576843,
                                    0.756074,  0.363923,  0.883733,  0.693509,
                                    0.0917556, 0.0411234, 0.0654977, 0.408299};
std::vector<float> scale_data    = {1.0f, 1.0f, 1.0f, 1.0f};
std::vector<float> bias_data     = {1.0f, 1.0f, 1.0f, 1.0f};
std::vector<float> mean_data     = {0.34442666, 0.34195662, 0.31565964, 0.57439};
std::vector<float> variance_data = {0.07396074, 0.03984508, 0.11567877, 0.01094088};

auto builder = std::make_shared<builder::Builder>();
builder->SetShapeInference(true);

auto input       = builder::Const(builder, static_cast<void*>(in_data.data()),
                               builder::Type({1, 2, 2, 4}, builder::PrimitiveType::F32()));
auto scale    = builder::Const(builder, static_cast<void*>(scale_data.data()),
                               builder::Type({4}, builder::PrimitiveType::F32()));
auto mean     = builder::Const(builder, static_cast<void*>(mean_data.data()),
                               builder::Type({4}, builder::PrimitiveType::F32()));
auto variance = builder::Const(builder, static_cast<void*>(variance_data.data()),
                               builder::Type({4}, builder::PrimitiveType::F32()));

auto out      = builder::BatchNormInference(input, scale, bias, mean, variance, 0.001f, 3);

语义详见: BatchNormInference

2.21. BatchNormTraining

builder::Op BatchNormTraining(builder::Op input,
                              builder::Op scale,
                              builder::Op bias,
                              float epsilon,
                              int64_t feature_index,
                              builder::Type result_type = builder::Type());

总结: 训练阶段计算输入 input 的 BatchNorm 归一化,对每个特征的空间和批量维度上的操作数进行归一化。 BatchNormTraining 计算每个批次的均值和方差。

(2.21.1)\[saved\_mean = ReduceMean(input, axis=feature\_index)\]
(2.21.2)\[saved\_var = ReduceVar(input, axis=feature\_index)\]
(2.21.3)\[BatchNormTraining(input, scale, bias)=\frac{input - saved\_mean}{\sqrt{saved\_var + epsilon}} * scale + bias\]
参数:
  • input - 输入 Op

  • scale - 应用于 BatchNorm 输出,维度大小为 [C]C 为 channel 大小

  • bias - 应用于 BatchNorm 输出,维度大小为 [C]C 为 channel 大小

  • epsilon - 为了数值稳定加在分母上的值

  • feature_index - 指定输入 input 的 feature 维度

  • result_type - (可选)指定输出的类型

返回值:
  • 返回 Tuple Op,包含 BatchNorm 归一化输出, saved_mean, saved_variance

示例代码:

std::vector<float> in_data    = {0.42291,   0.359912,  0.272663,  0.618909,
                                 0.106967,  0.602868,  0.040745,  0.576843,
                                 0.756074,  0.363923,  0.883733,  0.693509,
                                 0.0917556, 0.0411234, 0.0654977, 0.408299};
std::vector<float> scale_data = {2.0f, 3.0f};
std::vector<float> bias_data  = {0.022f, 0.014f};

auto builder = std::make_shared<builder::Builder>();
builder->SetShapeInference(true);

auto input    = builder::Const(builder, static_cast<void*>(in_data.data()),
                            builder::Type({1, 2, 2, 4}, builder::PrimitiveType::F32()));
auto scale = builder::Const(builder, static_cast<void*>(scale_data.data()),
                            builder::Type({2}, builder::PrimitiveType::F32()));
auto bias  = builder::Const(builder, static_cast<void*>(bias_data.data()),
                            builder::Type({2}, builder::PrimitiveType::F32()));

auto out   = builder::BatchNormTraining(input, scale, bias, 0.001f, 3);

语义详见: BatchNormTraining

2.22. BCELoss

builder::Op BCELoss(std::vector<builder::Op> ins,
                    const char* reduction = nullptr,
                    builder::Type result_type = builder::Type());

总结: 计算目标值和预测值之间的二值交叉熵损失值

  • 未做 reduction 之前,输出 Out 计算公式如下:

(2.22.1)\[Out=\left\{\begin{matrix} -1 * weight * [label * log(input) + (1 - label) * log(1 - input)], & ins 包含 weight \\ -1 * [label * log(input) + (1 - label) * log(1 - input)], & ins 不包含 weight \\ \end{matrix}\right.\]
  • 根据 reduction 的设置,最终 Out 计算如下:

(2.22.2)\[Out=\left\{\begin{matrix} Out, & reduction = nullptr \\ mean(Out), & reduction = mean \\ sum(Out), & reduction = sum \\ \end{matrix}\right.\]
参数:
  • ins - 输入 input,目标 target,以及可选的 weight

  • reduction - 指定应用于输出结果的计算方式,可选值有:none, mean, sum。默认为 none。设置为 mean 时,计算 BCELoss 的均值;设置为 sum 时,计算 BCELoss 的总和;设置为 none 时,则返回 bce_loss。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

std::vector<builder::Op> ins = {input, target, weight};
auto out   = builder::BCELoss(ins, "mean");

语义详见: BCELoss

2.23. Bitcast

builder::Op Bitcast(builder::Op input, builder::Type result_type);

总结: 定义参考 TensorFlow,但实际语义为 Reshape,目前已经废弃,只做后向兼容。

[Deprecated API]: 已废弃,推荐使用 Reshape

参数:
  • input - 输入 Op

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Bitcast(input, result_type);

语义详见: semantics-bitcast

2.24. BitcastConvert

builder::Op BitcastConvert(builder::Op input, builder::Type result_type);

总结: 执行从指定维度形状到目标维度形状的逐元素位转换操作。

参数:
  • input - 输入 Op

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

std::vector<float> in_value_1 = {1.1f, 2.2f, 3.3f, 4.4f, 5.5f, 6.6f, 7.7f, 8.8f};
std::vector<int8_t> in_value_2 = {1, 2, 3, 4, 5, 6, 7, 8};
auto in_1 = builder::Const(builder, static_cast<void*>(in_value_1.data()),
                         builder::Type({8}, builder::PrimitiveType::F32()));
auto in_2 = builder::Const(builder, static_cast<void*>(in_value_2.data()),
                         builder::Type({2, 4}, builder::PrimitiveType::S8()));

auto out1 = builder::BitcastConvert(in_1, builder::Type({8}, builder::PrimitiveType::S32()));
auto out2 = builder::BitcastConvert(in_1, builder::Type({8, 4}, builder::PrimitiveType::S8()));
auto out3 = builder::BitcastConvert(in_2, builder::Type({2}, builder::PrimitiveType::S8()));

语义详见: BitcastConvert

2.25. Broadcast

builder::Op Broadcast(builder::Op input,
                      std::vector<int64_t> broadcast_sizes,
                      builder::Type result_type = builder::Type());

总结: 通过在输入 input 的维度前添加 broadcast_sizes,将 input 广播到更高维度

[Deprecated]: 已废弃,推荐使用 BroadcastInDim

参数:
  • input - 输入 Op

  • broadcast_sizes - 新添加的 dims 信息

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

std::vector<float> in_value = {2.0f};
auto input = builder::Const(builder, static_cast<void*>(in_value.data()),
                         builder::Type(builder::PrimitiveType::F32()));

auto out = builder::Broadcast(input, builder::Type({2, 3}, builder::PrimitiveType::S32()));

语义详见: Broadcast

2.26. BroadcastInDim

builder::Op BroadcastInDim(builder::Op input,
                           std::vector<int64_t> broadcast_dimensions,
                           builder::Type result_type);

总结: 通过复制输入 input 的数据来扩展 input 的维度大小和 Rank。

参数:
  • input - 输入 Op

  • broadcast_dimensions - 指定需要被广播的维度,语义参考 XLA 的规则。

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

std::vector<float> in_value = {1.1f, 2.2f, 3.3f, 4.4f, 5.5f, 6.6f};
auto input = builder::Const(builder, static_cast<void*>(in_value.data()),
                         builder::Type({2, 3}, builder::PrimitiveType::F32()));

auto out = builder::BroadcastInDim(input, {0, 1},
                                   builder::Type({2, 3, 4}, builder::PrimitiveType::F32()));

语义详见: BroadcastInDim

2.27. Cbrt

builder::Op Cbrt(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的立方根

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Cbrt(input, result_type);

语义详见: Cbrt

2.28. Ceil

builder::Op Ceil(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素对输入 input 进行向上取整运算

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Ceil(input, result_type);

语义详见: Ceil

2.29. Cholesky

builder::Op Cholesky(builder::Op input,
                     bool lower = false,
                     builder::Type result_type = builder::Type());

总结: 计算对称正定矩阵或一批对称正定矩阵的 Cholesky 分解。

如果 lowertrue,则返回的矩阵 L 为下三角矩阵,分解形式为:

(2.29.1)\[A=U^{T}U\]

如果 lowerfalse,则返回的矩阵 U 为上三角矩阵,分解形式为:

(2.29.2)\[A=LL^{T}\]
参数:
  • input - 输入 Op

  • lower - 是否返回上三角矩阵还是下三角矩阵的标志。默认为 false,即返回下三角矩阵。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,维度和数据类型与输入 input 相同

示例代码:

auto out = builder::Cholesky(input, result_type);

语义详见: Cholesky

2.30. Clamp

builder::Op Clamp(builder::Op min,
                  builder::Op input,
                  builder::Op max,
                  builder::Type result_type = builder::Type());

总结: 将输入 input 的所有元素进行裁剪,使得输出元素限制在 [min, max] 内。

(2.30.1)\[Out = MIN(MAX(input, min), max)\]
参数:
  • input - 输入 Op

  • min - 裁剪的最小值,维度只支持 scalar 标量类型或与输入 input 一致。

  • max - 裁剪的最大值,维度只支持 scalar 标量类型或与输入 input 一致。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,维度和数据类型与输入 input 相同

示例代码:

auto out = builder::Clamp(min, input, max, result_type);

语义详见: Clamp

2.31. ClampGrad

builder::Op ClampGrad(builder::Op grad_output,
                      builder::Op input,
                      builder::Op min,
                      builder::Op max,
                      builder::Type result_type = builder::Type());

总结: 计算以下 Clamp 输入 input 的梯度

(2.31.1)\[Out = MIN(MAX(input, min), max)\]
(2.31.2)\[grad\_in = (input > min \&\& input < max) ? grad\_out : 0\]
参数:
  • grad_output - Clamp 输出的梯度

  • input - Clamp 输入

  • min - Clamp 裁剪的最小值

  • max - Clamp 裁剪的最大值

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度,与 input 维度相同、数据类型相同。

示例代码:

auto grad_input = builder::ClampGrad(grad_output, input, min, max);

语义详见: semantics-clamp_grad

2.32. Compare

builder::Op Compare(builder::Op lhs,
                    builder::Op rhs,
                    const char* comparison_direction,
                    std::vector<int64_t> broadcast_dimensions = {},
                    builder::Type result_type = builder::Type());

总结: 逐元素二元比较操作,比较浮点数类型时使用标准 IEEE 754 浮点比较语义。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的左值

  • comparison_direction - 比较的操作类型:支持 EQ, NE, GE, GT, LE, LT 这六种。

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定输出的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred,维度为 lhsrhs 广播后的形状。

示例代码:

auto out = builder::Compare(lhs, rhs, "EQ", broadcast_dimensions);

语义详见: Compare

2.33. Complex

builder::Op Complex(builder::Op lhs,
                    builder::Op rhs,
                    builder::Type result_type = builder::Type());

总结: 从一对实值 lhs 和虚值 rhs 执行到复数值的逐元素转换。

参数:
  • lhs - 实值

  • rhs - 虚值

  • result_type - (可选)指定输出的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致

返回值:
  • 输出 Op,数据类型为 complex

示例代码:

// lhs: [1.0, 3.0]
// rhs: [2.0, 4.0]
auto out = builder::Complex(lhs, rhs);
// out: [(1.0, 2.0), (3.0, 4.0)]

语义详见: Complex

2.34. ConcatGrad

builder::Op ConcatGrad(builder::Op grad_output,
                       std::vector<builder::Op> ins,
                       int64_t axis,
                       builder::Type result_type = builder::Type());

总结: 计算 Concatenate 输入 ins 的梯度

参数:
  • grad_output - Concatenate 输出的梯度

  • ins - Concatenate 所有输入

  • axis - Concatenate 对所有输入 ins 进行运算的轴, axis 的有效范围是 [-R, R),R 是每个输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

限制:
  • 所有输入 ins 对应的 Rank 必须完全相等

返回值:
  • 输出 Tuple Op

示例代码:

auto grad_input = builder::ConcatGrad(grad_output, ins, axis);

语义详见: semantics-concat_grad

2.35. Concatenate

builder::Op Concatenate(std::vector<builder::Op> ins,
                        int64_t axis,
                        builder::Type result_type = builder::Type());

总结: 对所有输入 ins ,沿参数 axis 指定的轴进行拼接操作

参数:
  • ins - 待拼接的所有输入

  • axis - 指定对输入 ins 进行运算的轴, axis 的有效范围是 [-R, R),R 是每个输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

限制:
  • 所有输入 ins 对应的 Rank 必须完全相等

返回值:
  • 输出 Op,数据类型与输入相同

示例代码:

auto out = builder::Concatenate(ins, axis);

语义详见: Concatenate

2.36. Const

// 1. 通用接口,以下其他 Const 接口最终都会调用这个接口
builder::Op Const(std::shared_ptr<builder::Builder> builder,
                  void* value, builder::Type result_type);

// 2. Empty Tensor Op,用于不具体包含值信息,只做占位符的 Op,
//    或训练场景传递输入 shape 信息 (result_type shape类似为 {0, dim1, dim2, ...})
builder::Op Const(std::shared_ptr<builder::Builder> builder,
                  std::nullptr_t, builder::Type result_type);

// 3. 模板接口,不需要使用者手动对 value 指针进行 static_cast<void*> 强转
template <typename T>
builder::Op Const(std::shared_ptr<builder::Builder> builder,
                  T* value, builder::Type result_type);

// 4. 模板接口,直接传值 value
template <typename T>
builder::Op Const(std::shared_ptr<builder::Builder> builder,
                  T value, builder::Type result_type);

// 5. 模板接口,直接传 vector<T>
template <typename T>
builder::Op Const(std::shared_ptr<builder::Builder> builder,
                  std::vector<T>& values, builder::Type result_type);

总结: 构造常量 Op。

参数:
  • builder - 全局 builder::Builder 对象共享指针

  • value - 常量数值,支持 void* 指针, T 传值, T* 传指针, vector<T> 容器传值

  • result_type - 指定常量输出的类型

返回值:
  • 输出 Op

示例代码:

auto out1 = builder::Const(builder, 1.0, builder::Type(builder::PrimitiveType::S32()));
auto out2 = builder::Const(builder, 1.0, builder::Type(builder::PrimitiveType::F32()));

语义详见: Concatenate

2.37. Conv

builder::Op Conv(builder::Op lhs,
                 builder::Op rhs,
                 builder::ConvDimensionNumbers dimension_numbers,
                 std::vector<int64_t> window_strides = {},
                 std::vector<int64_t> padding = {},
                 std::vector<int64_t> lhs_dilation = {},
                 std::vector<int64_t> rhs_dilation = {},
                 std::vector<int64_t> window_reversal = {},
                 const char* auto_pad = nullptr,
                 int64_t feature_group_count = 1,
                 int64_t batch_group_count = 1,
                 std::vector<const char*> precision_config = {},
                 builder::Type result_type = builder::Type());

builder::Op Conv(builder::Op lhs,
                 builder::Op rhs,
                 builder::ConvDimensionNumbers dimension_numbers,
                 std::vector<int64_t> window_strides = {},
                 std::vector<std::vector<int64_t>> padding = {{}},
                 std::vector<int64_t> lhs_dilation = {},
                 std::vector<int64_t> rhs_dilation = {},
                 std::vector<int64_t> window_reversal = {},
                 const char* auto_pad = nullptr,
                 int64_t feature_group_count = 1,
                 int64_t batch_group_count = 1,
                 std::vector<const char*> precision_config = {},
                 builder::Type result_type = builder::Type());

总结: 计算神经网络中使用的各种卷积。

参数:
  • lhs - 输入 Op

  • rhs - 权重 Op

  • dimension_numbers - 对输入 lhsrhs, 以及输出的维度信息( batch_dim, feature_dim, spatial_dims)进行设置

  • window_strides - 卷积核移动的步长,默认值为 {},即步长为1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]。默认为 {}{{}},即不填充任何数值。

  • lhs_dilation - 指定应用于输入 lhs 的膨胀因子,默认值为 {},即膨胀因子为1。

  • rhs_dilation - 指定应用于输入 rhs 的膨胀因子,默认值为 {},即膨胀因子为1。

  • window_reversal - 未使用,保留默认值 {}

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • feature_group_count - 特征组的数量,默认为1。用于支持 group convolution 或者 depthwise convolution。

  • batch_group_count - 默认为1,可用于反向传播时的 grouped filters。

  • precision_config - 未使用,保留默认值 {}

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

// input: [N, Ci, H, W]
// weight: [Co, Ci, R, S]
// dimension_numbers:
//   input_batch_dimension = 0, input_feature_dimension = 1, input_spatial_dimensions = {2, 3}
//   kernel_input_feature_dimension = 1, kernel_output_feature_dimension = 0
//   kernel_spatial_dimensions = {2, 3}
//   output_batch_dimension = 0, output_feature_dimension = 1, output_spatial_dimensions = {2, 3}
auto out = builder::Conv(input,                 // builder::Op lhs
                         weight,             // builder::Op rhs
                         dimension_numbers,  // builder::ConvDimensionNumbers
                         {1, 1},             // window_strides
                         {0, 0},             // padding
                         {1, 1},             // lhs_dilation
                         {1, 1},             // rhs_dilation
                         {},                 // window_reversal
                         nullptr,            // auto_pad
                         1,                  // feature_group_count
                         1,                  // batch_group_count
                         {}                  // precision_config
                         );

语义详见: Conv

2.38. ConvBias

builder::Op ConvBias(std::vector<builder::Op> ins,
                     builder::ConvDimensionNumbers dimension_numbers,
                     int64_t feature_group_count,
                     int64_t batch_group_count,
                     std::vector<int64_t> window_strides = {},
                     std::vector<int64_t> padding = {},
                     std::vector<int64_t> lhs_dilation = {},
                     std::vector<int64_t> rhs_dilation = {},
                     std::vector<int64_t> window_reversal = {},
                     const char* auto_pad = nullptr,
                     std::vector<const char*> precision_config = {},
                     builder::Type result_type = builder::Type());

builder::Op ConvBias(std::vector<builder::Op> ins,
                     builder::ConvDimensionNumbers dimension_numbers,
                     int64_t feature_group_count,
                     int64_t batch_group_count,
                     std::vector<int64_t> window_strides = {},
                     std::vector<std::vector<int64_t>> padding = {{}},
                     std::vector<int64_t> lhs_dilation = {},
                     std::vector<int64_t> rhs_dilation = {},
                     std::vector<int64_t> window_reversal = {},
                     const char* auto_pad = nullptr,
                     std::vector<const char*> precision_config = {},
                     builder::Type result_type = builder::Type());

[Deprecated API]: HLIR 图优化 Op,只在 HLIR Pass 内部使用,符合 ConvBias 场景的 Conv + Add 会在 HLIR Pass 中被优化为 ConvBias

总结:Conv 一样计算神经网络中使用的各种卷积,区别是指定了偏置 bias ,作用于 Conv 的输出。

参数:
  • ins - Conv 的输入 lhsrhs,以及偏置 bias

  • dimension_numbers - 对输入 lhsrhs, 以及输出的维度信息( batch_dim, feature_dim, spatial_dims)进行设置

  • window_strides - 卷积核移动的步长,默认值为 {},即步长为1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]。默认为 {}{{}},即不填充任何数值。

  • lhs_dilation - 指定应用于输入 lhs 的膨胀因子,默认值为 {},即膨胀因子为1。

  • rhs_dilation - 指定应用于输入 rhs 的膨胀因子,默认值为 {},即膨胀因子为1。

  • window_reversal - 未使用,保留默认值 {}

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • feature_group_count - 特征组的数量,默认为1。用于支持 group convolution 或者 depthwise convolution。

  • batch_group_count - 默认为1,可用于反向传播时的 grouped filters。

  • precision_config - 未使用,保留默认值 {}

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

// input: [N, Ci, H, W]
// weight: [Co, Ci, R, S]
// bias: [Co]
// ins: {input, weight, bias}
// dimension_numbers:
//   input_batch_dimension = 0, input_feature_dimension = 1, input_spatial_dimensions = {2, 3}
//   kernel_input_feature_dimension = 1, kernel_output_feature_dimension = 0
//   kernel_spatial_dimensions = {2, 3}
//   output_batch_dimension = 0, output_feature_dimension = 1, output_spatial_dimensions = {2, 3}

auto out = builder::ConvBias(ins,                // builder::Op lhs, rhs, bias
                             dimension_numbers,  // builder::ConvDimensionNumbers
                             1,                  // feature_group_count
                             1,                  // batch_group_count
                             {1, 1},             // window_strides
                             {0, 0},             // padding
                             {1, 1},             // lhs_dilation
                             {1, 1},             // rhs_dilation
                             {},                 // window_reversal
                             nullptr,            // auto_pad
                             {}                  // precision_config
                             );

语义详见: ConvBias

2.39. Conv1D

builder::Op Conv1D(std::vector<builder::Op> ins,
                   int64_t group = 1,
                   const char* auto_pad = nullptr,
                   const char* layout = nullptr,
                   std::vector<int64_t> stride = {},
                   std::vector<int64_t> padding = {},
                   std::vector<int64_t> dilation = {},
                   builder::Type result_type = builder::Type());

[Experimental API]: 实验性API,接口不稳定,可能会被删除或更改。

总结: 对输入 ins 计算一维卷积。

参数:
  • ins - 一维卷积的输入 lhsrhs,以及可选的偏置 bias

  • group - (可选)一维卷积核的分组数。

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • layout - (可选)- 指定输入的数据格式,支持 NCL 和 NLC,默认值为 nullptr,代表 NLC。

  • stride - 卷积核移动的步长,默认值为 {},即步长为 1。

  • padding - 池化填充,格式为 [begin, end],。默认为 {},即不填充任何数值。

  • dilation - 指定应用于卷积核的膨胀因子,默认值为 {},即膨胀因子为 1。

  • result_type - (可选)指定输出的类型

返回值:
  • 卷积输出 Op,数据格式和 layout 与输入一致

示例代码:

auto out = builder::Conv1D(ins,                // builder::Op input, weight, bias
                           1,                  // group
                           nullptr,            // auto_pad
                           nullptr,            // layout, default NLC
                           {1},                // stride
                           {0},                // padding
                           {1},                // dilation
                           );

语义详见: semantics-conv1d

2.40. Conv1DTranspose

builder::Op Conv1DTranspose(std::vector<builder::Op> ins,
                            int64_t group = 1,
                            const char* auto_pad = nullptr,
                            const char* layout = nullptr,
                            std::vector<int64_t> stride = {},
                            std::vector<int64_t> padding = {},
                            std::vector<int64_t> output_padding = {},
                            std::vector<int64_t> dilation = {},
                            std::vector<int64_t> output_shape = {},
                            builder::Type result_type = builder::Type());

[Experimental API]: 实验性API,接口不稳定,可能会被删除或更改。

总结: 对输入 ins 计算一维转置卷积。

参数:
  • ins - 转置卷积的输入 lhsrhs,以及可选的偏置 bias

  • group - (可选)一维卷积核的分组数。

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • layout - (可选)- 指定输入的数据格式,支持 NCL 和 NLC,默认值为 nullptr,代表 NLC。

  • stride - 卷积核移动的步长,默认值为 {},即步长为 1。

  • padding - 池化填充,格式为 [begin, end],。默认为 {},即不填充任何数值。

  • dilation - 指定应用于卷积核的膨胀因子,默认值为 {},即膨胀因子为 1。

  • result_type - (可选)指定输出的类型

返回值:
  • 转置卷积输出 Op,数据格式和 layout 与输入一致

示例代码:

auto out = builder::Conv1DTranspose(ins,      // builder::Op input, weight, bias
                                    1,        // group
                                    nullptr,  // auto_pad
                                    nullptr,  // layout, default NLC
                                    {1},      // stride
                                    {0},      // padding
                                    {1},      // dilation
                                    );

语义详见: semantics-conv1d_transpose

2.41. Conv2D

builder::Op Conv2D(std::vector<builder::Op> ins,
                   int64_t group = 1,
                   const char* auto_pad = nullptr,
                   const char* layout = nullptr,
                   std::vector<int64_t> stride = {},
                   std::vector<int64_t> padding = {},
                   std::vector<int64_t> dilation = {},
                   builder::Type result_type = builder::Type());

[Experimental API]: 实验性API,接口不稳定,可能会被删除或更改。

总结: 对输入 ins 计算二维卷积。

参数:
  • ins - 二维卷积的输入 lhsrhs,以及可选的偏置 bias

  • group - (可选)二维卷积核的分组数。

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • layout - (可选)- 指定输入的数据格式,支持 NCHW 和 NHWC ,默认值为 nullptr,代表 NHWC 。

  • stride - 卷积核移动的步长,默认值为 {},即步长为 1。

  • padding - 池化填充,格式为 [begin, end],。默认为 {},即不填充任何数值。

  • dilation - 指定应用于卷积核的膨胀因子,默认值为 {},即膨胀因子为 1。

  • result_type - (可选)指定输出的类型

返回值:
  • 卷积输出 Op,数据格式和 layout 与输入一致

示例代码:

auto out = builder::Conv2D(ins,                // builder::Op input, weight, bias
                           1,                  // group
                           nullptr,            // auto_pad
                           nullptr,            // layout, default NLC
                           {1},                // stride
                           {0},                // padding
                           {1},                // dilation
                           );

语义详见: semantics-conv2d

2.42. Conv2DTranspose

builder::Op Conv2DTranspose(std::vector<builder::Op> input,
                            int64_t group = 1,
                            const char* auto_pad = nullptr,
                            const char* layout = nullptr,
                            std::vector<int64_t> stride = {},
                            std::vector<int64_t> padding = {},
                            std::vector<int64_t> output_padding = {},
                            std::vector<int64_t> dilation = {},
                            std::vector<int64_t> output_shape = {},
                            builder::Type result_type = builder::Type());

[Experimental API]: 实验性API,接口不稳定,可能会被删除或更改。

总结: 对输入 ins 计算二维转置卷积。

参数:
  • ins - 转置卷积的输入 lhsrhs,以及可选的偏置 bias

  • group - (可选)一维卷积核的分组数。

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 nullptr,代表 NOTSET,即使用显式填充参数 padding

  • layout - (可选)- 指定输入的数据格式,支持 NCL 和 NLC,默认值为 nullptr,代表 NLC。

  • stride - 卷积核移动的步长,默认值为 {},即步长为 1。

  • padding - 池化填充,格式为 [begin, end],。默认为 {},即不填充任何数值。

  • dilation - 指定应用于卷积核的膨胀因子,默认值为 {},即膨胀因子为 1。

  • result_type - (可选)指定输出的类型

返回值:
  • 转置卷积输出 Op,数据格式和 layout 与输入一致

示例代码:

auto out = builder::Conv2DTranspose(ins,      // builder::Op input, weight, bias
                                    1,        // group
                                    nullptr,  // auto_pad
                                    nullptr,  // layout, default NLC
                                    {1},      // stride
                                    {0},      // padding
                                    {1},      // dilation
                                    );

语义详见: semantics-conv2d_transpose

2.43. Convert

builder::Op Convert(builder::Op input, builder::Type result_type);

总结: 与 C++ 中的逐元素 static_cast 类似,将 input 的数据类型转换为 result_type 对应的数据类型。支持输入和输出数据类型相同,要求输入 input 的维度信息与 result_type 设置的维度信息必须完全一样。

参数:
  • input - 输入 Op

  • result_type - 指定输出的类型

返回值:
  • 输入 Op

示例代码:

auto out = builder::Convert(input, result_type);

语义详见: Convert

2.44. Cos

builder::Op Cos(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的余弦

(2.44.1)\[Cos(input)=std::cos(input) \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Cos(input);
auto out2 = builder::Cos(input, result_type);

语义详见: Cos

2.45. CosGrad

builder::Op CosGrad(builder::Op grad_output,
                     builder::Op input,
                     builder::Type result_type = builder::Type());

总结: 逐元素计算 Cos 输入 input 的梯度

(2.45.1)\[grad\_in=-grad\_out * sin(input)\]
参数:
  • grad_output - Cos 输出的梯度

  • input - Cos 输入

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度,与 input 维度相同、数据类型相同。

示例代码:

auto grad_input1 = builder::CosGrad(grad_output, input);
auto grad_input2 = builder::CosGrad(grad_output, input, result_type);

语义详见: semantics-cos_grad

2.46. CTCLoss

builder::Op CTCLoss(builder::Op log_probs,
                    builder::Op target_labels,
                    builder::Op input_lengths,
                    builder::Op target_lengths,
                    int64_t blank = 0,
                    builder::Type result_type = builder::Type());

总结: 计算 CTC(Connectist Temporal Classification) 损失和梯度。

参数:
  • log_probs - 输入概率序列,维度为 (T, N, C)。其中 T 表示输入长度, N 表示批次大小, C 是分类数,包含空白。

  • target_labels - 目标标签序列,维度为 (N, S)。其中 S 表示最大目标长度。

  • input_lengths - 输入长度,维度为 (N)

  • target_lengths - 目标长度,维度为 (N)

  • blank - (可选)空白标签,默认为 0

  • result_type - (可选)指定输出的类型

返回值:
  • 根据调用 CTCLoss 时传递的 result_type 决定返回 Tuple Op,还是单损失输出 Op。

  • 返回 Tuple Op: 传入的 result_type 为 Tuple Type,返回的 Tuple Op 包含两个输出:1. neg_log_likelihood 对每个输入节点可微调的损失值,维度为 (N); 2. log_alpha 输入到输出的轨迹概率,维度为 (N, T, 2*S+1)

  • 返回 Op: 传入的 result_type 不是 Tuple Type,返回 neg_log_likelihood

示例代码:

auto out = builder::CTCLoss(log_probs, target_labels, input_lengths, target_lengths, result_type);

语义详见: CTCLoss

2.47. CTCLossGrad

builder::Op CTCLossGrad(builder::Op log_probs,
                        builder::Op target_labels,
                        builder::Op input_lengths,
                        builder::Op target_lengths,
                        builder::Op grad_loss,
                        builder::Op loss,
                        builder::Op alpha,
                        int64_t blank = 0,
                        bool zero_infinity = false,
                        builder::Type result_type = builder::Type());

总结: 计算 CTC(Connectist Temporal Classification) 输入 log_probs 的梯度。

参数:
  • log_probs - 输入概率序列,维度为 (T, N, C)。其中 T 表示输入长度, N 表示批次大小, C 是分类数,包含空白。

  • target_labels - 目标标签序列,维度为 (N, S)。其中 S 表示最大目标长度。

  • input_lengths - 输入长度,维度为 (N)

  • target_lengths - 目标长度,维度为 (N)

  • grad_loss - CTC 输出 loss 的梯度

  • loss - CTC 输出 loss

  • blank - (可选)空白标签,默认为 0

  • zero_infinity - (可选)是否设置无限损失和相关梯度为零,默认为 false

  • result_type - (可选)指定输出的类型

返回值:
  • CTCLoss 输入 log_probs 的梯度

示例代码:

auto grad_input = builder::CTCLossGrad(log_probs,
                                    target_labels,
                                    input_lengths,
                                    target_lengths,
                                    grad_loss,
                                    loss,
                                    alpha,
                                    blank,
                                    zero_infinity,
                                    result_type);

语义详见: semantics-ctc_loss_grad

2.48. CumSum

builder::Op CumSum(builder::Op input,
                   builder::Op axis,
                   bool exclusive = false,
                   bool reverse = false,
                   builder::Type result_type = builder::Type());

总结: 沿给定轴 axis 计算输入 input 的累加和。默认情况下,结果的第一个元素与输入第一个元素相同,可通过设置 exclusivetrue,更改此行为以排除第一个元素。也可以沿着轴 axis 的反方向进行累加求和,只需要将属性 reverse 设置为 true 即可。

参数:
  • input - 需要进行累加的输入

  • axis - 指定需要进行累加的轴,axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • exclusive - (可选)累加计算时是否排除第一个元素。如果设置为 true,将返回不包含第一个元素的累加和,即第 j 个输出元素是前 j-1 个输入元素的和。默认为 false

  • reverse - (可选)是否以反方向进行累加求和。默认为 false

  • result_type - 指定输出的类型

返回值:
  • 输出 Op,维度和数据类型与输入相同。

示例代码:

auto out = builder::CumSum(input, axis, false, false);

语义详见: semantics-cumsum

2.49. CustomCall

builder::Op CustomCall(std::vector<builder::Op> args,
                       const char* call_target_name,
                       std::vector<const char*> region_list,
                       builder::Type result_type);

总结: 调用用户自定义的计算逻辑

参数:
  • args - 自定义函数的输入

  • call_target_name - 目标函数名称

  • region_list - 未使用,默认为空 {}

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::CustomCall(args, target_name, {}, result_type);

语义详见: CustomCall

2.50. DepthToSpace

builder::Op DepthToSpace(builder::Op input,
                         std::vector<int64_t> space_dims,
                         int64_t depth_dim,
                         int64_t block_size,
                         const char* mode = "DCR",
                         builder::Type result_type = builder::Type());

总结: 将深度数据重新排列到空间维度中,是 SpaceToDepth 的反向操作。

参数:
  • input - 输入 Op,必须为四维。

  • space_dims - 输入 Op 的空间维度:输入为 NCHW 时, space_dims 设置为 {2, 3};输入为 NHWC 时, space_dims 设置为 {1, 2}

  • depth_dim - 输入 Op 的深度维度:输入为 NCHW 时, depth_dim 设置为 1;输入为 NHWC 时, depth_dim 设置为 3

  • block_size - 用于划分深度数据的块大小,其值必须 >= 2

  • mode - 重排模式,DCR 模式下,输入张量沿深度-列-行的顺序进行重排;CRD 模式使用列-行-深度的模式重排。默认为 DCR。

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::DepthToSpace(input, space_dims, depth_dim, block_size, mode);

语义详见: DepthToSpace

2.51. Div

builder::Op Div(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator/(builder::Op lhs, builder::Op rhs);

总结: 逐元素对输入 lhsrhs 进行相除, 并将各个位置的输出元素保存到返回结果中。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator/ 获得相同的效果。

(2.51.1)\[Div(lhs, rhs) = \frac{lhs}{rhs} \]
参数:
  • lhs - 需要相除的左值

  • rhs - 需要相除的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Div(lhs, rhs);
auto out2 = builder::Div(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Div(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs / rhs;

语义详见: Div

2.52. Dot

builder::Op Dot(builder::Op lhs,
                builder::Op rhs,
                std::vector<const char*> precision_config,
                builder::Type result_type = builder::Type());

总结:lhs 的第二个维度( Rank 为 1 时则为第一个维度)与 rhs 的第一个维度执行乘积之和。

参数:
  • lhs - 左操作数

  • rhs - 右操作数

  • precision_config - (可选)用于 TensorFlow 配置,默认为 {} 即可。

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 进行相乘的维度必须相同

返回值:
  • 输出 Op,数据类型与输入相同,维度满足以下规则:

  • vector[n] dot vector[n] => scalar

  • matrix[m, k] dot vector[k] => vector[m]

  • matrix[m, k] dot matrix[k, n] => matrix[m, n]

示例代码:

auto out1 = builder::Dot(lhs, rhs, {});
auto out2 = builder::Dot(lhs, rhs, {}, result_type);

语义详见: Dot

2.53. DotGeneral

builder::Op DotGeneral(builder::Op lhs,
                       builder::Op rhs,
                       builder::DotDimensionNumbers dot_dimension_numbers,
                       std::vector<const char*> precision_config,
                       builder::Type result_type = builder::Type());

总结:Dot 操作的语义相同,区别是 DotGeneral 通过 dot_dimension_numbers 属性的 lhs_contracting_dimensionsrhs_contracting_dimensions 来指定 lhsrhs 进行相乘的维度。

参数:
  • lhs - 左操作数

  • rhs - 右操作数

  • dot_dimension_numbers - 指定 lhsrhs 进行相乘和 batch 处理的维度。

  • precision_config - (可选)用于 TensorFlow 配置,默认为 {} 即可。

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 进行相乘的维度必须相同

  • 输入 lhsrhs 对应的 batch 维度必须相同

示例代码:

// lhs = { {1.0, 2.0, 3.0}, {4.0, 5.0, 6.0} }
// rhs = { {1.0, 1.0, 1.0}, {2.0, 2.0, 2.0} }
// DotDimensionNumbers dnums = {{}, {}, 1, 1}; lhs_batch = rhs_batch = {}
auto out1 = builder::DotGeneral(lhs, rhs, dnums, {});
// out1 = { {6.0, 12.0}, {15.0, 30.0} }

// lhs = { { {1.0, 2.0}, {3.0, 4.0} }, { {5.0, 6.0}, {7.0, 8.0} } }
// rhs = { { {1.0, 0.0}, {0.0, 1.0} }, { {1.0, 0.0}, {0.0, 1.0} } }
// DotDimensionNumbers dnums = {{0}, {0}, 2, 1}; lhs_batch = rhs_batch = {0}
auto out2 = builder::DotGeneral(lhs, rhs, dnums, {});
// out2 = { { {1.0, 2.0}, {3.0, 4.0} }, { {5.0, 6.0}, {7.0, 8.0} } }

语义详见: DotGeneral

2.54. DotGeneralBias

builder::Op DotGeneralBias(builder::Op lhs,
                           builder::Op rhs,
                           std::vector<builder::Op> bias,
                           builder::DotDimensionNumbers dot_dimension_numbers,
                           std::vector<const char*> precision_config,
                           builder::Type result_type = builder::Type());

[Deprecated API]: HLIR 图优化 Op,只在 pass 中使用。

总结: Fusion 优化类 Op,不推荐使用。 将 DotGeneralAdd 操作进行合并,调用对应的优化算子实现。推理栈 pass pipeline 中会对符合 fusion 的 DotGeneralAdd pattern 进行融合。

参数:
  • lhs - 左操作数

  • rhs - 右操作数

  • bias - 只有一个 Op 的 vector,表示 Add 的右操作数。

  • dot_dimension_numbers - 指定 lhsrhs 进行相乘和 batch 处理的维度。

  • precision_config - (可选)用于 TensorFlow 配置,默认为 {} 即可。

  • result_type - (可选)指定返回值的类型

限制:
  • DotGeneral 的基础上,增加对 bias 的限制: bias 只包含有一个 Rank 为 1 的 Op。

  • 如果 bias 的 dim[0] 不为 1,则值必须等于 DotGeneral 输出 Op 最后一维的值。

示例代码:

// lhs: type = tensor<6x1024x1024xf32>
// rhs: type = tensor<6x1024x1024xf32>
// bias: size 为 1 的vector,type = tensor<1024xf32>
// DotDimensionNumbers dnums = {{0}, {0}, 2, 1}; lhs_batch = rhs_batch = {0}
auto out = builder::DotGeneralBias(lhs, rhs, bias, dnums, {});

语义详见: DotGeneralBias

2.55. Dropout

builder::Op Dropout(builder::Op input,
                    float ratio,
                    bool training_mode = true,
                    std::experimental::optional<int64_t> seed = builder::nullopt,
                    std::vector<int64_t> noise_shape = {},
                    builder::Type result_type = builder::Type());

总结: Dropout 是一种正则化手段,可根据给定的丢弃概率 p,在训练过程中随机将一些神经元输出设置为 0,通过阻止神经元节点间的相关性来减少过拟合。

参数:
  • input - 输入 Op

  • ratio - 用于描述丢弃概率: p = 1.0 / (1.0 - ratio)

  • training_mode - 标记是否为训练阶段,默认值为 True。如果设置为 false,则忽略比率,模拟推理模式,输入数据不会丢失任何内容。

  • seed - 随机数生成器的种子,默认设置为 builder::nullopt ,会自动生成。

  • noise_shape - (可选)描述与输入 input 进行相乘的 shape 形状

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::Dropout(input, ratio, training_mode, seed, noise_shape);

语义详见: Dropout

2.56. DynamicBroadcastInDim

builder::Op DynamicBroadcastInDim(builder::Op input,
                                  builder::Op output_shape,
                                  std::vector<int64_t> broadcast_dimensions = {},
                                  builder::Type result_type = builder::Type());

总结: BroadcastInDim 的泛化版本,接收将输出维度作为输入 Op 传入,用于动态 Shape 场景。

参数:
  • input - 输入 Op

  • output_shape - 表示目标 Shape 的 Op,数据类型为 8/16/32/64 位的整形类型。

  • broadcast_dimensions - 指定需要被广播的维度,语义参考 XLA 的规则。

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicBroadcastInDim(input, new_shape, broadcast_dimensions);

语义详见: DynamicBroadcastInDim

2.57. DynamicIota

builder::Op DynamicIota(builder::Op output_shape,
                        int64_t iota_dimension,
                        builder::Type result_type = builder::Type());

总结: Iota 的泛化版本,接收将输出维度作为输入 Op 传入,用于动态 Shape 场景。

参数:
  • input - 输入 Op

  • output_shape - 表示目标 Shape 的 Op,数据类型为 8/16/32/64 位的整形类型。

  • iota_dimension - iota 递增的起始数值

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicIota(new_shape, iota_dimension);

语义详见: DynamicIota

2.58. DynamicPad

builder::Op DynamicPad(builder::Op input,
                       builder::Op pads,
                       builder::Op padding_value,
                       int64_t mode,
                       builder::Type result_type = builder::Type());

总结: Pad 的泛化版本,接收对输入 input 进行 Pad 的维度信息作为输入 pads 传入,用于 Pad 维度为动态输入的场景。

参数:
  • input - 输入 Op,要进行 Pad 操作的 Op

  • pads - 表示输入 input 进行 Pad 操作的维度。维度填充的方式为 [begin1, begin2, begin3, …, end1, end2, end3, …]

  • padding_value - Pad 填充的值,仅在 mode 为 0 时有效。

  • mode - Pad 填充模式,可选择 0,1,2,3 四种,分别代表 pad_value, pad_edge, pad_reflect, pad_symmetric模式。

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicPad(input, pads, padding_value, mode);

语义详见: DynamicPad

2.59. DynamicReshape

builder::Op DynamicReshape(builder::Op input,
                           builder::Op output_shape,
                           std::experimental::optional<int64_t> allowzero = builder::nullopt,
                           builder::Type result_type = builder::Type());

总结: Reshape 的泛化版本,用于目标 shape 为动态输入的场景。

参数:
  • input - 输入 Op,要进行 Reshape 操作的 Op

  • output_shape - 表示目标 shape

  • allowzero - (可选)语义来自 ONNX。默认设置为 0,当 output_shape 对应的任何值为零时,将从输入 input 复制对应的纬度值;当 allowzero 设置为 1 时,表示如果 output_shape 对应的任何值为零时,输出对应的维度也是零。

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicReshape(input, output_shape, builder::nullopt);

语义详见: DynamicReshape

2.60. DynamicSlice

builder::Op DynamicSlice(builder::Op input,
                         std::vector<builder::Op> start_indices,
                         std::vector<int64_t> slice_sizes,
                         builder::Type result_type = builder::Type());

总结: Slice 的泛化版本, DynamicSlice 从动态输入 start_indices 中读取 slice 切分开始维度信息,每个维度切分大小通过 slice_sizes 指定。

参数:
  • input - 输入 Op,要进行 Slice 操作的 Op

  • start_indices - 表示 Slice 切分开始的维度, Rank 必须为 1,维度大小等于输入 input 的 Rank。

  • slice_sizes - 指定每个维度切分的长度

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicSlice(input, start_indices, slice_sizes);

语义详见: DynamicSlice

2.61. DynamicUpdateSlice

builder::Op DynamicUpdateSlice(builder::Op input,
                               builder::Op update,
                               std::vector<builder::Op> start_indices,
                               builder::Type result_type = builder::Type());

总结: 基于 DynamicSlice 对输入 input 进行更新。 输入 inputstart_indices 开始进行切分更新,更新数据来自 updateupdate 维度决定了最终输出 Op 的维度。

参数:
  • input - 输入 Op,要进行 Slice 操作的 Op

  • update - 包含输入切分进行更新的数据, update 的每个维度必须严格大于零,并且 start + update 必须小于或者等于输入对应维度的大小,以避免生成越界更新索引。

  • start_indices - 表示 Slice 切分开始的维度, Rank 必须为 1,维度大小等于输入 input 的 Rank。

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::DynamicUpdateSlice(input, update, start_indices);

语义详见: DynamicUpdateSlice

2.62. Elu

builder::Op Elu(builder::Op input,
                float alpha = 1,
                builder::Type result_type = builder::Type());

总结: elu 激活层(ELU Activation),指数线性单元激活函数,对输入 input 逐元素计算 ELU。

(2.62.1)\[ELU(input)=\begin{cases} alpha*(e^{input}-1), & \text input<=0 \\ input & \text input>0 \end{cases} \]
参数:
  • input - 输入 Op

  • alpha - (可选)平滑系数,决定 ELU 的平滑度,默认为 1.0

  • result_type - (可选)指定返回值的类型

示例代码:

auto out = builder::Elu(input, alpha);

语义详见: Elu

2.63. Empty

builder::Op Empty(std::shared_ptr<builder::Builder> builder,
                  builder::PrimitiveType data_type,
                  const std::vector<int64_t>& shapes = {0});

总结: 构造 Empty Tensor Op,最终调用以下 Const API

auto op = builder::Const(builder, nullptr, builder::Type(shapes, data_type));
参数:
  • builder - 全局 builder::Builder 对象共享指针

  • data_type - 指定 Empty Tensor 的数据类型

  • shapes - 指定 Empty Tensor 的维度信息

限制:
  • 维度 shapes 必须包含 0。

示例代码:

auto out = builder::Empty(builder, builder::PrimitiveType::F32());

语义详见: semantics-empty

2.64. EmptyLike

builder::Op EmptyLike(
    builder::Op input,
    std::experimental::optional<builder::PrimitiveType> new_data_type = builder::nullopt,
    std::experimental::optional<std::vector<int64_t>> new_shapes = builder::nullopt);

builder::Op EmptyLike(builder::Op input,
                      builder::PrimitiveType new_data_type,
                      const std::vector<int64_t> &new_shapes);

template <typename T>
builder::Op EmptyLike(builder::Op input,
                      builder::PrimitiveType new_data_type,
                      const std::initializer_list<T>& new_shapes);

总结: 根据输入 input 对应的数据类型和维度信息,构造 Empty Tensor Op。常用使用方式为 builder::EmptyLike(input),构造的输出 Op 数据类型与输入 input 相同,在 input 对应的维度开头补 0 即为输出 Op 的维度。 也可只利用 input 保存的全局 Builder 共享指针,自行设置数据类型和维度,但需确保维度中包含 0。

参数:
  • input - 参考的输入,默认会从 input 中获取保存的全局 Builder 共享指针,以及 input 的数据类型和维度信息。

  • new_data_type - 重新指定数据类型,不采用 input 的数据类型。

  • new_shapes - 重新指定维度信息,不采用 input 的维度信息。

限制:
  • 维度 new_shapes 不为 builder::nullopt 时,必须包含 0。

返回值:
  • 输出 Const Op,为 Empty Op。

示例代码:

// input: tensor<1x3x224x224xf32>
auto out1 = builder::EmptyLike(input);  // tensor<0x1x3x224x224xf32>
auto out2 = builder::EmptyLike(input, builder::PrimitiveType::S32());  // tensor<0x1x3x224x224xi32>
std::vector<int64_t> new_shapes = {0, 1};
auto out3 = builder::EmptyLike(input, builder::PrimitiveType::S32(), new_shapes);  // tensor<0x1xi32>
auto out4 = builder::EmptyLike(input, builder::PrimitiveType::S32(), {0, 4});  // tensor<0x4xi32>

语义详见: semantics-empty_like

2.65. Equal

builder::Op Equal(builder::Op lhs,
                  builder::Op rhs,
                  std::vector<int64_t> broadcast_dimensions = {},
                  builder::Type result_type = builder::Type());

builder::Op operator==(builder::Op lhs, builder::Op rhs);

总结: 逐元素比较 lhsrhs 是否相等,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator== 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Equal(lhs, rhs);
auto out2 = builder::Equal(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Equal(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs == rhs;

语义详见: semantics-equal

2.66. Expand

builder::Op Expand(builder::Op input,
                   builder::Op shape,
                   builder::Type result_type = builder::Type());

总结: 根据 shape 指定的维度扩展 input,扩展后的输出 Op 形状与 shape 指定的形状一致。

参数:
  • input - 输入 Op

  • shape - shape 的元素值为具体扩展的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 shape 的数据类型为: int32 或 int64,暂时只支持 shape 为 Const Op。

返回值:
  • 输出 Op,数据类型与输入 input 一致。

示例代码:

// input: {4.0f, 8.0f} 1x2x1x1xf32
// shape: Const Op, value is {1, 2, 1, 4} 4xi64
auto out = builder::Expand(input, shape);
// out: {4.0f, 4.0f, 4.0f, 4.0f, 8.0f, 8.0f, 8.0f, 8.0f} 1x2x1x4xf32

语义详见: semantics-expand

2.67. Erf

builder::Op Erf(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 Erf(Error function) 激活函数

(2.67.1)\[Erf(input) = \frac{2}{\sqrt{\pi}} \int_{0}^{input}e^{- \eta^{2}}d\eta \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Erf(input);
auto out2 = builder::Erf(input, result_type);

语义详见: Erf

2.68. Exp

builder::Op Exp(builder::Op input, builder::Type result_type = builder::Type());

总结: 对输入 input ,逐元素进行以自然数 e 为底指数运算。

(2.68.1)\[out = e^{input} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Exp(input);
auto out2 = builder::Exp(input, result_type);

语义详见: Exp

2.69. ExpGrad

builder::Op ExpGrad(builder::Op grad_output,
                    builder::Op out,
                    builder::Type result_type = builder::Type());

总结: 逐元素计算 Exp(input) 输入 input 的梯度

(2.69.1)\[Exp(input) = e^{input}\]
(2.69.2)\[grad\_in = grad\_out * out\]
参数:
  • grad_output - Exp 输出的梯度

  • out - Exp(input) 的输出

  • result_type - (可选)指定输出的类型

返回值:
  • 输入 input 的梯度,与 input 维度相同、数据类型相同。

示例代码:

auto grad_input1 = builder::ExpGrad(grad_output, out);
auto grad_input2 = builder::ExpGrad(grad_output, out, result_type);

语义详见: semantics-exp_grad

2.70. Expm1

builder::Op Expm1(builder::Op input, builder::Type result_type = builder::Type());

总结: 对输入 input ,逐元素进行以自然数 e 为底指数运算并减 1。

(2.70.1)\[out = e^{input} - 1 \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Expm1(input);
auto out2 = builder::Expm1(input, result_type);

语义详见: Expm1

2.71. Flatten

builder::Op Flatten(builder::Op input,
                    int64_t axis = 1,
                    builder::Type result_type = builder::Type());

总结: 根据指定的轴 axis 将输入 input 展平为二维矩阵。如果输入 input 维度形状为 (d0, d1, …dn),则输出的维度为 (d0xd1x…d(axis-1), d(axis)xd(axis+1)…dn)。

参数:
  • input - 输入 Op, Rank >= axis。

  • axis - (可选)指示对输入 input 进行运算的轴, axis 的有效范围是 [-R, R], R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致。当 axis = 0 时,输出 Op 的维度形状为 (1, d0xd1x…xdn),其中输入 Op 维度为 (d0, d1, …, dn)。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与输入 input 内容相同,Rank 为 2,具体维度为展平之后的维度。

示例代码:

auto out1 = builder::Flatten(input, 1);
auto out2 = builder::Flatten(input, 1, result_type);

语义详见: semantics-flatten

2.72. FlattenV2

builder::Op FlattenV2(builder::Op input,
                      int64_t start_axis = 0,
                      int64_t stop_axis = -1,
                      builder::Type result_type = builder::Type());

总结: 根据指定的轴 start_axisstop_axis ,将输入 input 连续的维度进行展平。如果输入 input 维度形状为 (d0, d1, …dn),则输出的维度为 (d0, d1, …d(start_axis-1), d(start_axis)xd(start_axis+1)x…xd(stop_axis-1)xd(stop_axis), …, dn)。

参数:
  • input - 输入 Op, Rank >= axis。

  • start_axis - (可选)指示对输入 input 进行运算的轴, axis 的有效范围时 [-R, R), R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致。

  • stop_axis - (可选)指示对输入 input 进行运算的轴, axis 的有效范围时 [-R, R), R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与输入 input 内容相同,数据类型相同,维度为展平后的维度。

限制:
  • 要求 start_axis <= stop_axis

示例代码:

auto out1 = builder::FlattenV2(input, 0, -1);
auto out2 = builder::FlattenV2(input, 0, -1, result_type);

语义详见: semantics-flatten_v2

2.73. Floor

builder::Op Floor(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素对输入 input 进行向下取整运算

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Floor(input, result_type);

语义详见: Floor

2.74. FloorGrad

builder::Op FloorGrad(builder::Op grad_output, builder::Type result_type = builder::Type());

总结: 逐元素计算 Floor(input) 对输入 input 的梯度,Floor(input) 的输入梯度为常量 0。数据类型与输入 input 或者输出梯度 grad_output 一致。

参数:
  • grad_output - Floor 输出的梯度,用于获取保存的全局 Builder 共享指针,以及 Floor 操作数的数据类型和维度。

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度 Op,为常量 0,数据类型和维度与 grad_output 一致。

示例代码:

auto grad_input = builder::FloorGrad(grad_output, result_type);

语义详见: semantics-floor_grad

2.75. FullLike

// 语义参考 NumPy: https://numpy.org/doc/stable/reference/generated/numpy.full_like.html

template <typename T>
builder::Op FullLike(
    builder::Op input,
    T fill_value,
    std::experimental::optional<builder::PrimitiveType> new_data_type = builder::nullopt,
    std::experimental::optional<std::vector<int64_t>> new_shapes = builder::nullopt);

template <typename T>
builder::Op FullLike(builder::Op input,
                     T fill_value,
                     builder::PrimitiveType new_data_type,
                     const std::vector<int64_t> &new_shapes);

template <typename T, typename U>
builder::Op FullLike(builder::Op input,
                     T fill_value,
                     builder::PrimitiveType new_data_type,
                     const std::initializer_list<U> &new_shapes);

总结: 根据输入 input 对应的数据类型和维度信息,构造值全为 fill_value 的 Const Op。常用使用方式为 builder::FullLike(input, fill_value),构造的输出 Op 数据类型,维度与输入 input 相同。 也可只利用 input 保存的全局 Builder 共享指针,自行设置数据类型和维度。

参数:
  • input - 参考的输入,默认会从 input 中获取保存的全局 Builder 共享指针,以及 input 的数据类型和维度信息。

  • new_data_type - 重新指定数据类型,不采用 input 的数据类型。

  • new_shapes - 重新指定维度信息,不采用 input 的维度信息。

返回值:
  • 输出 Const Op。

示例代码:

// input: tensor<1x3x224x224xf32>, fill_value: 2.0
auto out1 = builder::FullLike(input);  // tensor<1x3x224x224xf32> value = 2.0
auto out2 = builder::FullLike(input,
                              builder::PrimitiveType::S32());  // tensor<1x3x224x224xi32> value = 2
std::vector<int64_t> new_shapes = {1};
auto out3 = builder::FullLike(input,
                              builder::PrimitiveType::S32(), new_shapes);  // tensor<1xi32> value = 2
auto out4 = builder::FullLike(input,
                              builder::PrimitiveType::S32(), {4});  // tensor<4xi32> value = 2

语义详见: semantics-full_like

2.76. Gather

builder::Op Gather(builder::Op input,
                   builder::Op start_indices,
                   builder::GatherDimensionNumbers dimension_numbers,
                   std::vector<int64_t> slice_sizes,
                   bool indices_are_sorted = false,
                   builder::Type result_type = builder::Type());

总结: 将输入 input 的的多个切片(每个切片可能具有不同的偏移量)拼接再一起。语义与 XLA Gather 一致。

参数:
  • input - 需要进行拼接的输入 Op

  • start_indices - 包含拼接切片起始索引的 Op

  • dimension_numbers - 包含 index_vector_dim, offset_dims, collapsed_slice_dims, start_index_map 属性。 index_vector_dim - start_indices 中包含起始索引的维度; offset_dims - 输出维度中偏移到从输入切片的数组中的维度; collapsed_slice_dims - 每个切片进行折叠的维度; start_index_map - 描述如何将 start_indices 的u偶姻映射到输入 input 合法索引的映射;

  • slice_sizes - 指定每个维度 i 切片的上界

  • indices_are_sorted - 是否保证调用者对索引进行排序

  • result_type - (可选)指定输出的类型

返回值:
  • 输出拼接 Op

示例代码:

auto out = builder::Gather(input, start_indices, dimension_numbers, slice_sizes, false);

语义详见: Gather

2.77. GeGlu

builder::Op GeGlu(builder::Op input,
                  bool approximate = true,
                  int64_t dim = -1,
                  builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 GEGLU 激活函数,参考 https://arxiv.org/abs/2002.05202

参数:
  • input - 输入 Op

  • approximate - (可选)用于控制 GELU 激活函数是否采用近似计算,具体可参考 Gelu

  • dim - 对输入进行切分的维度

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::GeGlu(input, approximate, dim);

语义详见: GeGlu

2.78. Gelu

builder::Op Gelu(builder::Op input,
                 bool approximate = true,
                 builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 GELU(Gaussian Error Linear Unit) 激活函数

  • approximate = false 时, GELU 公式如下:

(2.78.1)\[gelu(input) = 0.5 * input * (1 + erf(\frac{input}{\sqrt{2}}))\]
  • approximate = true 时,GELU 近似计算如下:

(2.78.2)\[gelu(input) = 0.5 * input * (1 + tanh(\sqrt{\frac{2}{\pi}} * (input + 0.044715 * input^{3})))\]
参数:
  • input - 输入 Op

  • approximate - (可选)用于控制是否采用近似计算

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 一致

示例代码:

auto out = builder::Gelu(input, approximate);

语义详见: Gelu

2.79. GeluGrad

builder::Op GeluGrad(builder::Op grad_output,
                     builder::Op input,
                     std::experimental::optional<bool> approximate = builder::nullopt,
                     builder::Type result_type = builder::Type());

总结: 逐元素计算 GELU 激活函数输入 input 的梯度

  • approximate = false 时, GELU 输入 input 梯度计算如下:

(2.79.1)\[gelu(input) = 0.5 * input * (1 + erf(\frac{input}{\sqrt{2}}))\]
(2.79.2)\[first = 1 + erf(\frac{input}{\sqrt{2}})\]
(2.79.3)\[second = input * \sqrt{\frac{2}{\pi}} * e^{-0.5 * input^{2}}\]
(2.79.4)\[grad\_in = 0.5 * grad\_out * (first + second)\]
  • approximate = true 时, GELU 采用近似计算,输入 input 梯度计算如下:

(2.79.5)\[gelu(input) = 0.5 * input * (1 + tanh(\sqrt{\frac{2}{\pi}} * (input + 0.044715 * input^{3})))\]
(2.79.6)\[y = tanh(\sqrt{\frac{2}{\pi}} * 0.044715 * input^{3} + input)\]
(2.79.7)\[first = input - input * y^{2}\]
(2.79.8)\[second = \sqrt{\frac{2}{\pi}} + \sqrt{\frac{2}{\pi}} * 0.044715 * 3 * input^{2}\]
(2.79.9)\[grad\_in = 0.5 * grad\_out * (1 + y + first * second)\]
参数:
  • grad_output - GELU 输出的梯度

  • input - 输入 Op

  • approximate - (可选)用于控制 GELU 是否采用近似计算

  • result_type - (可选)指定输出的类型

返回值:
  • 输入的梯度,数据类型和维度与输入 input 一致

示例代码:

auto out = builder::GeluGrad(grad_output, input, approximate);

语义详见: semantics-gelu_grad

2.80. Gemm

builder::Op Gemm(std::vector<builder::Op> ins,
                 float alpha = 1.0,
                 float beta = 1.0,
                 int64_t transA = 0,
                 int64_t transB = 0,
                 builder::Type result_type = builder::Type());

总结: General Matrix multiplication,定义来自 ONNX,计算 Y = alpha * A’ * B’ + beta * C。输入 ins 包含 2 个 或 3 个 Op,即 A, B, 以及可选的 C。其中 A 的维度为 (M, K) 或 (K, M), B 的维度为 (K, N) 或 (N, K), C 可广播为 (M, N), 输出 Y 的维度为 (M, N)。如果属性 transA 非零, 则 A 将在计算之前转置, 对于 B 和 transB 同样如此。

  • 公式如下,其中 transA, transB 用于控制输入 A, B 是否需要先做转置操作。

(2.80.1)\[Y = alpha * A' * B' + beta * C\]
参数:
  • ins - 输入 Op 集合,大小为 2 或者 3。

  • alpha - (可选)矩阵 A 的 系数,默认为 1

  • beta - (可选)矩阵 B 的稀疏,默认为 1

  • transA - (可选)是否需要先对矩阵 A 做转置操作,默认为 0,即不做转置操作

  • transB - (可选)是否需要先对矩阵 B 做转置操作,默认为 0,即不做转置操作

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型输入一致,维度为 (M, N)

示例代码:

auto out = builder::Gemm(ins);

语义详见: Gemm

2.81. GetTupleElement

builder::Op GetTupleElement(builder::Op input,
                            int32_t index,
                            builder::Type result_type = builder::Type());

总结: 使用编译时常量值 index 对 Tuple 输入 input 进行索引。概念上类似 C++ 的 std::get<int N>(tuple_variale)。

参数:
  • input - 输入 Tuple Op

  • index - 索引

  • result_type - (可选)指定输出的类型

限制:
  • 输入 input 必须为 tuple 类型

  • 属性 index 必须在输入 input 的有效范围内

返回值:
  • 输出 Op

示例代码:

auto out = builder::GetTupleElement(input, index);

语义详见: GetTupleElement

2.82. GlobalAveragePool

builder::Op GlobalAveragePool(builder::Op input,
                              std::vector<int64_t> dims,
                              builder::Type result_type = builder::Type());

总结: 对输入 input 维度 dims 所有的值应用平均池化。

参数:
  • input - 输入 Op

  • dims - 需要进行平均池化的维度

  • result_type - (可选)指定输出的类型

限制:
  • 输入 input 的 Rank >= 2

返回值:
  • 输出 Op

示例代码:

auto out = builder::GlobalAveragePool(input, dims);

语义详见: GlobalAveragePool

2.83. GlobalMaxPool

builder::Op GlobalMaxPool(builder::Op input,
                          std::vector<int64_t> dims,
                          builder::Type result_type = builder::Type());

总结: 对输入 input 维度 dims 所有的值应用最大池化。

参数:
  • input - 输入 Op

  • dims - 需要进行最大池化的维度

  • result_type - (可选)指定输出的类型

限制:
  • 输入 input 的 Rank >= 2

返回值:
  • 输出 Op

示例代码:

auto out = builder::GlobalMaxPool(input, dims);

语义详见: GlobalMaxPool

2.84. Glu

builder::Op Glu(builder::Op input,
                int64_t axis = -1,
                builder::Type result_type = builder::Type());

总结: 门线性单元函数 (Gated Linear Unit function),语义参考 https://arxiv.org/abs/1612.08083,公式如下:

(2.84.1)\[{GLU}(a, b)= a \otimes \sigma(b)\]
  • 输入按照给定的轴 axis 二等分,拆分后的前一半元素表示为 a , 后一半元素表示为 b 。 \(\sigma\) 表示 sigmoid 函数, \(\otimes\) 是 Hadamard 乘积。

参数:
  • input - 输入 Op

  • axis - (可选)指定分割轴,默认为 -1 表示输入 input 最后一维。 axis 的有效范围是 [-R, R),R 是每个输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型与输入 input 一致,在指定的轴上其维度减半。

示例代码:

auto out = builder::Glu(input, axis);

语义详见: Glu

2.85. Greater

builder::Op Greater(builder::Op lhs,
                    builder::Op rhs,
                    std::vector<int64_t> broadcast_dimensions = {},
                    builder::Type result_type = builder::Type());

builder::Op operator>(builder::Op lhs, builder::Op rhs);

总结: 逐元素比较 lhs > rhs ,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator> 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Greater(lhs, rhs);
auto out2 = builder::Greater(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Greater(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs > rhs;

语义详见: semantics-greater

2.86. GreaterEqual

builder::Op GreaterEqual(builder::Op lhs,
                         builder::Op rhs,
                         std::vector<int64_t> broadcast_dimensions = {},
                         builder::Type result_type = builder::Type());

builder::Op operator>=(builder::Op lhs, builder::Op rhs);

总结: 逐元素比较 lhs >= rhs ,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator>= 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::GreaterEqual(lhs, rhs);
auto out2 = builder::GreaterEqual(lhs, rhs, broadcast_dimensions);
auto out3 = builder::GreaterEqual(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs >= rhs;

语义详见: semantics-greater_equal

2.87. GridSample

builder::Op GridSample(builder::Op input,
                       builder::Op grid,
                       builder::DimensionsLayout layout,
                       int64_t mode = 1,
                       bool align_corners = false,
                       int64_t padding_mode = 0,
                       builder::Type result_type = builder::Type());

总结: 基于 flow field 网格的对输入 input 进行双线性插值采样。

参数:
  • input - 输入 Op

  • grid - 输入网格数据,数据类型与 input 一致

  • layout - 描述输入 input 的 Layout

  • mode - (可选)插值方式,可以为 linear(0) 和 nearest(1) ,默认为 1 , 即 nearest。

  • align_corners - (可选)如果设置成 true,-1和1被视为引用输入角像素的中心点。如果设置为 false,将被视为引用到输入角像素的角点,使采样更不受分辨率影响。默认值为 false。

  • padding_mode - (可选)支持 PAD_VALUE(0), PAD_EDGE(1), PAD_REFLECT(2)。默认为 0 , 即 PAD_VALUE, 使用 0 表示超出范围的网格位置。

  • result_type - (可选)指定返回值的类型

限制:

  • 只支持 input Rank = 4 , NHWC 格式。

返回值:
  • 输出 Op,数据类型与输入相同

示例代码:

auto out = builder::GridSample(input, grid, layout);

语义详见: GridSample

2.88. GroupNorm

builder::Op GroupNorm(builder::Op input,
                      builder::Op scale,
                      builder::Op bias,
                      int64_t num_groups,
                      float epsilon,
                      builder::DimensionsLayout layout,
                      builder::Type result_type = builder::Type());

总结: 在 min-batch 输入上进行组归一化,Group Normalization 把通道划分为组,然后计算每一组内的均值和方差,以进行归一化。论文参考:https://arxiv.org/abs/1803.08494

(2.88.1)\[y = \frac{input - \mathrm{E}[input]}{\sqrt{\mathrm{Var}[input] + epsilon}} * scale + bias\]
参数:
  • input - 输入 Op,维度为 [N, C, H, W],或者 [N, C, D1, D2, …, Dn]

  • scale - 输入 gamma Op, 维度为 [C]

  • bias - 输入 beta Op,维度为 [C]

  • num_groups - 沿通道维度待划分的组数

  • epsilon - 为确保数值稳定性,在分母增加的值

  • layout - 描述输入 input 的 Layout

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Tuple Op,分别为 output, mean, rstd

  • output: 数据类型与维度与输入相同

  • mean: 每组的均值,维度为 [N, num_groups]

  • rstd: 每组的标准差,维度为 [N, num_groupss]

示例代码:

auto out = builder::GroupNorm(input, scale, bias, num_groups, eps, layout);

语义详见: GroupNorm

2.89. GroupNormGrad

builder::Op GroupNormGrad(builder::Op input,
                          builder::Op scale,
                          builder::Op mean,
                          builder::Op rstd,
                          builder::Op grad_output,
                          int64_t num_groups,
                          float epsilon,
                          builder::DimensionsLayout layout,
                          builder::Type result_type = builder::Type());

总结: 计算 GroupNorm 输入 input 的梯度。在训练过程中,输入梯度是根据输出梯度以及前向计算的属性,前向输出的 mean 和 rstd 进行计算的。

参数:
  • input - 输入 Op,维度为 [N, C, H, W],或者 [N, C, D1, D2, …, Dn]

  • scale - 输入 gamma Op, 维度为 [C]

  • mean - 前向计算的输出均值

  • rstd - 前向计算的输出标准差

  • grad_output - 输出的梯度

  • num_groups - 沿通道维度待划分的组数

  • epsilon - 为确保数值稳定性,在分母增加的值

  • layout - 描述输入 input 的 Layout

  • result_type - (可选)指定返回值的类型

返回值:
  • 输入的梯度

示例代码:

auto out = builder::GroupNormGrad(input, scale, mean, rstd, grad_output, num_groups, eps, layout);

语义详见: semantics-group_norm_grad

2.90. Gtu

builder::Op Gtu(builder::Op input,
                int64_t axis = -1,
                builder::Type result_type = builder::Type());

总结: 门 Tanh 单元函数 (Gated Tanh Unit function),语义参考 https://arxiv.org/abs/1612.08083,公式如下:

(2.90.1)\[{GTU}(a, b)= tanh(a) \otimes \sigma(b)\]
  • 输入按照给定的轴 axis 二等分,拆分后的前一半元素表示为 a , 后一半元素表示为 b 。 \(\sigma\) 表示 sigmoid 函数, \(\otimes\) 是 Hadamard 乘积。

参数:
  • input - 输入 Op

  • axis - (可选)指定分割轴,默认为 -1 表示输入 input 最后一维。 axis 的有效范围是 [-R, R),R 是每个输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型与输入 input 一致,在指定的轴上其维度减半。

示例代码:

auto out = builder::Gtu(input, axis);

语义详见: Gtu

2.91. HardSigmoid

builder::Op HardSigmoid(builder::Op input,
                        float slope = 0.1666667,
                        float offset = 0.5,
                        builder::Type result_type = builder::Type());

总结: hard sigmoid 激活函数。sigmoid 的分段线性逼近激活函数,速度比 sigmoid 快,参考文献: https://arxiv.org/abs/1603.00391

  • 默认情况下, slope = \(\frac{1}{6}\)offset = \(\frac{1}{2}\) ,计算公式如下:

(2.91.1)\[\begin{split}hard\_sigmoid\left ( x \right )=\left\{\begin{matrix} 0, & x\leq -3 \\ 1, & x\geq 3 \\ \frac{1}{6}\times x+\frac{1}{2}, & otherwise \\ \end{matrix}\right.\end{split}\]
  • 未指定 slopeoffset 时,计算公式如下:

(2.91.2)\[\begin{split}hard\_sigmoid\left ( x \right )=\left\{\begin{matrix} 0, & x\leq -\frac{offset}{slope} \\ 1, & x\geq \frac{1-offset}{slope} \\ slope\times x+offset, & otherwise \\ \end{matrix}\right.\end{split}\]
参数:
  • input - 输入 Op

  • slope - (可选) 默认为 0.1666667

  • offset - (可选) 默认为 0.5

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 一致。

示例代码:

auto out = builder::HardSigmoid(input, slope, offset);

语义详见: HardSigmoid

2.92. HardSigmoidGrad

builder::Op HardSigmoidGrad(builder::Op grad_output,
                            builder::Op output,
                            float slope,
                            builder::Type result_type = builder::Type());

总结: 计算 hard sigmoid 激活函数输入的梯度。

  • HardSigmoid 计算公式如下:

(2.92.1)\[\begin{split}hard\_sigmoid\left ( x \right )=\left\{\begin{matrix} 0, & x\leq -\frac{offset}{slope} \\ 1, & x\geq \frac{1-offset}{slope} \\ slope\times x+offset, & otherwise \\ \end{matrix}\right.\end{split}\]
  • 输入 input 梯度计算公式如下:

(2.92.2)\[grad\_input = grad\_output * (output > 0 \&\& output < 1) * slope\]
参数:
  • grad_output - 输出梯度 Op

  • output - 输出 Op

  • slope - HardSigmoid 属性参数

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度 Op,数据类型和维度与输入 input 一致。

示例代码:

auto grad_input = builder::HardSigmoidGrad(grad_output, output, slope);

语义详见: semantics-hard_sigmoid_grad

2.93. HardSwish

builder::Op HardSwish(builder::Op input,
                      builder::Type result_type = builder::Type());

总结: hardswish 激活函数。在 MobileNetV3 架构中被提出,相较于 swish 函数,具有数值稳定性好,计算速度快等优点。参考文献:https://arxiv.org/abs/1905.02244

(2.93.1)\[\begin{split}hard\_swish\left ( x \right )=\left\{\begin{matrix} 0, & x\leq -3 \\ x, & x\geq 3 \\ \frac{x\left ( x+3 \right )}{6}, & otherwise \\ \end{matrix}\right.\end{split}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 一致。

示例代码:

auto out = builder::HardSwish(input);

语义详见: HardSwish

2.94. HardSwishGrad

builder::Op HardSwishGrad(builder::Op grad_output,
                          builder::Op input,
                          float offset = 3.0,
                          float scale = 6.0,
                          float threshold = 6.0,
                          builder::Type result_type = builder::Type());

总结: 计算 hard swish 激活函数输入的梯度。

  • 标准 HardSwish 计算公式如下:

(2.94.1)\[\begin{split}hard\_swish\left ( x \right )=\left\{\begin{matrix} 0, & x\leq -3 \\ x, & x\geq 3 \\ \frac{x\left ( x+3 \right )}{6}, & otherwise \\ \end{matrix}\right.\end{split}\]
  • 泛化 HardSwish 计算如下:

(2.94.2)\[out = (x * (min(max(0, x + offset), threshold))) / scale\]
  • 输入 input 梯度计算公式如下:

(2.94.3)\[tmp1 = (input + offset) < threshold\]
(2.94.4)\[tmp2 = (in + offset) > 0\]
(2.94.5)\[grad\_input = grad\_output * (tmp2 * (2 * in + offset) / scale * tmp1 + 1 - tmp1)\]

Notice: 不兼容 PyTorch,原因是 x == 3 时,这里输出 grad_input 为 grad_output, 而 PyTorch 官方计算规则输出为 1.5 * grad_output。详情参考 https://github.com/pytorch/pytorch/issues/87778

参数:
  • grad_output - 输出梯度 Op

  • offset - (可选)默认为 3.0

  • slope - (可选)默认为 6.0

  • threshold - (可选)默认为 6.0

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度 Op,数据类型和维度与输入 input 一致。

示例代码:

auto grad_input = builder::HardSwishGrad(grad_output, input);

语义详见: semantics-hard_swish_grad

2.95. If

builder::Op If(builder::Op condition,
               std::vector<builder::Op> inputs,
               std::vector<const char*> region_list,
               builder::Type result_type = builder::Type());

总结: 参考 ONNX If 语义规则: https://github.com/onnx/onnx/blob/main/docs/Operators.md#If

Experimental: 实验性 API,暂时只用于 TopsInference 。

语义详见: If

2.96. Imag

builder::Op Imag(builder::Op input, builder::Type result_type = builder::Type());

总结: 返回包含输入复数 Op input 的虚部。

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,包含原复数 Op 的虚部数值

示例代码:

auto out = builder::Imag(input);

语义详见: Imag

2.97. InstanceNorm

builder::Op InstanceNorm(builder::Op input,
                         builder::Op scale,
                         builder::Op bias,
                         float epsilon,
                         builder::DimensionsLayout layout,
                         builder::Type result_type = builder::Type());

总结: 按照论文中的描述进行实例归一化,其中均值和方差时针对每个通道的每个实例进行计算的:https://arxiv.org/abs/1607.08022

(2.97.1)\[y = \frac{input - \mathrm{E}[input]}{\sqrt{\mathrm{Var}[input] + epsilon}} * scale + bias\]
参数:
  • input - 输入 Op,维度为 [N, C, H, W] / [N, H, W, C],或者 [N, C, D1, D2, …, Dn] / [N, D1, D2, …, Dn, C]

  • scale - 输入 gamma Op, 维度为 [C]

  • bias - 输入 beta Op,维度为 [C]

  • epsilon - 为确保数值稳定性,在分母增加的值

  • layout - 描述输入 input 的 Layout

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,数据类型和维度与输入相同

示例代码:

auto out = builder::InstanceNorm(input, scale, bias, epsilon, layout);

语义详见: InstanceNorm

2.98. Iota

builder::Op Iota(std::shared_ptr<builder::Builder> builder,
                 int64_t axis,
                 builder::Type result_type);

总结: 创建一个具有指定形状的数组,并保存从零开始并沿指定维度递增 1 的值。

参数:
  • builder - 全局 builder::Builder 对象共享指针

  • axis - 数据自增的维度,有效范围时 [-R, R) , R 是 result_type 的 Rank。如果 axis < 0 ,则 axis = axis + R。

  • result_type - 指定返回值的类型

返回值:
  • 输出 Op

示例代码:

// result_type: 2x3xi32
auto out = builder::Iota(builder, axis, result_type);
// axis = 0, out = [[0, 0, 0], [1, 1, 1], [2, 2, 2]]
// axis = 1, out = [[0, 1, 2], [0, 1, 2], [0, 1, 2]]

语义详见: Iota

2.99. IsFinite

builder::Op IsFinite(builder::Op input, builder::Type result_type = builder::Type());

总结: 测试输入 input 的每个元素是否是有限的,即不是正无穷大或负无穷大,并且不是 NaN 。返回与输入具有相同维度的 pred Op,其中诶个元素当且仅当相应的输入元素是有限的时才为 true 。

参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::IsFinite(input, result_type);

语义详见: IsFinite

2.100. LayerNorm

builder::Op LayerNorm(builder::Op input,
                      builder::Op scale,
                      builder::Op bias,
                      int64_t axis,
                      float epsilon,
                      builder::Type result_type);

总结: 按照论文中的描述进行层归一化:https://arxiv.org/abs/1607.06450

(2.100.1)\[y = \frac{input - \mathrm{E}[input]}{\sqrt{\mathrm{Var}[input] + epsilon}} * scale + bias\]

其中 \(\mathrm{E}[input]\)\(\mathrm{Var}[input]\) 计算如下:

(2.100.2)\[\begin{align}\begin{aligned}\begin{split}\\\mathrm{E}[input]=\frac{1}{H}\sum_{i=1}^{H}input_i\\\end{split}\\\begin{split}\\\mathrm{Var}[input]=\frac{1}{H}\sum_i^H{(input_i-\mathrm{E}[input])^2}\\\end{split}\end{aligned}\end{align}\]
参数:
  • input - 输入 Op

  • scale - 输入 gamma Op, 对归一化值进行缩放

  • bias - 输入 beta Op,归一化缩放值的偏差

  • axis - 指定 input 需进行层归一化的起始维度, input 将沿着 axis 到 Rank(input) 的维度进行层归一化。axis 的有效范围时 [-R, R) , R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致

  • epsilon - 为确保数值稳定性,在分母增加的值

  • result_type - 指定返回值的类型,如果设置为 tuple 类型,则必须包含 3 个元素,即 output type, mean type, rstd type;如果设置为非 tuple 类型,则只会返回一个输出,代表 output type。

返回值:

  • 输出非 Tuple Op,代表归一化的输出

  • 输出 Tuple Op,对输入进行层归一化的输出和更新后的参数,分别为 output, mean, rstd

    • output: 层归一化输出,数据类型和维度与输入 input 一致

    • mean: 每组的均值,数据类型与输入 input 一致,维度为 inputaxis 之前的维度,即 [input_dim_0, input_dim_1, …, input_dim_axis-1]

    • rstd: 每组的方差,数据类型与维度和输出 mean 一致

示例代码:

auto out = builder::LayerNorm(input, scale, bias, axis, epsilon);

语义详见: LayerNorm

2.101. LayerNormGrad

builder::Op LayerNormGrad(builder::Op input,
                          builder::Op scale,
                          builder::Op mean,
                          builder::Op rstd,
                          builder::Op grad_output,
                          int64_t axis,
                          float epsilon,
                          builder::Type result_type = builder::Type());

总结: 计算 LayerNorm 输入 input 的梯度。在训练过程中,输入梯度是根据输出梯度以及前向计算的属性,前向输出的 mean 和 rstd 进行计算的。

参数:
  • input - 输入 Op

  • scale - 输入 gamma Op, 对归一化值进行缩放

  • mean - 前向计算的输出均值

  • rstd - 前向计算的输出标准差

  • grad_output - 输出的梯度

  • axis - 指定 input 需进行层归一化的起始维度, input 将沿着 axis 到 Rank(input) 的维度进行层归一化。axis 的有效范围时 [-R, R) , R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致

  • epsilon - 为确保数值稳定性,在分母增加的值

  • result_type - (可选)指定返回值的类型

返回值:
  • 输入的梯度

示例代码:

auto out = builder::LayerNormGrad(input, scale, mean, rstd, grad_output, axis, epsilon);

语义详见: semantics-layer_norm_grad

2.102. LayerNormInference

builder::Op LayerNormInference(builder::Op input,
                               builder::Op scale,
                               builder::Op bias,
                               int64_t axis,
                               float epsilon,
                               builder::Type result_type);

总结: 层归一化,在推理场景使用。

[Deprecated API]: 已废弃,推荐使用 LayerNormLayerNormInferenceLayerNorm 区别是输出只有一个值, 因此 result_type 是可选值,默认通过 shape inference 推导。

2.103. LeakyRelu

builder::Op LeakyRelu(builder::Op input,
                      float alpha = 0.01,
                      builder::Type result_type = builder::Type());

总结: leaky_relu 激活函数,定义如下:

(2.103.1)\[leaky\_relu(input) = \begin{cases}input, &input >= 0; \cr alpha * input, &otherwise.\end{cases}\]
参数:
  • input - 输入 Op

  • alpha - input 的元素小于 0 时,激活函数的斜率,默认为 0.01

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 相同。

示例代码:

auto out = builder::LeakyRelu(input, alpha);

语义详见: LeakyRelu

2.104. LeakyReluGrad

builder::Op LeakyReluGrad(builder::Op grad_output,
                          builder::Op input,
                          float alpha = 0.01,
                          builder::Type result_type = builder::Type());

总结: 计算以下 leaky_relu 激活函数输入 input 的梯度:

(2.104.1)\[leaky\_relu(input) = \begin{cases}input, &input >= 0; \cr alpha * input, &otherwise.\end{cases}\]
(2.104.2)\[grad\_input = \begin{cases}grad\_output, &input >= 0; \cr alpha * grad\_output, &otherwise.\end{cases}\]
参数:
  • grad_output - LeakyRelu 输出的梯度

  • input - 输入 Op

  • alpha - input 的元素小于 0 时,激活函数的斜率,默认为 0.01

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 相同。

示例代码:

auto out = builder::LeakyReluGrad(grad_output, input, alpha);

语义详见: semantics-leaky_relu_grad

2.105. Less

builder::Op Less(builder::Op lhs,
                 builder::Op rhs,
                 std::vector<int64_t> broadcast_dimensions = {},
                 builder::Type result_type = builder::Type());

builder::Op operator<(builder::Op lhs, builder::Op rhs);

总结: 逐元素比较 lhs < rhs ,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator< 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Less(lhs, rhs);
auto out2 = builder::Less(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Less(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs < rhs;

语义详见: semantics-less

2.106. LessEqual

builder::Op LessEqual(builder::Op lhs,
                      builder::Op rhs,
                      std::vector<int64_t> broadcast_dimensions = {},
                      builder::Type result_type = builder::Type());

builder::Op operator<=(builder::Op lhs, builder::Op rhs)

总结: 逐元素比较 lhs <= rhs ,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator<= 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::LessEqual(lhs, rhs);
auto out2 = builder::LessEqual(lhs, rhs, broadcast_dimensions);
auto out3 = builder::LessEqual(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs <= rhs;

语义详见: semantics-less_equal

2.107. Log

builder::Op Log(builder::Op input, builder::Type result_type = builder::Type());

总结: 对输入 input ,逐元素计算自然对数

(2.107.1)\[\text{Log}(input) = ln(input) \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Log(input);
auto out2 = builder::Log(input, result_type);

语义详见: Log

2.108. Log1p

builder::Op Log1p(builder::Op input, builder::Type result_type = builder::Type());

总结: 对输入 input ,逐元素计算输入 + 1 的自然对数

(2.108.1)\[\text{Log1p}(input) = ln(input + 1) \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Log1p(input);
auto out2 = builder::Log1p(input, result_type);

语义详见: Log1p

2.109. Map

builder::Op Map(std::vector<builder::Op> inputs,
                std::vector<int64_t> dimensions,
                std::vector<const char*> region_list,
                builder::Type result_type = builder::Type());

总结: 在给定 inputs 输入上应用 region_list 指定的函数,生成相同维度的 Op。

参数:
  • inputs - 输入 Op

  • dimensions - 映射维度

  • region_list - 映射的函数

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Map(inputs, dimensions, region_list);

语义详见: Map

2.110. Max

builder::Op Max(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

总结: 逐元素比较 lhsrhs ,并且把各个位置更大的元素保存到返回 Op 中。

(2.110.1)\[out = max(lhs, rhs)\]
参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入一致,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Max(lhs, rhs);
auto out2 = builder::Max(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Max(lhs, rhs, broadcast_dimensions, result_type);

语义详见: Max

2.111. MaximumGrad

builder::Op MaximumGrad(builder::Op grad_output,
                        builder::Op lhs,
                        builder::Op rhs,
                        std::vector<int64_t> broadcast_dimensions = {},
                        builder::Type result_type = builder::Type());

总结: 计算以下 Max 输入的梯度

(2.111.1)\[out = max(lhs, rhs)\]
参数:
  • grad_output - Max 输出的梯度

  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto grad_inputs1 = builder::MaximumGrad(lhs, rhs);
auto grad_inputs2 = builder::MaximumGrad(lhs, rhs, broadcast_dimensions);
auto grad_inputs3 = builder::MaximumGrad(lhs, rhs, broadcast_dimensions, result_type);

语义详见: semantics-maximum_grad

2.112. MaxPool

builder::Op MaxPool(builder::Op input,
                    std::vector<int64_t> kernel_shape,
                    bool ceil_mode = false,
                    bool return_indices = false,
                    int64_t storage_order = 0,
                    std::vector<int64_t> strides = {},
                    std::vector<int64_t> padding = {},
                    std::vector<int64_t> dilations = {},
                    const char* auto_pad = nullptr,
                    builder::Type result_type = builder::Type());

builder::Op MaxPool(builder::Op input,
                    std::vector<int64_t> kernel_shape,
                    bool ceil_mode = false,
                    bool return_indices = false,
                    int64_t storage_order = 0,
                    std::vector<int64_t> strides = {},
                    std::vector<std::vector<int64_t>> padding = {{}},
                    std::vector<int64_t> dilations = {},
                    const char* auto_pad = nullptr,
                    builder::Type result_type = builder::Type());

总结: 在输入 input 上应用最大池化操作

参数:
  • input - 输入 Op

  • kernel_shape - 池化核大小。size 大小必须等于 input Rank

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • return_indices - 是否同步返回排序索引

  • storage_order - 暂未使用

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • dilations - 膨胀因子

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

// input: type = 1x1x5x5xf32, value = {1.0f, 2.0f, 3.0f, ..., 25.0f}
auto out = builder::MaxPool(input,
                            {1, 1, 2, 2},             // kernel_shape
                            true,                     // ceil_mode
                            false,                    // return_indices
                            0,                        // storage_order
                            {1, 1, 1, 1},             // strides
                            {0, 0, 0, 0, 0, 0, 0, 0}, // padding
                            {1, 1, 1, 1},             // dilation
                            "NOTSET"                  // auto_pad
                            );
// out: type = 1x1x4x4xf32, value = {7.0f,  8.0f,  9.0f, 10.0f,
//                                   12.0f, 13.0f, 14.0f, 15.0f,
//                                   17.0f, 18.0f, 19.0f, 20.0f,
//                                   22.0f, 23.0f, 24.0f, 25.0f}

语义详见: MaxPool

2.113. MaxPool1D

builder::Op MaxPool1D(builder::Op input,
                      std::vector<int64_t> kernel_size,
                      bool ceil_mode = false,
                      bool return_indices = false,
                      const char* auto_pad = nullptr,
                      const char* layout = nullptr,
                      std::vector<int64_t> stride = {},
                      std::vector<int64_t> padding = {},
                      std::vector<int64_t> dilation = {},
                      builder::Type result_type = builder::Type());

总结: 在输入 input 上应用 1-D 最大池化操作

参数:
  • input - 输入 Op

  • kernel_size - 池化核大小。size 大小必须等于 input Rank

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • return_indices - 是否同步返回排序索引

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • layout - (可选)支持 NLC 和 NCL, 默认 nullptr 指代 NLC

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • dilations - 膨胀因子

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

// input: type = 1x10x1xf32
auto out = builder::MaxPool(input,
                            {2},             // kernel_size
                            false,           // ceil_mode
                            false,           // return_indices
                            "NOTSET",        // auto_pad
                            "NLC",           // layout
                            {1},             // stride
                            {0, 0});         // padding

语义详见: semantics-max_pool1d

2.114. MaxPool2D

builder::Op MaxPool2D(builder::Op input,
                      std::vector<int64_t> kernel_size,
                      bool ceil_mode = false,
                      bool return_indices = false,
                      const char* auto_pad = nullptr,
                      const char* layout = nullptr,
                      std::vector<int64_t> stride = {},
                      std::vector<int64_t> padding = {},
                      std::vector<int64_t> dilation = {},
                      builder::Type result_type = builder::Type());

总结: 在输入 input 上应用 2-D 最大池化操作

参数:
  • input - 输入 Op

  • kernel_size - 池化核大小。size 大小必须等于 input Rank

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • return_indices - 是否同步返回排序索引。(暂不支持 return_indices = true)

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • layout - (可选)支持 NCHW 和 NHWC, 默认 nullptr 指代 NHWC

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • dilations - 膨胀因子

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

// input: type = 1x1x5x5xf32
auto out = builder::MaxPool(input,
                            {2, 2},             // kernel_size
                            false,              // ceil_mode
                            false,              // return_indices
                            "NOTSET",           // auto_pad
                            "NCHW",             // layout
                            {2, 2},             // stride
                            {0, 0, 0, 1});      // padding

语义详见: semantics-max_pool2d

2.115. MaxPool2DGrad

builder::Op MaxPool2DGrad(builder::Op grad_output,
                          builder::Op input,
                          std::vector<int64_t> kernel_size,
                          bool ceil_mode = false,
                          const char* auto_pad = nullptr,
                          const char* layout = nullptr,
                          std::vector<int64_t> stride = {},
                          std::vector<int64_t> padding = {},
                          std::vector<int64_t> dilation = {},
                          builder::Type result_type = builder::Type());

总结: 计算 MaxPool2D 输入 input 的梯度

参数:
  • grad_output - MaxPool2D 输出的梯度

  • input - 输入 Op

  • kernel_size - 池化核大小。size 大小必须等于 input Rank

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • layout - (可选)支持 NCHW 和 NHWC, 默认 nullptr 指代 NHWC

  • strides - 沿着每个池化轴的步长,默认为空,步长为 1。

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • dilations - 膨胀因子

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 数据类型相同。

示例代码:

auto out = builder::MaxPool2DGrad(grad_output, input, kernel_size);

语义详见: semantics-max_pool2d_grad

2.116. MaxRoiPool

builder::Op MaxRoiPool(builder::Op input,
                       builder::Op rois,
                       builder::DimensionsLayout layout,
                       std::vector<int64_t> pooled_shape,
                       float spatial_scale = 1.0,
                       builder::Type result_type = builder::Type());

总结: ROI 最大池化, 输入 input 在区域 rois 上应用最大池化

参数:
  • input - 输入 Op,维度为 [N, C, H, W] 或者 [N, H, W, C]

  • rois - 维度为 [num_rois, 5]的二维 Op

  • layout - 描述输入 input 的 layout,只支持 NCHW 或者 NHWC

  • pooled_shape - ROI 池化输出的 height 和 weight

  • spatial_scale - (可选)比例因子,用于将 ROI 坐标从输入比例转换为池化时使用

  • result_type - (可选)指定输出的类型

返回值:
  • ROI 池化输出,数据类型与输入 input 一致,维度为 [num_rois, C, pooled_shape[0], pooled_shape[1]]

示例代码:

auto out = builder::MaxRoiPool(input, rois, layout, pooled_shape)

语义详见: MaxRoiPool

2.117. Min

builder::Op Min(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

总结: 逐元素比较 lhsrhs ,并且把各个位置更小的元素保存到返回 Op 中。

(2.117.1)\[out = min(lhs, rhs)\]
参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入一致,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Min(lhs, rhs);
auto out2 = builder::Min(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Min(lhs, rhs, broadcast_dimensions, result_type);

语义详见: Min

2.118. MinimumGrad

builder::Op MinimumGrad(builder::Op grad_output,
                        builder::Op lhs,
                        builder::Op rhs,
                        std::vector<int64_t> broadcast_dimensions = {},
                        builder::Type result_type = builder::Type());

总结: 计算以下 Min 输入的梯度

(2.118.1)\[out = min(lhs, rhs)\]
参数:
  • grad_output - Min 输出的梯度

  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto grad_inputs1 = builder::MinimumGrad(lhs, rhs);
auto grad_inputs2 = builder::MinimumGrad(lhs, rhs, broadcast_dimensions);
auto grad_inputs3 = builder::MinimumGrad(lhs, rhs, broadcast_dimensions, result_type);

语义详见: semantics-minimum_grad

2.119. Mish

builder::Op Mish(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 Mish(Self Regularized Non-Monotonic Neural Avtivation Function 自正则化非单调神经激活函数)。

(2.119.1)\[mish(input) = input * tanh(softplus(input))\]
  • 这里会用到 softplus 函数,原始的 softplus 公式包含有不同的分支(参考 Softplus API ),这里属于其中一种,定义如下:

(2.119.2)\[softplus(input) = ln(1 + e^{input})\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out1 = builder::Mish(input);
auto out3 = builder::Mish(input, result_type);

语义详见: Mish

2.120. MeshGrid

builder::Op MeshGrid(std::vector<builder::Op> inputs,
                     const char* indexing = nullptr,
                     builder::Type result_type = builder::Type());

总结: 从给定的 Op 生成网格矩阵。给定 N 个 Rank 为 0 或 1 的输入 inputs ,对每个输入做扩张操作,返回 N 个 N 维的 Op。

参数:
  • inputs - 输入 Op

  • indexing - (可选)可选值为 ‘xy’ 或 ‘ij’ ,影响输出网格的维度,对于 Rank 为 M 和 N 的二维输入,取值为 ‘xy’ 时,输出的维度为 [N, M];取值为 ‘ij’ 时,输出的维度为 [M, N]。默认为 nullptr, 代表 ‘ij’

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Tuple Op,元素个数与输入 inputs 一致

示例代码:

auto out1 = builder::MeshGrid(inputs);
auto out2 = builder::MeshGrid(inputs, result_type);

语义详见: semantics-mesh_grid

2.121. Mul

builder::Op Mul(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator*(builder::Op lhs, builder::Op rhs);

总结: 逐元素计算输入 lhsrhs 的乘积, 并将各个位置的输出元素保存到返回结果中。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator* 获得相同的效果。

(2.121.1)\[Mul(lhs, rhs) = lhs * rhs \]
参数:
  • lhs - 需要相乘的左值

  • rhs - 需要相乘的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Mul(lhs, rhs);
auto out2 = builder::Mul(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Mul(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs * rhs;

语义详见: semantics-mul

2.122. MulGrad

builder::Op MulGrad(builder::Op grad_output,
                    builder::Op lhs,
                    builder::Op rhs,
                    std::vector<int64_t> broadcast_dimensions,
                    builder::Type result_type);

总结: 计算以下 Mul 输入的梯度

(2.122.1)\[Mul(lhs, rhs) = lhs * rhs \]
参数:
  • grad_output - Mul 输出的梯度

  • lhs - Mul 左输入

  • rhs - Mul 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto out1 = builder::MulGrad(grad_output, lhs, rhs);
auto out2 = builder::MulGrad(grad_output, lhs, rhs, broadcast_dimensions);
auto out3 = builder::MulGrad(grad_output, lhs, rhs, broadcast_dimensions, result_type);

语义详见: semantics-mul_grad

2.123. Neg

builder::Op Neg(builder::Op input, builder::Type result_type = builder::Type());

builder::Op operator-(builder::Op op);

总结: 逐元素计算输入 input 的相反数,也可使用重载运算符 operator- 获得相同的效果。

(2.123.1)\[Neg(input) = -input \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Neg(input);
auto out2 = builder::Neg(input, result_type);
auto out3 = -input;

语义详见: Neg

2.124. NMS

builder::Op NMS(builder::Op boxes,
                builder::Op scores,
                int64_t max_output_boxes_per_class = 0,
                float iou_threshold = 0.0,
                float score_threshold = 0.0,
                int32_t center_point_box = 0,
                builder::Type result_type = builder::Type());

总结: 非极大值抑制 (non-maximum suppression, NMS),API 定义参考 ONNX, 与 tf.non_max_suppression 兼容。

参数:
  • boxes - 输入 Op,维度为 [num_batches, boxes_num, 4]

  • scores - 与 boxes 对于的 score,维度为 [num_batches, num_classes, boxes_num]

  • max_output_boxes_per_class - 表示每个类别每个 batch 要选择的最大框数,如果值为 -1 , 表示不限制最大框数

  • iou_threshold - 代表判断框相对于 IOU 是否重叠过多的阈值,范围为 [0.0, 1.0]

  • score_threshold - 表示根据 score 决定何时删除框的阈值

  • center_point_box - 代表 boxes 的格式。0 表示 [y1, x1, y2, x2],其中 (y1, x1) 和 (y2, x2) 代表 box 任意对角线对的坐标,主要用于 TensorFlow;1 表示 [x_center, y_center, width, height],主要用于 PyTorch。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,被 NMS 保留的检测边界框的索引,维度为 [num_selected_indices, 3],格式为 [batch_index, class_index, box_index]

示例代码:

auto out1 = builder::NMS(boxes, scores);

语义详见: NMS

2.125. NonZero

builder::Op NonZero(builder::Op input, builder::Type result_type = builder::Type());

总结: 返回输入 input 中非零元素的索引坐标。

参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,Rank 为 2 ,维度为动态 Shape,即 [N, R],其中 N 为 input 中非零元素的个数, R 为输入 input 的 Rank。

示例代码:

auto out1 = builder::NonZero(input);

语义详见: NonZero

2.126. Not

builder::Op Not(builder::Op input, builder::Type result_type = builder::Type());

builder::Op operator!(builder::Op input);

总结: 逐元素对输入 input 进行逻辑非运算,也可使用重载运算符 operator- 获得相同的效果。

(2.126.1)\[Not(input) = !input \]
参数:
  • input - 输入 Op ,数据类型必须为 pred

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Not(input);
auto out2 = builder::Not(input, result_type);
auto out3 = !input;

语义详见: Not

2.127. NotEqual

builder::Op NotEqual(builder::Op lhs,
                     builder::Op rhs,
                     std::vector<int64_t> broadcast_dimensions = {},
                     builder::Type result_type = builder::Type());

builder::Op operator!=(builder::Op lhs, builder::Op rhs);

总结: 逐元素比较 lhsrhs 是否不相等,也可使用 Compare 进行等价构造。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator!= 获得相同的效果。

参数:
  • lhs - 需要比较的左值

  • rhs - 需要比较的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::NotEqual(lhs, rhs);
auto out2 = builder::NotEqual(lhs, rhs, broadcast_dimensions);
auto out3 = builder::NotEqual(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs != rhs;

语义详见: semantics-not_equal

2.128. OnesLike

// 语义参考 NumPy: https://numpy.org/doc/stable/reference/generated/numpy.ones_like.html

builder::Op OnesLike(
  builder::Op input,
  std::experimental::optional<builder::PrimitiveType> new_data_type = builder::nullopt,
  std::experimental::optional<std::vector<int64_t>> new_shapes = builder::nullopt);

builder::Op OnesLike(builder::Op input,
                     builder::PrimitiveType new_data_type,
                     const std::vector<int64_t> &new_shapes);

template <typename T>
builder::Op OnesLike(builder::Op input,
                     builder::PrimitiveType new_data_type,
                     const std::initializer_list<T>& new_shapes);

总结: 根据输入 input 对应的数据类型和维度信息,构造值全为 1 的 Const Op。常用使用方式为 builder::OnesLike(input),构造的输出 Op 数据类型,维度与输入 input 相同。 也可只利用 input 保存的全局 Builder 共享指针,自行设置数据类型和维度。

参数:
  • input - 参考的输入,默认会从 input 中获取保存的全局 Builder 共享指针,以及 input 的数据类型和维度信息。

  • new_data_type - 重新指定数据类型,不采用 input 的数据类型。

  • new_shapes - 重新指定维度信息,不采用 input 的维度信息。

返回值:
  • 输出 Const Op。

示例代码:

// input: tensor<1x3x224x224xf32>
auto out1 = builder::OnesLike(input);  // tensor<1x3x224x224xf32> value = 1.0f
auto out2 = builder::OnesLike(input,
                              builder::PrimitiveType::S32());  // tensor<1x3x224x224xi32> value = 1
std::vector<int64_t> new_shapes = {1};
auto out3 = builder::OnesLike(input,
                              builder::PrimitiveType::S32(), new_shapes);  // tensor<1xi32> value = 1
auto out4 = builder::OnesLike(input,
                              builder::PrimitiveType::S32(), {4});  // tensor<4xi32> value = 1

语义详见: semantics-ones_like

2.129. Or

builder::Op Or(builder::Op lhs,
               builder::Op rhs,
               std::vector<int64_t> broadcast_dimensions = {},
               builder::Type result_type = builder::Type());

builder::Op operator||(builder::Op lhs, builder::Op rhs);

总结: 逐元素对 lhsrhs 进行逻辑或运算。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator|| 获得相同的效果。

参数:
  • lhs - 需要运算的左值

  • rhs - 需要运算的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须为 pred ,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型为 pred ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Or(lhs, rhs);
auto out2 = builder::Or(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Or(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs || rhs;

语义详见: Or

2.130. Pad

builder::Op Pad(builder::Op input,
                builder::Op padding_value,
                int64_t mode,
                std::vector<int64_t> edge_padding_low,
                std::vector<int64_t> edge_padding_high,
                std::vector<int64_t> interior_padding,
                builder::Type result_type = builder::Type());

总结: 根据参数对输入 input 进行填充。

参数:
  • input - 需要填充的输入 Op

  • padding_value - 填充的数值 Op

  • mode - 填充模式,可选择 PAD_VALUE(0), PAD_EDGE(1), PAD_REFLECT(2), PAD_SYMMETRIC(3)。

  • edge_padding_low - 指定每个维度低端添加的填充量,负值的绝对值表示从指定维度中删除的元素数量。

  • edge_padding_high - 指定每个维度高端添加的填充量,负值的绝对值表示从指定维度中删除的元素数量。

  • interior_padding - 指定每个维度中任意两个元素之间添加的填充量。

  • result_type - (可选)指定返回值的类型

返回值:
  • 填充输出 Op

示例代码:

auto out = builder::Pad(input, pad_value, mode, pad_low, pad_high, pad_interior);

语义详见: Pad

2.131. PopulationCount

builder::Op PopulationCount(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算 pupulation count (又称bitsum, bitcount)。对于输入 input 中的每个元素,计算该元素二进制表示中 1 比特的数量。

参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::PopulationCount(input);

语义详见: PopulationCount

2.132. Pow

builder::Op Pow(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

总结: 逐元素计算输入 lhsrhs 次幂。

(2.132.1)\[pow(lhs, rhs) = lhs^{rhs}\]
参数:
  • lhs - 左操作数

  • rhs - 右操作数

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入 lhs 相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Pow(lhs, rhs);
auto out2 = builder::Pow(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Pow(lhs, rhs, broadcast_dimensions, result_type);

语义详见: Pow

2.133. PowGrad

builder::Op PowGrad(builder::Op grad_output,
                    builder::Op lhs,
                    builder::Op rhs,
                    std::vector<int64_t> broadcast_dimensions = {},
                    builder::Type result_type = builder::Type());

总结: 计算 Pow 输入 lhsrhs 的梯度

(2.133.1)\[pow(lhs, rhs) = lhs^{rhs}\]
参数:
  • grad_output - Max 输出的梯度

  • lhs - 输入左值

  • rhs - 输入右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto grad_inputs1 = builder::PowGrad(lhs, rhs);
auto grad_inputs2 = builder::PowGrad(lhs, rhs, broadcast_dimensions);
auto grad_inputs3 = builder::PowGrad(lhs, rhs, broadcast_dimensions, result_type);

语义详见: semantics-pow_grad

2.134. PRelu

builder::Op PRelu(builder::Op input,
                  builder::Op slope,
                  builder::Type result_type = builder::Type());

总结: PReLU 激活函数

(2.134.1)\[prelu(input) = max(0, input) + slope * min(0, input)\]
参数:
  • input - 激活函数输入 Op

  • slope - 权重输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out1 = builder::PRelu(input, slope);
auto out2 = builder::PRelu(input, slope, result_type);

语义详见: PRelu

2.135. Reciprocal

builder::Op Reciprocal(builder::Op input, builder::Type result_type = builder::Type());

总结: 对输入 input 取倒数

(2.135.1)\[out = \frac{1}{input}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Reciprocal(input);

语义详见: semantics-reciprocal

2.136. ReciprocalGrad

builder::Op ReciprocalGrad(builder::Op grad_output,
                           builder::Op output,
                           builder::Type result_type = builder::Type());

总结: 计算 Reciprocal 输入 input 的梯度

(2.136.1)\[Reciprocal(input) = \frac{1}{input}\]
(2.136.2)\[grad\_input = grad\_output * (-output^2)\]
参数:
  • grad_output - Reciprocal 输出的梯度

  • output - Reciprocal 输出 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输入的梯度

示例代码:

auto grad_input = builder::ReciprocalGrad(grad_output, output);

2.137. ReduceAll

builder::Op ReduceAll(builder::Op input,
                      builder::Op init_value,
                      std::vector<const char*> region_list,
                      const char* type = nullptr,
                      builder::Type result_type = builder::Type());

总结: 基于 Reduce 构造的 API 接口,对 input 所有维度都执行 region_list 指定的归约函数

参数:
  • input - 输入 Op

  • init_value - 归约函数的初始值

  • region_list - 归约函数名称,对应 Builder 类的 AddFunc 创建的函数。

  • type - 用于指定计算类型的可选属性,默认为空字符串。

  • result_type - (可选)指定返回值的类型

Notice: region_list 对应的 function 只支持 GT, LT, Add, Div, Mul, Or, And, Xor 这几种 Op。

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceAll(input, init_value, region_list);

语义详见: semantics-reduce_all

2.138. ReduceL2

builder::Op ReduceL2(builder::Op input,
                     bool keepdims = false,
                     std::vector<int64_t> axes = {},
                     builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的 L2 范数。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceL2(input, keepdims);

语义详见: semantics-reduce_l2

2.139. ReduceMax

builder::Op ReduceMax(builder::Op input,
                      bool keepdims = false,
                      std::vector<int64_t> axes = {},
                      builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的最大值。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceMax(input, keepdims);

语义详见: semantics-reduce_max

2.140. ReduceMean

builder::Op ReduceMean(builder::Op input,
                       bool keepdims = false,
                       std::vector<int64_t> axes = {},
                       builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的平均值。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceMean(input, keepdims);

语义详见: semantics-reduce_mean

2.141. ReduceMin

builder::Op ReduceMin(builder::Op input,
                      bool keepdims = false,
                      std::vector<int64_t> axes = {},
                      builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的最小值。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceMin(input, keepdims);

语义详见: semantics-reduce_min

2.142. ReduceProd

builder::Op ReduceProd(builder::Op input,
                       bool keepdims = false,
                       std::vector<int64_t> axes = {},
                       builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的乘积。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceProd(input, keepdims);

语义详见: semantics-reduce_prod

2.143. ReduceSum

builder::Op ReduceSum(builder::Op input,
                      bool keepdims = false,
                      std::vector<int64_t> axes = {},
                      builder::Type result_type = builder::Type());

总结: 沿指定轴 axes 计算输入 input 的和。如果 keepdims == 1 ,则返回 Op 与输入 input 的 Rank 相等,否则会进行降维剪枝。

参数:
  • input - 输入 Op

  • keepdims - 是否保留减少的维度,默认为 false 不保留

  • axes - (可选) Reduce 操作的维度,默认为空,表示所有维度都进行操作。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceSum(input, keepdims);

语义详见: semantics-reduce_sum

2.144. Range

builder::Op Range(builder::Op start,
                  builder::Op end,
                  builder::Op step,
                  builder::Type result_type = builder::Type());

总结: 返回从 start 开始,步长为 step,且不超过 end (不包括 end )的序列。

参数:
  • start - 区间起点 Op

  • end - 区间终点 Op

  • step - 均匀分割的步长

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Range(start, end, step);

语义详见: semantics-range

2.145. Real

builder::Op Real(builder::Op input, builder::Type result_type = builder::Type());

总结: 返回包含输入复数 Op input 的实部。

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,包含原复数 Op 的实部数值

示例代码:

auto out = builder::Real(input);

语义详见: Real

2.146. RealDynamicSlice

builder::Op RealDynamicSlice(builder::Op input,
                             builder::Op start_indices,
                             builder::Op limit_indices,
                             builder::Op strides,
                             std::vector<builder::Op> axes,
                             builder::Type result_type = builder::Type());

总结: Slice 的泛化版本,从动态 start_indices, limit_indices, stridesaxes 的输入 Op 中提取 Slice 切分的信息。

参数:
  • input - 输入 Op

  • start_indices - 表示 Slice 切分开始的索引信息, Rank 必须为 1 ,对应 axes 相应轴起始索引

  • limit_indices - 表示 Slice 切分结束的索引信息, Rank 必须为 1 ,对应 axes 相应轴结束索引(不包含)

  • strides - 表示 Slice 切分步长信息, Rank 必须为 1 , 负值意味着向后切分,值不能包含 0

  • axes - Slice 要切分的轴,有效范围是 [-R, R) ,R 是输入 input 的 Rank。 axis 为负数时,进行计算的 axisaxis + R 一致。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::RealDynamicSlice(input, start_indices, limit_indices, strides, axes);

语义详见: RealDynamicSlice

2.147. Reduce

builder::Op Reduce(std::vector<builder::Op> inputs,
                   std::vector<builder::Op> init_values,
                   std::vector<int64_t> dimensions,
                   std::vector<const char*> region_list,
                   const char* type = nullptr,
                   builder::Type result_type = builder::Type());

总结: 对一个或多个输入 inputs 应用归约函数

参数:
  • inputs - 输入 Op

  • init_values - 与输入 inputs 个数对应的标量类型

  • dimensions - 要进行归约操作的维度,不要求必须是有序的

  • region_list - 归约函数名称,对应 Builder 类的 AddFunc 创建的函数。

  • type - 用于指定计算类型的可选属性,默认为空字符串。

  • result_type - (可选)指定输出的类型

Notice: region_list 对应的 function 只支持 GT, LT, Add, Div, Mul, Or, And, Xor 这几种 Op。

返回值:
  • 输出 Op

示例代码:

auto out = builder::Reduce(inputs, init_values, dimensions, region_list);

语义详见: Reduce

2.148. ReduceWindow

builder::Op ReduceWindow(
    std::vector<builder::Op> inputs,
    std::vector<builder::Op> init_values,
    std::vector<int64_t> window_dimensions,
    std::vector<const char*> region_list,
    std::vector<int64_t> window_strides = {},
    std::vector<int64_t> base_dilations = {},
    std::vector<int64_t> window_dilations = {},
    std::vector<int64_t> padding = {},
    const char* auto_pad = nullptr,
    std::experimental::optional<bool> ceil_mode = builder::nullopt,
    builder::Type result_type = builder::Type());

builder::Op ReduceWindow(
    std::vector<builder::Op> inputs,
    std::vector<builder::Op> init_values,
    std::vector<int64_t> window_dimensions,
    std::vector<const char*> region_list,
    std::vector<int64_t> window_strides = {},
    std::vector<int64_t> base_dilations = {},
    std::vector<int64_t> window_dilations = {},
    std::vector<std::vector<int64_t>> padding = {{}},
    const char* auto_pad = nullptr,
    std::experimental::optional<bool> ceil_mode = builder::nullopt,
    builder::Type result_type = builder::Type());

总结: 将归约函数应用于 N 个 inputs 每个窗口中的所有元素。

参数:
  • inputs - 输入 Op

  • init_values - 与输入 inputs 个数对应的标量类型

  • window_dimensions - 窗口的维度大小

  • region_list - 归约函数名称,对应 Builder 类的 AddFunc 创建的函数。

  • window_strides - 窗口步长

  • base_dilations - 基本膨胀系数

  • window_dilations - 窗口膨胀系数

  • padding - 池化填充,格式为 [begin1, end1, begin2, end2, …],也可采用二维数组形式填充,格式为 [[begin1, end1], [begin2, end2], …]

  • auto_pad - 必须为 NOTSET、SAME_UPPER、SAME_LOWER 或 VALID。默认值为 NOTSET,即使用显式填充参数 padding

  • ceil_mode - 是否使用 ceil 或 Floor(默认)来计算输出形状。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReduceWindow(inputs, init_values, window_dimensions, region_list);

语义详见: ReduceWindow

2.149. Relu

builder::Op Relu(builder::Op input, builder::Type result_type = builder::Type());

总结: ReLU 激活函数(Rectified Linear Unit)

(2.149.1)\[ReLU(input) = max(0, input)\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Relu(input);

语义详见: Relu

2.150. ReluGrad

builder::Op ReluGrad(builder::Op grad_output,
                     builder::Op output,
                     builder::Type result_type = builder::Type());

总结: 计算 ReLU 激活函数输入的梯度

(2.150.1)\[ReLU(input) = max(0, input)\]
(2.150.2)\[grad\_input = \begin{cases}grad\_output, &output > 0; \cr 0, &otherwise.\end{cases}\]
参数:
  • grad_output - ReLU 输出的梯度

  • output - ReLU 输出 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输入的梯度

示例代码:

auto grad_input = builder::ReluGrad(grad_output, output);

语义详见: semantics-relu_grad

2.151. Relu6

builder::Op Relu6(builder::Op input, builder::Type result_type = builder::Type());

总结: ReLU6 激活函数

(2.151.1)\[ReLU6(input) = min(max(0, input), 6)\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Relu6(input);

语义详见: Relu6

2.152. Relu6Grad

builder::Op Relu6Grad(builder::Op grad_output,
                      builder::Op output,
                      builder::Type result_type = builder::Type());

总结: 计算 ReLU6 激活函数输入的梯度

(2.152.1)\[ReLU6(input) = min(max(0, input), 6)\]
(2.152.2)\[grad\_input = \begin{cases}grad\_output, &output > 0 \&\& output < 6; \cr 0, &otherwise.\end{cases}\]
参数:
  • grad_output - ReLU6 输出的梯度

  • output - ReLU6 输出 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输入的梯度

示例代码:

auto grad_input = builder::Relu6Grad(grad_output, input);

语义详见: semantics-relu6_grad

2.153. Rem

builder::Op Rem(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator%(builder::Op lhs, builder::Op rhs);

总结: 逐元素取模运算。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator% 获得相同的效果。

(2.153.1)\[Rem(lhs, rhs) = lhs \% rhs \]
参数:
  • lhs - 需要取模的左值

  • rhs - 需要取模的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Rem(lhs, rhs);
auto out2 = builder::Rem(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Rem(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs % rhs;

语义详见: Rem

2.154. Reshape

builder::Op Reshape(builder::Op input, builder::Type result_type);

builder::Op Reshape(builder::Op input, const std::vector<int64_t>& new_shape);

总结: 在保持输入 input 数据不变的情况下,改变 input 的维度信息

参数:
  • input - 输入 Op

  • result_type - 指定返回值的类型

  • new_shape - 指定返回值的维度

返回值:
  • 输出 Op

示例代码:

auto out1 = builder::Reshape(input, result_type);
auto out2 = builder::Reshape(input, new_shape);

语义详见: Reshape

2.155. Resize

builder::Op Resize(
  builder::Op input,
  builder::Op roi,
  builder::Op scales,
  builder::Op sizes,
  int64_t mode,
  int64_t coordinate_transformation_mode,
  bool exclude_outside,
  std::experimental::optional<int64_t> nearest_mode = builder::nullopt,
  std::experimental::optional<float> extrapolation_value = builder::nullopt,
  std::experimental::optional<float> cubic_coeff_a = builder::nullopt,
  std::vector<int64_t> resize_dimensions = {},
  builder::Type result_type = builder::Type());

总结: 将输入 input 调整为指定大小。

参数:
  • input - 输入 Op

  • roi - 一维 Op ,以 [start1, …, stratN, end1, …, endN] 形式给出,其中 N 是输入 input 的 Rank。 RoIs 坐标在输入图像的坐标系中标准化,仅当 mode 代表 tf_crop_and_resize 时生效

  • scales - 每个缩放维度的比例,与 sizes 参数不能同时指定,必须有一个以 builder::Const(builder, nullptr, type) 形式给出

  • sizes - 输出大小,与 scales 不能同时指定,必须有一个以 builder::Const(builder, nullptr, type) 形式给出

  • mode - 插值模式,支持 nearest(0), linear(1), cubic(2) 三种模式

  • coordinate_transformation_mode - 描述如何将输出的坐标转为原始输入的坐标

  • exclude_outside - 如果设置为 1 ,则输入 Op 之外的采样位置权重被设置为 0

  • nearest_mode - 支持四种模式 round_prefer_floor(0), round_prefer_ceil(1), floor(2), ceil(3)

  • extrapolation_value - 当 coordinate_transformation_mode 为 tf_crop_and_resize 且 x_original 超出范围 [0, length_original - 1] 时,该值用作相应的输出值。 默认值为 0.0f

  • cubic_coeff_a - 三次插值中使用的系数 a 。 两个常见的选择是 -0.5(在 TensorFlow 的某些情况下)和 -0.75(在 PyTorch 中)

  • resize_dimensions - 未使用,默认为空

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Resize(input, roi, scales, sizes, mode, coordinate_transformation_mode, exclude_outside);

语义详见: Resize

2.156. ResizeGrad

builder::Op ResizeGrad(
    builder::Op grad_output,
    builder::Op roi,
    builder::Op scales,
    builder::Op sizes,
    int64_t mode,
    int64_t coordinate_transformation_mode,
    bool exclude_outside,
    std::experimental::optional<int64_t> nearest_mode = builder::nullopt,
    std::experimental::optional<float> extrapolation_value = builder::nullopt,
    std::experimental::optional<float> cubic_coeff_a = builder::nullopt,
    builder::Type result_type = builder::Type());

总结: 计算 Resize 输入 input 的梯度

参数:
  • grad_output - Resize 输出的梯度

  • roi - 一维 Op ,以 [start1, …, stratN, end1, …, endN] 形式给出,其中 N 是输入 input 的 Rank。 RoIs 坐标在输入图像的坐标系中标准化,仅当 mode 代表 tf_crop_and_resize 时生效

  • scales - 每个缩放维度的比例,与 sizes 参数不能同时指定,必须有一个以 builder::Const(builder, nullptr, type) 形式给出

  • sizes - 输出大小,与 scales 不能同时指定,必须有一个以 builder::Const(builder, nullptr, type) 形式给出

  • mode - 插值模式,支持 nearest(0), linear(1), cubic(2) 三种模式

  • coordinate_transformation_mode - 描述如何将输出的坐标转为原始输入的坐标

  • exclude_outside - 如果设置为 1 ,则输入 Op 之外的采样位置权重被设置为 0

  • nearest_mode - 支持四种模式 round_prefer_floor(0), round_prefer_ceil(1), floor(2), ceil(3)

  • extrapolation_value - 当 coordinate_transformation_mode 为 tf_crop_and_resize 且 x_original 超出范围 [0, length_original - 1] 时,该值用作相应的输出值。 默认值为 0.0f

  • cubic_coeff_a - 三次插值中使用的系数 a 。 两个常见的选择是 -0.5(在 TensorFlow 的某些情况下)和 -0.75(在 PyTorch 中)

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ResizeGrad(grad_output, roi, scales, sizes, mode, coordinate_transformation_mode, exclude_outside);

语义详见: semantics-resize_grad

2.157. Reverse

builder::Op Reverse(builder::Op input,
                    std::vector<int64_t> dimensions,
                    builder::Type result_type = builder::Type());

总结: 沿指定维度 dimensions 翻转输入 input 中元素的顺序,生成相同维度的输出 Op

参数:
  • input - 输入 Op

  • dimensions - 需要翻转的维度

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Reverse(input, dimensions);

语义详见: Reverse

2.158. ReverseSequence

builder::Op ReverseSequence(builder::Op input,
                            builder::Op sequence_lens,
                            int64_t batch_axis = 1,
                            int64_t time_axis = 0,
                            builder::Type result_type = builder::Type());

总结: 反向批量翻转输入 input。对于批处理轴 batch_axis 上的每个切片,该运算按照 sequence_lens 指定的值,反转 time_axis 轴上的输入。

参数:
  • input - 输入 Op

  • sequence_lens - 指定输入在 batch_axis 上反转序列的长度

  • batch_axis - 指定哪个轴是批处理轴,必须为 0 或 1

  • batch_axis - 指定哪个轴是时间轴,必须为 0 或 1

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::ReverseSequence(input, sequence_lens, batch_axis, time_axis);
// input = [[0.0, 4.0, 8.0,  12.0],
//          [1.0, 5.0, 9.0,  13.0],
//          [2.0, 6.0, 10.0, 14.0],
//          [3.0, 7.0, 11.0, 15.0]]
// sequence_lens = [4, 3, 2, 1] time_axis = 0 batch_axis = 1
// output = [[3.0, 6.0, 9.0,  12.0],
//           [2.0, 5.0, 8.0,  13.0],
//           [1.0, 4.0, 10.0, 14.0],
//           [0.0, 7.0, 11.0, 15.0]]

// input = [[0.0,  1.0,  2.0,  3.0 ],
//          [4.0,  5.0,  6.0,  7.0 ],
//          [8.0,  9.0,  10.0, 11.0],
//          [12.0, 13.0, 14.0, 15.0]]
// sequence_lens = [1, 2, 3, 4] time_axis = 1 batch_axis = 0
// output = [[0.0,  1.0,  2.0,  3.0 ],
//           [5.0,  4.0,  6.0,  7.0 ],
//           [10.0, 9.0,  8.0,  11.0],
//           [15.0, 14.0, 13.0, 12.0]]

语义详见: ReverseSequence

2.159. RngNormal

builder::Op RngNormal(
    builder::Op mu,
    builder::Op sigma,
    builder::Op shape,
    std::vector<builder::Op> seed_and_offset = {},
    std::experimental::optional<int64_t> seed = builder::nullopt,
    builder::Type result_type = builder::Type());

总结: 使用遵循 N(mu, sigma) 的正态分布生成随机输出

参数:
  • mu - 标量类型,指定生成数的平均值

  • sigma - 标量类型,指定生成数的标准差

  • shape - 指定输出维度大小

  • seed_and_offset - 暂时未使用,默认为 {}

  • seed - 用于设置随机数生成器

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::RngNormal(mu, sigma, shape);

语义详见: RngNormal

2.160. RngUniform

builder::Op RngUniform(
    builder::Op a,
    builder::Op b,
    builder::Op shape,
    std::vector<builder::Op> seed_and_offset = {},
    std::experimental::optional<int64_t> seed = builder::nullopt,
    builder::Type result_type = builder::Type());

总结: 生成 [a, b) 的平均分布

参数:
  • a - 平均分布左值

  • b - 平均分布右值

  • shape - 指定输出维度大小

  • seed_and_offset - 暂时未使用,默认为 {}

  • seed - 用于设置随机数生成器

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::RngUniform(a, b, shape);

语义详见: RngUniform

2.161. RoiAlign

builder::Op RoiAlign(builder::Op input,
                     builder::Op rois,
                     builder::Op batch_indices,
                     builder::DimensionsLayout layout,
                     int64_t coordinate_transformation_mode = 0,
                     int64_t mode = 0,
                     int64_t output_height = 1,
                     int64_t output_width = 1,
                     int64_t sampling_ratio = 0,
                     float spatial_scale = 1.0,
                     builder::Type result_type = builder::Type());

总结: 感兴趣区域对齐算子,是对非均匀大小的输入执行双线性插值,获得固定大小的特征图。

参数:
  • input - 输入的特征图

  • rois - 待hi行池化的 RoIs(Regions of Interest) 框坐标

  • batch_indices - 该 batch 中每一张图所包含的框数量

  • layout - input layout 信息

  • coordinate_transformation_mode - 坐标偏移模式,可选 half_pixel(0), output_half_pixel(1)

  • mode - 池化模式,可选 avg(0) 或者 max(1)

  • output_height - 池化输出的高

  • output_width - 池化输出的宽

  • sampling_ratio - 插值网格中用于计算每个池化输出条柱输出值的采样点数

  • spatial_scale - 空间比例因子

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::RoiAlign(input, rois, batch_indices, layout);

语义详见: RoiAlign

2.162. RoiAlignGrad

builder::Op RoiAlignGrad(builder::Op grad_output,
                         builder::Op input,
                         builder::Op rois,
                         builder::Op batch_indices,
                         builder::DimensionsLayout layout,
                         int64_t coordinate_transformation_mode = 0,
                         int64_t mode = 0,
                         int64_t output_height = 1,
                         int64_t output_width = 1,
                         int64_t sampling_ratio = 0,
                         float spatial_scale = 1.0,
                         builder::Type result_type = builder::Type());

总结: RoiAlign 输入 input 的梯度

参数:
  • grad_output - 输出的梯度

  • input - 输入的特征图

  • rois - 待hi行池化的 RoIs(Regions of Interest) 框坐标

  • batch_indices - 该 batch 中每一张图所包含的框数量

  • layout - input layout 信息

  • coordinate_transformation_mode - 坐标偏移模式,可选 half_pixel(0), output_half_pixel(1)

  • mode - 池化模式,可选 avg(0) 或者 max(1)

  • output_height - 池化输出的高

  • output_width - 池化输出的宽

  • sampling_ratio - 插值网格中用于计算每个池化输出条柱输出值的采样点数

  • spatial_scale - 空间比例因子

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto grad_input = builder::RoiAlignGrad(grad_output, input, rois, batch_indices, layout);

语义详见: semantics-roi_align_grad

2.163. Roll

builder::Op Roll(builder::Op input,
                 std::vector<int64_t> shifts,
                 std::vector<int64_t> axes = {},
                 builder::Type result_type = builder::Type());

总结: 沿着指定维度 axes 对输入 input 进行循环滚动,当元素移动到最后位置时,会从第一个位置重新插入。

参数:
  • input - 输入 Op

  • shifts - 滚动位移

  • axes - 滚动轴

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Roll(input, shifts, axes);
// input = [[1.0, 2.0, 3.0],
//          [4.0, 5.0, 6.0],
//          [7.0, 8.0, 9.0]]
// shifts = 1
// output = [[9. 1. 2.]
//           [3. 4. 5.]
//           [6. 7. 8.]]

// shifts = 1, axis = 0
// output = [[7. 8. 9.]
//           [1. 2. 3.]
//           [4. 5. 6.]]

// shifts = 1, axis = 1
// output = [[3. 1. 2.]
//           [6. 4. 5.]
//           [9. 7. 8.]]

语义详见: semantics-roll

2.164. RollGrad

builder::Op RollGrad(builder::Op grad_output,
                     std::vector<int64_t> shifts,
                     std::vector<int64_t> axis = {},
                     builder::Type result_type = builder::Type());

总结: 计算 Roll 输入的梯度

参数:
  • grad_output - Roll 输出的梯度

  • shifts - 滚动位移

  • axes - 滚动轴

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto grad_input = builder::RollGrad(grad_output, shifts, axes);

语义详见: semantics-roll_grad

2.165. Round

builder::Op Round(builder::Op input, builder::Type result_type = builder::Type());

总结: 将输入中的数值四舍五入到最接近的整数数值

参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Round(input);

语义详见: Round

2.166. RoundNearestEven

builder::Op RoundNearestEven(builder::Op input, builder::Type result_type = builder::Type());

总结: 将输入中的数值四舍五入到最接近的偶数

参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::RoundNearestEven(input);

语义详见: RoundNearestEven

2.167. Rsqrt

builder::Op Rsqrt(builder::Op input, builder::Type result_type = builder::Type());

总结: rsqrt 激活函数

(2.167.1)\[out = \frac{1}{\sqrt{input}}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Rsqrt(input);

语义详见: Rsqrt

2.168. Scatter

builder::Op Scatter(builder::Op input,
                    builder::Op scatter_indices,
                    builder::Op updates,
                    builder::ScatterDimensionNumbers scatter_dimension_numbers,
                    std::vector<const char*> region_list,
                    bool indices_are_sorted = false,
                    bool unique_indices = false,
                    builder::Type result_type = builder::Type());

总结: 通过基于 updates 来更新选定索引 scatter_indices 上的输入来获得输出

参数:
  • input - 输入 Op

  • scatter_indices - 指定 scatter slice 操作开始的索引

  • updates - 要更新的值

  • scatter_dimension_numbers - Scatter 索引操作属性

  • region_list - 用于组合输入 input 中的值和 Scatter 分散更新值的计算操作

  • indices_are_sorted - 是否保证调用者对索引进行排序

  • unique_indices - 是否保证索引唯一无重复

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Scatter(input, scatter_indices, updates, scatter_dimension_numbers, region_list);

语义详见: ScatterND

2.169. ScatterND

builder::Op ScatterND(builder::Op input,
                      builder::Op indices,
                      builder::Op updates,
                      builder::Type result_type = builder::Type());

总结: 接收三个输入, Rank 为 R >= 1 的数据 Op,Rank 为 Q >= 1 的索引 Op,并更新 Rank 为 Q + R - indices.shape[-1] -1 的 Op, 语义来自 ONNX。

参数:
  • input - 输入 Op

  • indices - 索引 Op,当值包含负数时,计算结果未定义,与算子实现有关:算子实现上有可能直接返回,即不处理 indices 包含负数的情况,也有可能会修正 indices 的负值。

  • updates - 要更新的值

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::ScatterND(input, indices, updates);

语义详见: semantics-scatter_nd

2.170. Select

builder::Op Select(builder::Op condition,
                   builder::Op on_true,
                   builder::Op on_false,
                   builder::Type result_type = builder::Type());

总结: 根据 condition 来选择 on_trueon_false 中的对应元素来组成新的 Op

参数:
  • condition - 选择条件,数据类型必须为 pred

  • on_true - 条件为真时选择的 Op

  • on_false - 条件为假时选择的 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Select(condition, on_true, on_false);

语义详见: Select

2.171. SelectGrad

builder::Op SelectGrad(builder::Op grad_output,
                       builder::Op condition,
                       builder::Type result_type = builder::Type());

总结: 计算 Select 两个输入 on_trueon_false 的梯度

参数:
  • grad_output - Select 输出的梯度

  • condition - 选择条件,数据类型必须为 pred

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Tuple Op,两个元素分别代表 on_trueon_false 的梯度

示例代码:

auto output = builder::SelectGrad(grad_output, condition);

语义详见: semantics-select_grad

2.172. SelectAndScatter

builder::Op SelectAndScatter(builder::Op input,
                             builder::Op source,
                             builder::Op init_value,
                             std::vector<const char*> region_list,
                             std::vector<int64_t> window_dimensions = {},
                             std::vector<int64_t> window_strides = {},
                             std::vector<int64_t> padding = {},
                             builder::Type result_type = builder::Type());

builder::Op SelectAndScatter(builder::Op input,
                             builder::Op source,
                             builder::Op init_value,
                             std::vector<const char*> region_list,
                             std::vector<int64_t> window_dimensions = {},
                             std::vector<int64_t> window_strides = {},
                             std::vector<std::vector<int64_t>> padding = {{}},
                             builder::Type result_type = builder::Type());

总结: 复合操作,首先在输入 input 上计算 ReduceWindow,以从每个窗口中选择一个元素,然后将 source 分散到所选元素的索引,以构造与输入 input 有相同维度形状的输出 Op

参数:
  • input - 输入 Op

  • source - 需要分散操作的源 Op

  • init_value - 输出在分散索引位置的初始值

  • region_list - 更新分散索引位置的函数,对应 BuilderAddFunc 创建的函数名称。

  • window_dimensions - ReduceWindow 窗口维度

  • window_strides - ReduceWindow 步长

  • padding - ReduceWindow 填充方式

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::SelectAndScatter(input, source, init_value, region_list);

语义详见: SelectAndScatter

2.173. SetDimensionSize

builder::Op SetDimensionSize(builder::Op input,
                             builder::Op size,
                             int32_t dimension,
                             builder::Type result_type = builder::Type());

总结: 设置输入 input 指定维度 dimension 的动态大小 size

参数:
  • input - 输入 Op

  • size - 标量或 Rank = 1 只包含一个值的 Op,代表运行时动态的 size 大小

  • dimension - 指定输入 input 要更新的维度,有效范围为 [0, R) , R 为输入的 Rank

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::SetDimensionSize(input, size, dimension);

语义详见: SetDimensionSize

2.174. Shape

builder::Op Shape(builder::Op input,
                  int64_t start = 0,
                  int64_t end = LLONG_MAX,
                  builder::Type result_type = builder::Type());

总结: 获取输入 input 的维度大小

参数:
  • input - 输入 Op

  • start - (可选)用于切割形状的起始轴,默认为 0 。

  • end - (可选)用于切割形状的结束轴,默认为 LLONG_MAX,代表包括直到最后一个轴的所有轴维度。

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Shape(input);

语义详见: Shape

2.175. ShiftLeft

builder::Op ShiftLeft(builder::Op lhs,
                      builder::Op rhs,
                      std::vector<int64_t> broadcast_dimensions = {},
                      builder::Type result_type = builder::Type());

builder::Op operator<<(builder::Op lhs, builder::Op rhs);

总结:lhs 操作数进行左移位 rhs。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator<< 获得相同的效果。

参数:
  • lhs - 左输入

  • rhs - 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op

示例代码:

auto output = builder::ShiftLeft(lhs, rhs);

语义详见: ShiftLeft

2.176. ShiftRightArithmetic

builder::Op ShiftRightArithmetic(builder::Op lhs,
                                 builder::Op rhs,
                                 std::vector<int64_t> broadcast_dimensions = {},
                                 builder::Type result_type = builder::Type());

总结:lhs 操作数进行算数右移 rhs

参数:
  • lhs - 左输入

  • rhs - 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op

示例代码:

auto output = builder::ShiftRightArithmetic(lhs, rhs);

语义详见: ShiftRightArithmetic

2.177. ShiftRightLogical

builder::Op ShiftRightLogical(builder::Op lhs,
                              builder::Op rhs,
                              std::vector<int64_t> broadcast_dimensions = {},
                              builder::Type result_type = builder::Type());

builder::Op operator>>(builder::Op lhs, builder::Op rhs);

总结:lhs 操作数进行逻辑右移 rhs。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator>> 获得相同的效果。

参数:
  • lhs - 左输入

  • rhs - 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op

示例代码:

auto output = builder::ShiftRightLogical(lhs, rhs);

语义详见: ShiftRightLogical

2.178. Sigmoid

builder::Op Sigmoid(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 Sigmoid 激活函数

(2.178.1)\[sigmoid(input)=\frac{1}{1+e^{-input}}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Sigmoid(input);

语义详见: Sigmoid

2.179. SigmoidGrad

builder::Op SigmoidGrad(builder::Op grad_output,
                        builder::Op output,
                        builder::Type result_type = builder::Type());

总结: 计算 Sigmoid 激活函数输入的梯度

(2.179.1)\[sigmoid(input)=\frac{1}{1+e^{-input}}\]
(2.179.2)\[grad\_input = grad\_output * output * (1 - output)\]
参数:
  • grad_output - 输出的梯度

  • output - Sigmoid 的输出

  • result_type - (可选)指定返回值的类型

返回值:
  • 输入的梯度

示例代码:

auto grad_input = builder::SigmoidGrad(grad_output, output);

语义详见: semantics-sigmoid_grad

2.180. Sign

builder::Op Sign(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素判断输入 input 的正负,输出正负判断值

(2.180.1)\[\begin{split}sign(x)=\begin{cases} -1, & \text{ if } x<0 \\ 0, & \text{ if } x=0 \\ 1, & \text{ if } x>0 \end{cases}\end{split}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Sign(input);

语义详见: Sign

2.181. Sin

builder::Op Sin(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的正弦

(2.181.1)\[Sin(input)=std::sin(input) \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Sin(input);
auto out2 = builder::Sin(input, result_type);

语义详见: Sin

2.182. Sinh

builder::Op Sinh(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的双曲正弦函数

(2.182.1)\[sinh(input)=\frac{e^{input}-e^{-input}}{2} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Sinh(input);
auto out2 = builder::Sinh(input, result_type);

语义详见: Sinh

2.183. Silu

builder::Op Silu(builder::Op input,
                 float beta = 1.0,
                 builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 SiLU 或者 Swish 激活函数

(2.183.1)\[SiLU(input) = \frac{input}{1 + e^{-beta * input}}\]
参数:
  • input - 输入 Op

  • beta - (可选) 默认 beta = 1.0f, SiLU 公式等价于 \(input * sigmoid(input)\) ,即 Swish

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Silu(input);
auto out2 = builder::Silu(input, 1.0);

语义详见: Silu

2.184. SiluGrad

builder::Op SiluGrad(builder::Op grad_output,
                     builder::Op input,
                     float beta = 1.0,
                     builder::Type result_type = builder::Type());

总结: 计算 Silu 输入的梯度

(2.184.1)\[SiLU(input) = \frac{input}{1 + e^{-beta * input}}\]
(2.184.2)\[tmp1 = e^{-input} + 1\]
(2.184.3)\[tmp2 = e^{-input} * input\]
(2.184.4)\[grad\_input = grad\_output * \frac{1}{tmp1} * (1 + \frac{tmp2}{tmp1})\]
参数:
  • grad_output - Silu 输出的梯度

  • input - 输入 Op

  • beta - (可选) 默认 beta = 1.0f, SiLU 公式等价于 \(input * sigmoid(input)\)

  • result_type - (可选)指定输出的类型

返回值:
  • 输入的梯度

示例代码:

auto grad_input = builder::SiluGrad(grad_output, input);

语义详见: semantics-silu_grad

2.185. Size

builder::Op Size(builder::Op input, builder::Type result_type = builder::Type());

总结: 计算输入 input 中包含元素的总数

参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Size(input);

语义详见: Size

2.186. Slice

builder::Op Slice(builder::Op input,
                  std::vector<int64_t> start_indices,
                  std::vector<int64_t> end_indices,
                  std::vector<int64_t> strides,
                  builder::Type result_type = builder::Type());

总结: 沿输入 input 的每个轴生成切片。使用 start_indices, end_indices, strides 属性来指定每个轴的起点,终点和步长信息。

参数:
  • input - 输入 Op

  • start_indices - 起点

  • end_indices - 终点(不包含)

  • strides - 步长

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Slice(input, start_indices, end_indices, strides);

语义详见: Slice

2.187. SliceInDim

builder::Op SliceInDim(builder::Op input,
                       int64_t start_index,
                       int64_t end_index,
                       int64_t stride,
                       int64_t dim,
                       builder::Type result_type = builder::Type());

总结: 沿输入 input 的轴 dim 进行切片。使用 start_index, end_index, stride 属性来指定起点,终点和步长信息。

参数:
  • input - 输入 Op

  • start_index - 起点

  • end_index - 终点(不包含)

  • stride - 步长

  • dim - 切片的轴,有效范围是 [-R, R) ,其中 R 代表 input 的 Rank。 如果 axis < 0 ,则 axis = axis + R。

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::SliceInDim(input, start_index, end_index, stride, dim);

语义详见: SliceInDim

2.188. Softmax

builder::Op Softmax(builder::Op input,
                    int64_t axis = -1,
                    bool accurate = false,
                    bool logarithmic = false,
                    float epsilon = 0,
                    builder::Type result_type = builder::Type());

总结: softmax 激活函数,支持 log_softmax 以及平滑 softmax

参数:
  • input - 输入 Op

  • axis - 指定轴

  • accurate - 是否采用平滑 softmax。如果 accurate = true,它将找到沿指定轴的最大值,并从沿指定轴的每个元素中减去最大值

  • logarithmic - 默认为 false,采用 softmax;当设置为 true 时,变为 log_softmax

  • epsilon - 为确保数值稳定性,在分母增加的值

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 一致

示例代码:

auto output = builder::Softmax(input);

语义详见: Softmax

2.189. Softplus

builder::Op Softplus(
    builder::Op input,
    std::experimental::optional<int64_t> beta = builder::nullopt,
    std::experimental::optional<int64_t> threshold = builder::nullopt,
    builder::Type result_type = builder::Type());

总结: softplus 激活函数,根据 beta , threshold 的设置走不同的计算逻辑

  • 如果设置了 threshold 属性,公式如下:

(2.189.1)\[\begin{split}softplus(input)=\begin{cases} \frac{1}{\beta} * \log(1 + e^{beta * input}),&input*beta<=threshold;\\ input,&input*beta>threshold. \end{cases}\end{split}\]
  • 如果未设置 threshold 属性,公式如下:

(2.189.2)\[softplus(input) = \log(1 + e^{beta * input})\]
参数:
  • input - 输入 Op

  • beta - (可选) 默认为 1

  • threshold - (可选)默认未设置

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型和维度与输入 input 一致

示例代码:

auto output = builder::Softplus(input);

语义详见: Softplus

2.190. Sort

builder::Op Sort(std::vector<builder::Op> inputs,
                 std::vector<const char*> region_list,
                 int64_t axis = -1,
                 bool is_stable = false,
                 builder::Type result_type = builder::Type());

总结: 对输入 inputs 进行排序。如果 inputs 只提供一个输入,它将按照升序或降序对指定维度 dimension 进行排序。如果提供多个输入,它将所有输入排序在一起(仅比较第一个 Op 中的元素)

参数:
  • inputs - 输入 Op

  • region_list - 排序函数,只支持 > 或者 < 两种排序规则

  • axis - 排序的轴维度,有效范围是 [-R, R) ,其中 R 代表 inputs[0] 的 Rank。 如果 axis < 0 ,则 axis = axis + R。默认为 -1

  • is_stable - 是否采用稳定排序

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Sort(inputs, region_list);

语义详见: Sort

2.191. SpaceToDepth

builder::Op SpaceToDepth(builder::Op input,
                         std::vector<int64_t> space_dims,
                         int64_t depth_dim,
                         int64_t block_size,
                         builder::Type result_type = builder::Type());

总结: 将空间维度数据重新排列到深度中,是 DepthtOSpace 的反向操作。

参数:
  • input - 输入 Op,必须为四维。

  • space_dims - 输入 Op 的空间维度:输入为 NCHW 时, space_dims 设置为 {2, 3};输入为 NHWC 时, space_dims 设置为 {1, 2}

  • depth_dim - 输入 Op 的深度维度:输入为 NCHW 时, depth_dim 设置为 1;输入为 NHWC 时, depth_dim 设置为 3

  • block_size - 用于划分深度数据的块大小,其值必须 >= 2

  • result_type - 指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::SpaceToDepth(input, space_dims, depth_dim, block_size);

语义详见: SpaceToDepth

2.192. Split

builder::Op Split(builder::Op input,
                  builder::Op split,
                  int64_t axis = 0,
                  int64_t num_outputs = 0,
                  builder::Type result_type = builder::Type());

总结: 根据指定的轴 axis 将输入 input 切分成多个 Op

参数:
  • input - 输入 Op

  • split - 切分的具体信息

  • axis - 切分的轴

  • num_outputs - 切分的输出个数,如果指定了 num_outputs,输入会被等分切分。如果 input 不能等分切分,那么最后一次切分块的大小会稍小一些。

  • result_type - 指定输出的类型

限制:
  • splitnum_outputs 同时设置时,会采用 num_outputs 设置的内容

  • split 只支持 Rank 为 0 或 1,数据类型为 int32 或 int64,而且必须可常量折叠为 Const Op

返回值:
  • 输出 Tuple Op

示例代码:

// 1. 采用 split 进行切分
// auto split = builder::Const(builder, value, builder::Type(builder::PrimitiveType::S32()))
auto out = builder::Split(input, split, axis, num_outputs/* = 0, or < 0*/);

// 2. 采用 num_outputs 进行切分
// builder::Op split; // 构造默认未初始化的 Op
auto out = builder::Split(input, split, axis, num_outputs/* > 0*/);

语义详见: semantics-split

2.193. Sqrt

builder::Op Sqrt(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的算数平方根

(2.193.1)\[out=\sqrt {input}=input^{1/2} \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Sqrt(input);
auto out2 = builder::Sqrt(input, result_type);

语义详见: Sqrt

2.194. Square

builder::Op Square(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的平方

(2.194.1)\[out = input^2 \]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Square(input);
auto out2 = builder::Square(input, result_type);

语义详见: semantics-square

2.195. SquareGrad

builder::Op SquareGrad(builder::Op grad_output,
                       builder::Op input,
                       builder::Type result_type = builder::Type());

总结: 计算 Square 输入的梯度

(2.195.1)\[grad\_input = grad\_output * 2 * input \]
参数:
  • grad_output - 输出的梯度

  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度

示例代码:

auto grad_input1 = builder::SquareGrad(grad_output, input);
auto grad_input2 = builder::SquareGrad(grad_output, input, result_type);

语义详见: semantics-square_grad

2.196. Squeeze

builder::Op Squeeze(builder::Op input,
                    builder::Op axes,
                    builder::Type result_type = builder::Type());

总结: 删除输入 input 的 Shape 中指定维度 axes ,尺寸大小为 1 的维度。

参数:
  • input - 输入 Op

  • axes - 指定维度

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度

示例代码:

auto out = builder::Squeeze(input, axes);

语义详见: Squeeze

2.197. Stack

builder::Op Stack(std::vector<builder::Op> inputs,
                  int64_t axis = 0,
                  builder::Type result_type = builder::Type());

总结: 沿轴 axis 对所有输入 inputs 进行堆叠操作,要求所有输入右相同的 Shape 和数据类型。

参数:
  • inputs - 输入 Op

  • axis - (可选)指定对输入进行堆叠的轴,有效范围是 [-(R+1), R+1] ,其中 R 代表第一个输入的 Rank。 如果 axis < 0 ,则 axis = axis + R + 1。默认为 0

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Stack(inputs);

语义详见: semantics-stack

2.198. StackGrad

builder::Op StackGrad(builder::Op grad_output,
                      int64_t axis = 0,
                      builder::Type result_type = builder::Type());

总结: 计算 Stack 输入的梯度,沿 axisgrad_output 切分为多个 Op

参数:
  • grad_output - 输出的梯度

  • axis - (可选)指定切分的轴,有效范围是 [-R, R) ,其中 R 代表 grad_output 的 Rank。 如果 axis < 0 ,则 axis = axis + R。默认为 0

  • result_type - (可选)指定输出的类型

返回值:
  • 输入的梯度,为 Tuple Op,元素个数对应 grad_output 维度对应 axis 的 dim 数值

示例代码:

auto grad_inputs = builder::StackGrad(grad_output, axis);

语义详见: semantics-stack_grad

2.199. STFT

builder::Op STFT(builder::Op signal,
                 builder::Op frame_step,
                 builder::Op window,
                 int32_t onesided = 1,
                 std::experimental::optional<int32_t> frame_length = builder::nullopt,
                 builder::Type result_type = builder::Type());

总结: 短时傅里叶变换,参考 ONNX 定义 https://github.com/onnx/onnx/blob/main/docs/Operators.md#STFT

参数:
  • signal - 输入信号 Op

  • frame_step - 连续 DFT 之间步进的样本数

  • window - 信号上滑动的窗口

  • onesided - (可选)是否为单向,默认为 1 ,即单向。

  • frame_length - (可选)表示 DFT 大小的标量

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::STFT(signal, frame_step, window);

语义详见: semantics-stft

2.200. Sub

builder::Op Sub(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator-(builder::Op lhs, builder::Op rhs);

总结: 逐元素计算输入 lhsrhs 的差, 并将各个位置的输出元素保存到返回结果中。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator- 获得相同的效果。

(2.200.1)\[Sub(lhs, rhs) = lhs - rhs \]
参数:
  • lhs - 左操作数

  • rhs - 右操作数

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的数据类型必须一致,维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op,数据类型与输入相同,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Sub(lhs, rhs);
auto out2 = builder::Sub(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Sub(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs - rhs;

语义详见: Sub

2.201. SubGrad

builder::Op SubGrad(builder::Op grad_output,
                    builder::Op lhs,
                    builder::Op rhs,
                    std::vector<int64_t> broadcast_dimensions = {},
                    std::experimental::optional<float> alpha = builder::nullopt,
                    builder::Type result_type);

总结: 计算以下 Sub 输入的梯度

(2.201.1)\[Sub(lhs, rhs) = lhs - alpha * rhs \]
参数:
  • grad_output - Sub 输出的梯度

  • lhs - Sub 左输入

  • rhs - Sub 右输入

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • alpha - 被减数的系数

  • result_type - (可选)指定返回值的类型

返回值:
  • 返回 Tuple Op: 输入 lhsrhs 的梯度

示例代码:

auto grad_inputs1 = builder::SubGrad(grad_output, lhs, rhs);
auto grad_inputs2 = builder::SubGrad(grad_output, lhs, rhs, broadcast_dimensions);
auto grad_inputs3 = builder::SubGrad(grad_output, lhs, rhs, broadcast_dimensions, 1.0f);

语义详见: semantics-sub_grad

2.202. Swish

builder::Op Swish(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 Swish 激活函数

(2.202.1)\[Swish(input) = \frac{input}{1 + e^{-input}}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out = builder::Swish(input);

语义详见: Swish

2.203. Tan

builder::Op Tan(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 tangent 三角函数

(2.203.1)\[Tan(input)=std::tan(input)\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Tan(input);
auto out2 = builder::Tan(input, result_type);

语义详见: Tan

2.204. Tanh

builder::Op Tanh(builder::Op input, builder::Type result_type = builder::Type());

总结: 逐元素计算输入 input 的 tanh 激活函数

(2.204.1)\[Tanh(input) = \frac{e^{input} - e^{-input}}{e^{input} + e^{-input}}\]
参数:
  • input - 输入 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,与 input 维度相同、数据类型相同。

示例代码:

auto out1 = builder::Tanh(input);
auto out2 = builder::Tanh(input, result_type);

语义详见: Tanh

2.205. TanhGrad

builder::Op TanhGrad(builder::Op grad_output,
                     builder::Op output,
                     builder::Type result_type = builder::Type());

总结: 计算 Tanh 输入的梯度

(2.205.1)\[Tanh(input) = \frac{e^{input} - e^{-input}}{e^{input} + e^{-input}}\]
(2.205.2)\[grad\_input = grad\_output * (1 - output^2)\]
参数:
  • grad_output - 输出的梯度

  • output - Tanh 的输出

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度 Op

示例代码:

auto grad_input = builder::TanhGrad(grad_output, output);

语义详见: semantics-tanh_grad

2.206. Tile

builder::Op Tile(builder::Op input,
                 builder::Op repeats,
                 builder::Type result_type = builder::Type());

总结: 根据参数 repeats 对输入 input 的各维进行复制。输出 Op 的第 i 维度有 input.shape[i] * repeats[i] 个元素,并且 input 的值沿第 i 维度被复制 repeats[i] 次。

参数:
  • input - 输入 Op

  • repeats - 指定输入 input 每个维度的复制次数

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op,数据类型与 input 一致,第 i 维的大小等于 input[i] * repeats[i]

示例代码:

auto out = builder::Tile(input, repeats);

语义详见: Tile

2.207. Topk

builder::Op TopK(builder::Op input,
                 builder::Op k,
                 int64_t axis = -1,
                 bool sorted = true,
                 bool largest = true,
                 builder::Type result_type = builder::Type());

总结: 沿着可选的 axis 查找 topk 最大或最小的结果

参数:
  • input - 输入 Op

  • k - 在指定轴上进行 top 查找的数量

  • axis - 对输入进行运算的轴,axis 的有效范围是 [-R, R),R 是输入 input 的 Rank, axis 为负数时,进行计算的 axisaxis + R 一致。

  • sorted - (可选)控制返回的结果是否按序排列后返回

  • largest - (可选) 指定排序方向

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Tuple Op,返回 topk 结果和对应的索引信息

示例代码:

auto out = builder::TopK(input, k);

语义详见: Topk

2.208. Transpose

builder::Op Transpose(builder::Op input,
                      std::vector<int64_t> permutation,
                      builder::Type result_type = builder::Type());

总结: 根据 permutation 对输入 input 的数据进行重排,返回 Op 的第 i 维 对应输入 input 的 permutation[i] 维。

(2.208.1)\[output\_dimensions[i] = input\_dimensions[permutation[i]]\]
参数:
  • input - 输入 Op

  • permutation - 长度必须和输入 input 的 Rank 相同

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Transpose(input, permutation);

语义详见: Transpose

2.209. TransposeGrad

builder::Op TransposeGrad(builder::Op grad_output,
                          std::vector<int64_t> permutation,
                          builder::Type result_type = builder::Type());

总结: Transpose 输入的梯度

(2.209.1)\[reversed\_permutation[permutation[i]] = i\]
(2.209.2)\[grad\_input\_dimensions[i] = grad\_output\_dimensions[reversed\_permutation[i]]\]
参数:
  • grad_output - 输出的梯度

  • permutation - 长度必须和输入 input 的 Rank 相同

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto grad_input = builder::TransposeGrad(grad_output, permutation);

语义详见: semantics-transpose_grad

2.210. Trilu

builder::Op Trilu(builder::Op input,
                  bool upper = true,
                  int64_t k = 0,
                  builder::Type result_type = builder::Type());

总结: 返回输入 input 的上/下三角部分,其余部分设置为 0 。

参数:
  • input - 输入 Op

  • upper - 指示返回的是上三角部分,还是下三角部分

  • k - 指定的对角线,默认为 0

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Trilu(input);

语义详见: Trilu

2.211. Tuple

builder::Op Tuple(std::vector<builder::Op> inputs,
                  builder::Type result_type = builder::Type());

总结: 将一组输入 inputs 分组为单 Op

参数:
  • inputs - 输入的多个 Op

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Tuple(inputs);

语义详见: Tuple

2.212. Unsqueeze

builder::Op Unsqueeze(builder::Op input,
                      builder::Op axes,
                      builder::Type result_type = builder::Type());

总结: 向输入 input 的 shape 中一个或多个位置(axes) 插入尺寸为 1 的维度

参数:
  • inputs - 输入 Op

  • axes - 表示要插入维度的位置

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::Unsqueeze(input, axes);

语义详见: Unsqueeze

2.213. UnsqueezeGrad

builder::Op UnsqueezeGrad(builder::Op grad_output,
                          builder::Op axes,
                          builder::Type result_type = builder::Type());

总结: 计算 Unsqueeze 输入的梯度

参数:
  • grad_output - 输出的梯度

  • axes - 表示 Unsqueeze 要插入维度的位置

  • result_type - (可选)指定输出的类型

返回值:
  • 输入梯度 Op

示例代码:

auto out = builder::UnsqueezeGrad(grad_output, axes);

语义详见: semantics-unsqueeze_grad

2.214. Where

builder::Op Where(builder::Op condition,
                   builder::Op x,
                   builder::Op y,
                   builder::Type result_type = builder::Type());

总结: 根据 condition 来选择 xy 中的对应元素来组成新的 Op, 与 Select 区别是 Where 支持动静态输入的隐式广播,语义与 ONNX Where, NumPy Where 一致。

参数:
  • condition - 选择条件,数据类型必须为 pred

  • x - 条件为真时选择的 Op

  • y - 条件为假时选择的 Op

  • result_type - (可选)指定返回值的类型

返回值:
  • 输出 Op

示例代码:

auto output = builder::Where(condition, x, y);

2.215. While

builder::Op While(std::vector<builder::Op> args,
                  std::vector<const char*> region_list,
                  builder::Type result_type = builder::Type());

[Experimental API]: 实验性 API,暂时只用于 TopsInference 。

总结: 语义类似 C++ while,返回 Op 代表循环执行 region_list 对应的函数,直到条件失败。

参数:
  • args - While 循环的输入参数

  • region_list - 代表 While 循环的执行函数

  • result_type - (可选)指定输出的类型

返回值:
  • 输出 Op

示例代码:

auto out = builder::While(args, region_list);

语义详见: While

2.216. Xor

当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator^ 获得相同的效果。 builder::Op operator^(builder::Op lhs, builder::Op rhs);

builder::Op Xor(builder::Op lhs,
                builder::Op rhs,
                std::vector<int64_t> broadcast_dimensions = {},
                builder::Type result_type = builder::Type());

builder::Op operator^(builder::Op lhs, builder::Op rhs);

总结: 逐元素对 lhsrhs 进行按位异或运算。当不需要显示指定 broadcast_dimensions 时,也可使用重载运算符 operator^ 获得相同的效果。

参数:
  • lhs - 需要运算的左值

  • rhs - 需要运算的右值

  • broadcast_dimensions - (可选)指定需要被广播的维度

  • result_type - (可选)指定返回值的类型

限制:
  • 输入 lhsrhs 的维度可不相同,但必须满足 XLA 广播规则

  • 默认 broadcast_dimensions 为空,此时采用 numpy-style-broadcasting 规则

返回值:
  • 输出 Op ,维度为 lhsrhs 广播后的形状。

示例代码:

auto out1 = builder::Xor(lhs, rhs);
auto out2 = builder::Xor(lhs, rhs, broadcast_dimensions);
auto out3 = builder::Xor(lhs, rhs, broadcast_dimensions, result_type);
auto out4 = lhs ^ rhs;

语义详见: Or

2.217. ZerosLike

// 语义参考 NumPy: https://numpy.org/doc/stable/reference/generated/numpy.zeros_like.html

builder::Op ZerosLike(
  builder::Op input,
  std::experimental::optional<builder::PrimitiveType> new_data_type = builder::nullopt,
  std::experimental::optional<std::vector<int64_t>> new_shapes = builder::nullopt);

builder::Op ZerosLike(builder::Op input,
                     builder::PrimitiveType new_data_type,
                     const std::vector<int64_t> &new_shapes);

template <typename T>
builder::Op ZerosLike(builder::Op input,
                      builder::PrimitiveType new_data_type,
                      const std::initializer_list<T>& new_shapes);

总结: 根据输入 input 对应的数据类型和维度信息,构造值全为 0 的 Const Op。常用使用方式为 builder::ZerosLike(input),构造的输出 Op 数据类型,维度与输入 input 相同。 也可只利用 input 保存的全局 Builder 共享指针,自行设置数据类型和维度。

参数:
  • input - 参考的输入,默认会从 input 中获取保存的全局 Builder 共享指针,以及 input 的数据类型和维度信息。

  • new_data_type - 重新指定数据类型,不采用 input 的数据类型。

  • new_shapes - 重新指定维度信息,不采用 input 的维度信息。

返回值:
  • 输出 Const Op。

示例代码:

// input: tensor<1x3x224x224xf32>
auto out1 = builder::ZerosLike(input);  // tensor<1x3x224x224xf32> value = 0.0f
auto out2 = builder::ZerosLike(input,
                               builder::PrimitiveType::S32());  // tensor<1x3x224x224xi32> value = 0
std::vector<int64_t> new_shapes = {1};
auto out3 = builder::ZerosLike(input,
                               builder::PrimitiveType::S32(), new_shapes);  // tensor<1xi32> value = 0
auto out4 = builder::ZerosLike(input,
                               builder::PrimitiveType::S32(), {4});  // tensor<4xi32> value =