Binary#

The binary primitive computes a result of a binary elementwise operation between tensors source 0 and source 1.

\[\dst(\overline{x}) = \src_0(\overline{x}) \mathbin{op} \src_1(\overline{x}),\]

where \(\overline{x} = (x_0, \ldots, x_n)\) and \(op\) is an operator like addition, multiplication, maximum or minimum. Variable names follow the standard Conventions.

Forward and Backward#

The binary primitive does not have a notion of forward or backward propagations.

Execution Arguments#

When executed, the inputs and outputs should be mapped to an execution argument index as specified by the following table.

Primitive input/output

Execution argument index

\(\src_0\)

DNNL_ARG_SRC_0

\(\src_1\)

DNNL_ARG_SRC_1

\(\dst\)

DNNL_ARG_DST

Operation Details#

  • The binary primitive requires all source and destination tensors to have the same number of dimensions.

  • The binary primitive supports implicit broadcast semantics for source 1. It means that if some dimension has value of one, this value will be used to compute an operation with each point of source 0 for this dimension.

  • The \(\dst\) memory format can be either specified explicitly or by dnnl::memory::format_tag::any (recommended), in which case the primitive will derive the most appropriate memory format based on the format of the source 0 tensor.

  • Destination memory descriptor should completely match source 0 memory descriptor.

  • The binary primitive supports in-place operations, meaning that source 0 tensor may be used as the destination, in which case its data will be overwritten.

Post-ops and Attributes#

The following attributes should be supported:

Type

Operation

Description

Restrictions

Attribute

Scales

Scales the corresponding input tensor by the given scale factor(s).

The corresponding tensor has integer data type. Only one scale per tensor is supported. Input tensors only.

Post-op

Sum

Adds the operation result to the destination tensor instead of overwriting it.

Must precede eltwise post-op.

Post-op

Eltwise

Applies an elementwise operation to the result.

Data Types Support#

The source and destination tensors may have dnnl::memory::data_type::f32, dnnl::memory::data_type::bf16, dnnl::memory::data_type::s8 or dnnl::memory::data_type::u8 data types.

Data Representation#

The binary primitive works with arbitrary data tensors. There is no special meaning associated with any of tensors dimensions.

API#

struct binary : public dnnl::primitive#

Elementwise binary operator primitive.

Public Functions

binary()#

Default constructor. Produces an empty object.

binary(const primitive_desc &pd)#

Constructs an elementwise binary operation primitive.

Parameters

pd – Primitive descriptor for an elementwise binary operation primitive.

struct desc#

Descriptor for an elementwise binary operator primitive.

Public Functions

desc(algorithm aalgorithm, const memory::desc &src0, const memory::desc &src1, const memory::desc &dst)#

Constructs a descriptor for an elementwise binary operator primitive.

Parameters

  • aalgorithm – Elementwise algorithm.

  • src0 – Memory descriptor for source tensor #0.

  • src1 – Memory descriptor for source tensor #1.

  • dst – Memory descriptor for destination tensor.

struct primitive_desc : public dnnl::primitive_desc#

Primitive descriptor for an elementwise binary operator primitive.

Public Functions

primitive_desc()#

Default constructor. Produces an empty object.

primitive_desc(const desc &adesc, const engine &aengine, bool allow_empty = false)#

Constructs a primitive descriptor for an elementwise binary operator primitive.

Parameters

  • adesc – Descriptor for an elementwise binary operator primitive.

  • aengine – Engine to use.

  • allow_empty – A flag signifying whether construction is allowed to fail without throwing an exception. In this case an empty object will be produced. This flag is optional and defaults to false.

primitive_desc(const desc &adesc, const primitive_attr &attr, const engine &aengine, bool allow_empty = false)#

Constructs a primitive descriptor for an elementwise binary operator primitive.

Parameters

  • adesc – Descriptor for an elementwise binary operator primitive.

  • aengine – Engine to use.

  • attr – Primitive attributes to use.

  • allow_empty – A flag signifying whether construction is allowed to fail without throwing an exception. In this case an empty object will be produced. This flag is optional and defaults to false.

memory::desc src_desc(int idx = 0) const#

Returns a source memory descriptor.

Parameters

idx – Source index.

Returns

Source memory descriptor.

Returns

A zero memory descriptor if the primitive does not have a source parameter with index pdx.

memory::desc src0_desc() const#

Returns the memory descriptor for source #0.

memory::desc src1_desc() const#

Returns the memory descriptor for source #1.

memory::desc dst_desc() const#

Returns a destination memory descriptor.

Returns

Destination memory descriptor.

Returns

A zero memory descriptor if the primitive does not have a destination parameter.