einsum optimize default arg is documented as True but defaults to False

[acbellini]

np.einsum documentation says that the optimize arg default is True:

numpy/numpy/core/einsumfunc.py

Line 867 in 963c704

function. See ``np.einsum_path`` for more details. Default is True.

but when the argument is missing, it defaults to False:

numpy/numpy/core/einsumfunc.py

Line 1060 in 963c704

optimize_arg = kwargs.pop('optimize', False)

Proposed fix: change the argument to default to True, as it makes sense to use optimization unless explicitly disabled

[charris]

@dgasmith Thoughts?

[dgasmith]

Whoops, we had agreed to flip the optimization to True as we thought the algorithm was sufficiently battle tested through a full release already. It looks like only half of it was changed correctly. Great catch to fix this in the RC.

@acbellini Let me know if I can help out.

[charris]

Closed by #10259.

[acbellini]

Yay! my first ever Numpy PR :D !!!!

[peijunz]

Dear developers @acbellini @charris

Although the optimization option is changed to True by default, there is still inconsistency in line 822:

numpy/numpy/core/einsumfunc.py

Lines 819 to 822 in 6914bb4

	def einsum(*operands, **kwargs):
	"""
	einsum(subscripts, *operands, out=None, dtype=None, order='K',
	casting='safe', optimize=False)

The signature of this function is still showing optimization=False. Could you please improve it?

Thank you!

[dgasmith]

In NumPY 1.14.1 (?) optimize was turned off by default as it was showing a few regressions.

Einsum is a pure C function and has low latency as most other functions like sum or tensordot have a bit of Python overhead that can easily swamp the compute time for very small operations. I didn't realize that folks were using it in this fashion, but makes quite a bit of sense in retrospect.

I think the only way forward to have optimize=True by default would be to write a bit of the optimization tech in C so the latency goes down.

[acbellini]

@dgasmith : but now code, signature and doc are inconsistent.

Signature says default is False
Docs say default is True
in the actual code , it depends on the length of the operands. So, if I pass only two arguments, it will not use optimization, if I pass three or more, it will. What is the logic behind this?

[dgasmith]

Ah, ok it looks like they way it shook out was to kwargs.pop('optimize', len(operands) > 3) so you need 3 or more tensors (as one is the input string), but this also doesn't account for the other input methods.

I didn't make those changes, but if I recall correctly the idea was optimize=True for 3 or more tensors is a good idea as order can be optimized and not just using the einsum vs tensordot switch for 2 operands.

I think the current behavior is fairly reasonable, but does need to be documented correctly.