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

Sets scale(s) for the corresponding tensor(s)

post-op

Eltwise

Applies an elementwise operation to the result

post-op

Binary

Applies a binary operation to the result

post-op

Sum

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

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 dnnl::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 primitive_desc : public dnnl::primitive_desc#

Primitive descriptor for an elementwise binary operator primitive.

Public Functions

primitive_desc() = default#

Default constructor. Produces an empty object.

primitive_desc(const engine &aengine, algorithm aalgorithm, const memory::desc &src0, const memory::desc &src1, const memory::desc &dst, const primitive_attr &attr = default_attr(), bool allow_empty = false)#

Constructs a primitive descriptor for an elementwise binary operator primitive.

Parameters

  • aengine – Engine to use.

  • aalgorithm – Elementwise binary algorithm.

  • src0 – Memory descriptor for source tensor #0.

  • src1 – Memory descriptor for source tensor #1.

  • dst – Memory descriptor for destination tensor.

  • attr – Primitive attributes to use. Attributes are optional and default to empty attributes.

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

algorithm get_algorithm() const#

Returns an algorithm kind.

Returns

An algorithm kind.

Returns

dnnl::algorithm::undef if the primitive does not have an algorithm parameter.