User guide

NumPy User Guide, Release 1.9.0
Broadcasting provides a means of vectorizing array operations so that looping occurs in C instead of Python. It does
this without making needless copies of data and usually leads to efficient algorithm implementations. There are,
however, cases where broadcasting is a bad idea because it leads to inefficient use of memory that slows computation.
NumPy operations are usually done on pairs of arrays on an element-by-element basis. In the simplest case, the two
arrays must have exactly the same shape, as in the following example:
>>> a = np.array([1.0, 2.0, 3.0])
>>> b = np.array([2.0, 2.0, 2.0])
>>> a
*
b
array([ 2., 4., 6.])
NumPy’s broadcasting rule relaxes this constraint when the arrays’ shapes meet certain constraints. The simplest
broadcasting example occurs when an array and a scalar value are combined in an operation:
>>> a = np.array([1.0, 2.0, 3.0])
>>> b = 2.0
>>> a
*
b
array([ 2., 4., 6.])
The result is equivalent to the previous example where b was an array. We can think of the scalar b being stretched
during the arithmetic operation into an array with the same shape as a. The new elements in b are simply copies
of the original scalar. The stretching analogy is only conceptual. NumPy is smart enough to use the original scalar
value without actually making copies, so that broadcasting operations are as memory and computationally efficient as
possible.
The code in the second example is more efficient than that in the first because broadcasting moves less memory around
during the multiplication (b is a scalar rather than an array).
2.5.1 General Broadcasting Rules
When operating on two arrays, NumPy compares their shapes element-wise. It starts with the trailing dimensions, and
works its way forward. Two dimensions are compatible when
1. they are equal, or
2. one of them is 1
If these conditions are not met, a ValueError: frames are not aligned exception is thrown, indicating
that the arrays have incompatible shapes. The size of the resulting array is the maximum size along each dimension of
the input arrays.
Arrays do not need to have the same number of dimensions. For example, if you have a 256x256x3 array of RGB
values, and you want to scale each color in the image by a different value, you can multiply the image by a one-
dimensional array with 3 values. Lining up the sizes of the trailing axes of these arrays according to the broadcast
rules, shows that they are compatible:
Image (3d array): 256 x 256 x 3
Scale (1d array): 3
Result (3d array): 256 x 256 x 3
When either of the dimensions compared is one, the other is used. In other words, dimensions with size 1 are stretched
or “copied” to match the other.
In the following example, both the A and B arrays have axes with length one that are expanded to a larger size during
the broadcast operation:
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
2.5. Broadcasting 27