Add `conj` specification for computing the complex conjugate
This PR
- adds support for computing the complex conjugate via
conj, which is widely implemented by array libraries. - follows the conventions set forth for element-wise mathematical functions.
- restricts input array types to complex floating-point arrays, following the precedent in https://github.com/data-apis/array-api/pull/427.
Notes
- Re: restricting to complex dtypes. We should note that this, similar to
real, runs contrary to array libraries, more generally, which allow real-valued arrays as input and defineconjas a no-op for those inputs (see PyTorch v1.11, TensorFlow, and NumPy). However, this PR chooses to be consistent withrealin requiring users to provide a complex number array for the primary reason that, in most cases, when a user is callingconj(z), the expectation is thatzis complex-valued, and, if real-valued, this is likely a bug.
Would be nice if we can discuss #425 again this week. It seems this and #427 are blocked.
My feeling would be that we should probably allow it, since Python itself also always implemntes .real and .conjugate() (althought not .imag I believe).
But of course for now that just means not explicitly saying that it must be forbidden (vs. should not be allowed or does not have to be allowed).
As discussed in the Sept 22, 2022, consortium meeting, the plan is to merge this PR as is. We can revisit the decision to only support complex dtypes based on downstream library implementations and feedback should this prove problematic/undesirable.
The spec, as written, uses should, so implementors can extend to real-valued dtypes for reasons of backward compatibility. However, users should only except that complex dtypes will work across all spec compliant array API implementations.