Add real specification for returning the real component of a complex number

[kgryte]

This PR

• adds a specification for real, an API for returning the real component of a complex number for each element x_i of an input array x.

• chooses to follow PyTorch in restricting the allowed input array data types to only complex floating-point data types. NumPy et al and TensorFlow allow both real- and complex-valued input array data types. For real-valued data types, real(x) is a no-op.

  An argument can be made that, as real numbers are a subset of complex numbers, when providing a real-valued array, this is equivalent to a complex number array whose imaginary components are all zeros. As such, any numeric array is a complex number array regardless of its storage data type.

  This PR chooses to be more restrictive based on the premise that consumers should be explicit when performing a complex number operation (e.g., if real-valued inputs are allowed, was calling real(x) intentional when providing a real-valued x or was this an unintended bug where x should have been complex valued?). Given potential ambiguity between intended versus unintended behavior, this PR places the onus on consumers to resolve this ambiguity.

  Provided RFC: add data type inspection utilities to the array API specification #425 moves forward, array API consumers should have standardized means for inspecting array data types and branching accordingly. E.g.,

  if is_complex(x):
      x = real(x)
  
  # do something with real-valued `x`

• is dependent on Add complex floating-point data types #418 which adds complex floating-point data types to the specification.

[leofang]

So this PR should be merged after resolving #425.

[kgryte]

@leofang Yes, I would think so.

[leofang]

Would be nice if we can discuss #425 again this week. It seems this and #446 are blocked.

[rgommers]

I was looking for imag as well, seems like there's no separate PR and it's also not in the spec. Easiest to add to this PR?

[kgryte]

As imag has the same concerns as real and conj, was not going to add until we had settled the question of allowed dtypes.

[kgryte]

Atm, the function, as spec'd, states that the input array "should have a complex floating-point data type". This affords array libraries some flexibility in allowing real-valued data types, as "should" is more lenient than "must".

At this point, I don't think we should wait on #425, as data type inspection still lacks consensus. We should merge this as is so that array libraries can begin their spec compliant implementations, and we can revisit/make changes to the spec upon receiving feedback based on real-world implementations.

[rgommers]

I think we have multiple good solutions and will get gh-425 over the finish line. So I agree that this PR shouldn't be blocked on that. @leofang would you agree?

[leofang]

Sounds good to me, as long as we are committed to get #425 done in the same year.

[kgryte]

As discussed in the Sept 22, 2022, consortium meeting, the plan is to merge this and #446 as is. We can revisit the decision to only support complex dtypes based on downstream library implementations and feedback should this prove problematic/undesirable.