Add complex number support to log

[kgryte]

This PR

• adds complex number support to log by documenting special cases. By convention, the natural logarithm has a single branch cut, which is defined as the real interval (-infinity, 0).
• updates the input and output array data types to be any floating-point data type, not just real-valued floating-point data types.
• derives special cases from C99

[rgommers]

Sphinx is unhappy with the branch cuts label:

/home/circleci/repo/spec/API_specification/array_api/elementwise_functions.py:docstring of
array_api.elementwise_functions.log:41: WARNING: undefined label: branch-cuts

[kgryte]

@rgommers This is because we need to merge #461 first. The other branch cut PRs are dependent on that PR due to the added/referenced design doc.

[kgryte]

Now that #461 is merged, all checks for this PR now pass.

[rgommers]

Thanks @kgryte. One minor comment on the diff. My main comment is about the branch cuts - it would be very helpful to document that they are consistent with (and based on) those from C99. It is noted in the branch cuts design document, however that is probably easy to miss (and it requires the user to know which functions are in C99 and which aren't). Maybe in a couple of words, "branch cuts for log match those in C99"?.

[asmeurer]

For functions like this with a branch cut, should we add special cases along the cut, i.e., a + 0j and a - 0j where a < 0?

[kgryte]

@asmeurer That should already be covered by https://github.com/data-apis/array-api/pull/514/files#diff-6a52ec5810cf6d5389f09ea49af4311f7dc38da86d9c091e2a0234dfc5f662cbR939.

[asmeurer]

Is it worth specially noting that functions like log, sqrt, etc. are not expected to promote floating-point arguments outside of their real domain to complex (and indeed, such value-based casting is explicitly recommended against)?

[asmeurer]

@asmeurer That should already be covered by #514 (files).

Did you mean to link to a specific line? I don't see where this is mentioned.

[kgryte]

Did you mean to link to a specific line?

From your comment, seemed like you were referring to how complex conjugates should be specified.

[kgryte]

Is it worth specially noting that functions like log, sqrt, etc. are not expected to promote floating-point arguments outside of their real domain to complex (and indeed, such value-based casting is explicitly recommended against)?

Yes, this is likely a good idea. Probably better to include as part of the general complex number design doc.

[asmeurer]

I mean specifically special cases along the cut, for +0 and -0. Something like "If a is negative and b is +0.0, log(a + bj) should equal log(-a) + π" and "If a is negative and b is -0.0, log(a + bj) should equal log(-a) - π". That's why I asked in the last meeting if all the cuts where either on the real or imaginary axes, because when they are you can always pick a side of the cut with positive or negative 0.

Also, a weird thing I just discovered: 1-0.0j doesn't create a complex number with -0.0 imaginary part. You have to do -(-1+0j) or complex(1, -0.0).

[rgommers]

My main comment is about the branch cuts - it would be very helpful to document that they are consistent with (and based on) those from C99. It is noted in the branch cuts design document, however that is probably easy to miss (and it requires the user to know which functions are in C99 and which aren't). Maybe in a couple of words, "branch cuts for log match those in C99"?.

This comment applies to a large number of open PRs, so I will add it as a separate task in gh-533.

[kgryte]

@asmeurer At the moment, the spec does cover the special cases you mention. Per the guidance in C99 (and also included in this PR), log(conj(z)) == conj(log(z)). In which case, if $z = a + bj$ with $a < 0$

z = a + 0j;
log(z) = log(a) + πj
conj(log(z)) = conj(log(a) + πj) = log(a) - πj
log(conj(z)) = log(a - 0j) = log(a) - πj            // per equality requirement

We can see that the equality requirement holds by computing the principal value of the complex logarithm in terms of atan2.

$$\log(z) = \log(r) + \theta j = \log(|z|) + j \operatorname{Arg}(z) = \log(\sqrt{a^2 + b^2}) + j \operatorname{atan2}(b,a)$$

where $z = a + bj = r e^{\theta j}$ and $r = |z| = \sqrt{a^2 + b^2}$. If we plug in the values for $a < 0$ and $b = \pm 0$, we get

log(a + 0j) = log(a) + j atan2(+0, a) = log(a) + πj
log(a - 0j) = log(a) + j atan2(-0, a) = log(a) - πj

In short, I don't think we need to go beyond what this PR already does. Namely, require that log(conj(z)) == conj(log(z)).

[asmeurer]

Hmm, OK. What about functions whose branch cuts are along the imaginary axis?

Anyway, let's make sure this is tested properly when we add it to the test suite (specifically, with +/- 0 being tested) @honno

[asmeurer]

Just to be clear, I'm OK with this PR. My question applies to some other functions, but it's not something that should block things, since it's just about a special case which could easily be added later.

[rgommers]

Thanks @asmeurer for the clarification and the new issue. Looks like we're all good here then.