Example
The numpy dot function has an optional parameter out=None. This parameter allows you to specify an array to write the result to. This array must be exactly the same shape and type as the array that would have been returned, or an exception will be thrown.
>>> I = np.eye(2)
>>> I
array([[ 1., 0.],
[ 0., 1.]])
>>> result = np.zeros((2,2))
>>> result
array([[ 0., 0.],
[ 0., 0.]])
>>> np.dot(I, I, out=result)
array([[ 1., 0.],
[ 0., 1.]])
>>> result
array([[ 1., 0.],
[ 0., 1.]])
Let's try changing the dtype of result to int.
>>> np.dot(I, I, out=result)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: output array is not acceptable (must have the right type, nr dimensions, and be a C-Array)
And if we try using a different underlying memory order, say Fortran-style (so columns are contiguous instead of rows), an error also results.
>>> result = np.zeros((2,2), order='F')
>>> np.dot(I, I, out=result)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: output array is not acceptable (must have the right type, nr dimensions, and be a C-Array)
