ENH: einsum: Add alternative einsum parameter method

This makes the following equivalent:
einsum('ii', a)
einsum(a, [0,0])

einsum('ii->i', a)
einsum(a, [0,0], [0])

einsum('...i,...i->...', a, b)
einsum(a, [Ellipsis,0], b, [Ellipsis,0], [Ellipsis])

1 files changed, 30 insertions, 0 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index f51860240..e749784d5 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -1517,6 +1517,10 @@ add_newdoc('numpy.core', 'einsum',
 
     Evaluates the Einstein summation convention on the operands.
 
+    An alternative way to provide the subscripts and operands is as
+    einsum(op0, sublist0, op1, sublist1, ..., [sublistout]). The examples
+    below have corresponding einsum calls with the two parameter methods.
+
     Using the Einstein summation convention, many common multi-dimensional
     array operations can be represented in a simple fashion.  This function
     provides a way compute such summations.
@@ -1605,16 +1609,22 @@ add_newdoc('numpy.core', 'einsum',
 
     >>> np.einsum('ii', a)
     60
+    >>> np.einsum(a, [0,0])
+    60
     >>> np.trace(a)
     60
 
     >>> np.einsum('ii->i', a)
     array([ 0,  6, 12, 18, 24])
+    >>> np.einsum(a, [0,0], [0])
+    array([ 0,  6, 12, 18, 24])
     >>> np.diag(a)
     array([ 0,  6, 12, 18, 24])
 
     >>> np.einsum('ij,j', a, b)
     array([ 30,  80, 130, 180, 230])
+    >>> np.einsum(a, [0,1], b, [1])
+    array([ 30,  80, 130, 180, 230])
     >>> np.dot(a, b)
     array([ 30,  80, 130, 180, 230])
 
@@ -1622,6 +1632,10 @@ add_newdoc('numpy.core', 'einsum',
     array([[0, 3],
            [1, 4],
            [2, 5]])
+    >>> np.einsum(c, [1,0])
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
     >>> c.T
     array([[0, 3],
            [1, 4],
@@ -1630,24 +1644,34 @@ add_newdoc('numpy.core', 'einsum',
     >>> np.einsum('..., ...', 3, c)
     array([[ 0,  3,  6],
            [ 9, 12, 15]])
+    >>> np.einsum(3, [Ellipsis], c, [Ellipsis])
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
     >>> np.multiply(3, c)
     array([[ 0,  3,  6],
            [ 9, 12, 15]])
 
     >>> np.einsum('i,i', b, b)
     30
+    >>> np.einsum(b, [0], b, [0])
+    30
     >>> np.inner(b,b)
     30
 
     >>> np.einsum('i,j', np.arange(2)+1, b)
     array([[0, 1, 2, 3, 4],
            [0, 2, 4, 6, 8]])
+    >>> np.einsum(np.arange(2)+1, [0], b, [1])
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
     >>> np.outer(np.arange(2)+1, b)
     array([[0, 1, 2, 3, 4],
            [0, 2, 4, 6, 8]])
 
     >>> np.einsum('i...->...', a)
     array([50, 55, 60, 65, 70])
+    >>> np.einsum(a, [0,Ellipsis], [Ellipsis])
+    array([50, 55, 60, 65, 70])
     >>> np.sum(a, axis=0)
     array([50, 55, 60, 65, 70])
 
@@ -1659,6 +1683,12 @@ add_newdoc('numpy.core', 'einsum',
            [ 4664.,  5018.],
            [ 4796.,  5162.],
            [ 4928.,  5306.]])
+    >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
+    array([[ 4400.,  4730.],
+           [ 4532.,  4874.],
+           [ 4664.,  5018.],
+           [ 4796.,  5162.],
+           [ 4928.,  5306.]])
     >>> np.tensordot(a,b, axes=([1,0],[0,1]))
     array([[ 4400.,  4730.],
            [ 4532.,  4874.],