Add element-wise function specifications, incl. type casting and broadcasting rules

[kgryte]

This PR

• adds specifications for element-wise operations, both elementary mathematical functions and arithmetic operations.
• builds on the analysis and subsequent discussions outlined and held in issues Proposal to standardize element-wise elementary mathematical functions #8, Proposal to standardize element-wise arithmetic operations #9, Type promotion rules #14, Supported data types #15.

[rgommers]

Should we require element-wise function output arguments to have the exact same shape as input arguments or should we allow broadcasting?

That's a good question. I'd prefer requiring out being of the correct shape. For functions with a single array input that implies the same shape as the input; for multiple array inputs or for other keywords that may support broadcasting, those can affect the expected shape of the output array. out itself is a special keyword in this case, the intent is for it to be filled in-place so it should not participate in broadcasting I believe.

Although some may have a use case for func(in_shape_1_by4, out=shape_10_by_4). That breaks this equivalence though:

out1 = func(inputs)
out2 = np.empty((some_shape))
func(inputs, out=out2).shape == func(inputs, out=None).shape

My mental model is that those shapes should be equal, and hence out= doesn't broadcast.

[kgryte]

@rgommers Thanks for the feedback.

Re: broadcasting. My understanding is that, e.g., NumPy permits such broadcasting semantics.

[kgryte]

I've updated the proposed specification to include supported data types and promotion rules, which should now roughly complete the spec for element-wise functions. Remaining concerns include:

• minimum precision requirements
• casting rules

However, these concerns can be addressed in follow-up PRs.

[rgommers]

Thanks @kgryte. I think this is in good shape, and all the important decisions have been reviewed by multiple people in the various linked issues and meetings.

Let's go ahead and merge this.