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

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?

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.

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)

np.identity returns a square matrix (special case of a 2D-array) which is an identity matrix with the main diagonal (i.e. 'k=0') as 1's and the other values as 0's. you can't change the diagonal k here.

np.eye returns a 2D-array, which fills the diagonal, i.e. 'k' which can be set, with 1's and rest with 0's.

So, the main advantage depends on the requirement. If you want an identity matrix, you can go for identity right away, or can call the np.eye leaving the rest to defaults.

But, if you need a 1's and 0's matrix of a particular shape/size or have a control over the diagonal you can go for eye method.

Just like how a matrix is a special case of an array, np.identity is a special case of np.eye.

Additional references:

• Eye and Identity - HackerRank