Broadcasting ¶
Array API specification for broadcasting semantics.
Overview ¶
Broadcasting refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for elementwise operations.
Broadcasting facilitates user ergonomics by encouraging users to avoid unnecessary copying of array data and can potentially enable more memoryefficient elementwise operations through vectorization, reduced memory consumption, and cache locality.
Algorithm ¶
Given an elementwise operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding nonsingleton dimension.
If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank.
The results of the elementwise operation must be stored in an array having a shape determined by the following algorithm.

Let
A
andB
both be arrays. 
Let
shape1
be a tuple describing the shape of arrayA
. 
Let
shape2
be a tuple describing the shape of arrayB
. 
Let
N1
be the number of dimensions of arrayA
(i.e., the result oflen(shape1)
). 
Let
N2
be the number of dimensions of arrayB
(i.e., the result oflen(shape2)
). 
Let
N
be the maximum value ofN1
andN2
(i.e., the result ofmax(N1, N2)
). 
Let
shape
be a temporary list of lengthN
for storing the shape of the result array. 
Let
i
beN1
. 
Repeat, while
i >= 0

Let
n1
beN1  N + i
. 
If
n1 >= 0
, letd1
be the size of dimensionn1
for arrayA
(i.e., the result ofshape1[n1]
); else, letd1
be1
. 
Let
n2
beN2  N + i
. 
If
n2 >= 0
, letd2
be the size of dimensionn2
for arrayB
(i.e., the result ofshape2[n2]
); else, letd2
be1
. 
If
d1 == 1
, then
set the
i
th element ofshape
tod2
.


Else, if
d2 == 1
, then
set the
i
th element ofshape
tod1
.


Else, if
d1 == d2
, then
set the
i
th element ofshape
tod1
.


Else, throw an exception.

Set
i
toi1
.


Let
tuple(shape)
be the shape of the result array.
Examples ¶
The following examples demonstrate the application of the broadcasting algorithm for two compatible arrays.
A (4d array): 8 x 1 x 6 x 1
B (3d array): 7 x 1 x 5

Result (4d array): 8 x 7 x 6 x 5
A (2d array): 5 x 4
B (1d array): 1

Result (2d array): 5 x 4
A (2d array): 5 x 4
B (1d array): 4

Result (2d array): 5 x 4
A (3d array): 15 x 3 x 5
B (3d array): 15 x 1 x 5

Result (3d array): 15 x 3 x 5
A (3d array): 15 x 3 x 5
B (2d array): 3 x 5

Result (3d array): 15 x 3 x 5
A (3d array): 15 x 3 x 5
B (2d array): 3 x 1

Result (3d array): 15 x 3 x 5
The following examples demonstrate array shapes which do not broadcast.
A (1d array): 3
B (1d array): 4 # dimension does not match
A (2d array): 2 x 1
B (3d array): 8 x 4 x 3 # second dimension does not match
A (3d array): 15 x 3 x 5
B (2d array): 15 x 3 # singleton dimensions can only be prepended, not appended
Inplace Semantics ¶
As implied by the broadcasting algorithm, inplace elementwise operations must not change the shape of the inplace array as a result of broadcasting.