What are the advantages of using numpy.identity over numpy.eye?

Question

Having looked over the man pages for numpy's eye and identity, I'd assumed that identity was a special case of eye, since it has fewer options (e.g. eye can fill shifted diagonals, identity cannot), but could plausibly run more quickly. However, this isn't the case on either small or large arrays:

>>> np.identity(3)                                                   array([[ 1.,  0.,  0.],        [ 0.,  1.,  0.],        [ 0.,  0.,  1.]]) >>> np.eye(3)                                                        array([[ 1.,  0.,  0.],        [ 0.,  1.,  0.],        [ 0.,  0.,  1.]]) >>> timeit.timeit("import numpy; numpy.identity(3)", number = 10000) 0.05699801445007324 >>> timeit.timeit("import numpy; numpy.eye(3)", number = 10000)      0.03787708282470703 >>> timeit.timeit("import numpy", number = 10000)                    0.00960087776184082 >>> timeit.timeit("import numpy; numpy.identity(1000)", number = 10000) 11.379066944122314 >>> timeit.timeit("import numpy; numpy.eye(1000)", number = 10000)      11.247124910354614 

What, then, is the advantage of using identity over eye?

Answer 1

identity just calls eye so there is no difference in how the arrays are constructed. Here's the code for identity:

def identity(n, dtype=None):     from numpy import eye     return eye(n, dtype=dtype) 

As you say, the main difference is that with eye the diagonal can may be offset, whereas identity only fills the main diagonal.

Since the identity matrix is such a common construct in mathematics, it seems the main advantage of using identity is for its name alone.

Answer 2

To see the difference in an example, run the below codes:

import numpy as np  #Creates an array of 4 x 4 with the main diagonal of 1  arr1 = np.eye(4) print(arr1)  print("\n")  #or you can change the diagonal position  arr2 = np.eye(4, k=1)  # or try with another number like k= -2 print(arr2)  print("\n")  #but you can't change the diagonal in identity  arr3 = np.identity(4) print(arr3)