Hi – thanks for your suggestion, though it’s a bit of a challenge! Do you know of an example where the existing haddocks have something similar?
The branch cuts and behaviour of negative zeros are just part of the spec for what the functions do. Hence I would expect that anyone who reads the Data.Complex page should want to know about them. (Else it’s a bit like saying “I want to use sqrt but have no interest in knowing that it will only return a positive value”).
Here’s my best attempt at pithy so far:
Data.Complex
Complex numbers that comply with the LIA standards with regard to signed zeros and branch cuts.
Branch Cuts & Principle Values
The “inverse” complex functions (such as sqrt, log, asin, which are mathematically multivalued) return only a single principal value within a defined range. In general, inverse(fn z) == z only when z is within the defined range. The inverse functions are continuous throughout the complex plane except for discontinuities at certain lines on the axes called “branch cuts”.
The ranges and branch cuts comply with the LIA standards and are detailed below. In particular, two (==) points on a branch cut will map to different points on the range boundary if they have zeros of different signs. In some cases this allows apparently identical expressions to be computationally equivalent, for example sqrt(z/(z-1)) * sqrt(1/(z-1)) and sqrt z / (z-1), although detailed analysis is required to determine the behaviour and equivalence of expressions in general.
Note that currently in Haskell:
f1 z = sqrt(z/(z-1)) * sqrt(1/(z-1))
f1 ((-4) :+ 0) = 0.0 :+ 0.4
f2 z = sqrt z / (z-1)
f2 ((-4) :+ 0) = 0.0 :+ (-0.4)
Negative zeros (which GHC supports) provide a mechanism to address this, but only if sqrt makes correct use of it for points on the branch (which it currently does not – hence my proposed fixes, which also address other issues such as overflow, etc).
[If you’re also asking about -0.0 in non-complex functions, here’s an example:
f x = atan(1/x)
Mathematically, f x is undefined at x=0. But, in Haskell, we get f 0 = 1.57.. and f(-0) = -1.57. This mirrors the maths f(x) -> pi/2 as x -> 0 from above, and f(x) -> -pi/2 as x -> 0 from below. (Whether this is what’s required is for the programmer/analyst to determine, depending on the problem being solved).]
Sorry, a not very pithy response 😊
Regards, David.
From: Bryan Richtermailto:b@chreekat.net
Sent: 23 October 2021 07:06
To: David Jamesmailto:dj112358@outlook.com
Cc: Haskell Cafemailto:haskell-cafe@haskell.org
Subject: Re: [Haskell-cafe] Numerics (was: Re: Trouble with asinh)
Hi David,
I have one suggestion for the haddocks. I made a solid effort to wade into the explanation of branch cuts and negative zeros, but I never managed to figure out why I should care. ;) In other words: tl;dr.
Would it be possible to write a pithy few words right at the beginning as an introduction that motivates the topic? If, as you say, few other languages take the subject into account, it's very likely that few programmers take it into account either.
In general, as a math-conscious member of the community, I'm happy to see this kind of work being accomplished, so thanks!
-Bryan
On Fri, 22 Oct 2021, 17.48 David James,