New Julia function cispi

[eschnett]

Closes #33341.

[StefanKarpinski]

I like it! Nice simple function with very fast special cases for specific types. Feels like testing a few other values would be good, maybe:

@test cispi(0.5) == 1
@test cispi(1.5) == -1
@test cispi(0.25) == Complex(sqrt(2)/2, sqrt(2)/2)

[eschnett]

@StefanKarpinski Those tests for fast special cases are a very good idea. I actually managed to have a bug in my implementation (now fixed). Now we even have cispi(1) == cispi(1.0)...

[simeonschaub]

Great to have this, I have needed that before! I am wondering, whether it would make sense to have an optimized sincospi here. Looking at the implementations of sinpi and sincos, it looks like there are some optimization opportunities by calculating them together. Probably a separate issue though.

[antoine-levitt]

For floats, is it faster (or at least as fast) as cis(pi*x)? Since cis calls an optimized sincos it could well be worse.

[simeonschaub]

IIUC the advantage of sinpi and friends is not better performance, but better accuracy and exact results for multiples of 1/2.

[olof3]

"signbit is the inverse of cispi"
Perhaps it would be more accurate with "a left inverse of cispi when b is a Bool"

cispi(n) * abs(n) == n, doesn't seem to hold for e.g., n=-2

I'm not sure how helpful this paragraph is for understanding the functionality of signbit?

[eschnett]

I didn't want to use the terminology of "left inverse" since that's quite technical. I want to point to the fact that signbit and cispi are related. signbit itself should be explained elsewhere – but a reminder here might be useful.

[olof3]

Calling it inverse (or left inverse) without specifying that it is only valid for Bools seems like a quite puzzling statement. But I guess I mostly think that cispi and signbit are not that strongly related to motivate adding all this text to the succinct doc string of signbit. If there really is a need to indicate a relation, perhaps a simple See also [`cispi`](@ref) would be enough?

[eschnett]

I updated the documentation. I now call them "related" functions.

[eschnett]

@simeonschaub Yes, there should be an optimized sincospi as well. This should be even faster than sincos since one doesn't have to divide by pi.

[StefanKarpinski]

There appears to have been a git merge snafu here.

[eschnett]

@StefanKarpinski snafu corrected.

[ViralBShah]

Bump. Is it good to merge? Still needs NEWS.

[eschnett]

I thought the consensus was to not have cospi / sinpi with special cases for integer arguments? If so, this PR should be rejected in favour of a new function (e.g. bitsign) that is intended as inverse to signbit, without direct connotation to trigonometry.

[simonbyrne]

sincospi is now merged (#35816)

[simeonschaub]

We can now take advantage of #35816. What cispi returns for integers, should probably follow sincospi for now, until #35820 reaches a consensus.

[simeonschaub]

Suggested change

	cispi(sign::Bool) = sign ? -1 : 1
	cispi(sign::Integer) = oftype(sign, cispi(isodd(sign)))
	cispi(theta::Real) = Complex(cospi(theta), sinpi(theta))
	cispi(theta::Real) = complex(reverse(sincospi(theta))...)

[simeonschaub]

Suggested change

	function cispi(z::Complex)
	cospi(z) + im*sinpi(z)
	end
	function cispi(z::Complex)
	sipi, copi = sincospi(z)
	return complex(real(copi) - imag(sipi), imag(copi) + real(sipi))
	end

The second line might be a bit of a micro-optimization, but certainly won't hurt.

[simeonschaub]

What's the current status of this? Would definitely be nice to have for consistency, now that we have sincospi.

[simeonschaub]

Bump. @eschnett Do you still intend to finish this? I do think this has value outside being the inverse of signbit.

[eschnett]

@simeonschaub No, I don't think any more that this is a good idea. cispi for floating point numbers makes sense, but not for integers.

[simeonschaub]

I am fine with not special-casing Integer, I just want the generic definitions for real and complex numbers.

[jmert]

Is there any chance this can get finished and merged (just the cispi part, not the relation to signbit part)?

(I can volunteer to cherry-pick onto a new branch/PR and deal with any further review if that'd help. It looks like the suggested changes above plus a few edits to doc strings is all that would be needed.)