From a Swift API-design perspective, the existing methods on Augmented probably ought to be spelled more like sum and product.
The exact behavior / implementation details can be described in the documentation, but at the point of use I think it reads much better to have, eg:
let (a,b) = Augmented.product(u, u)
let (c,d) = Augmented.product(v, v)
var (s,e) = Augmented.sum(-1, a)
s = (s + c) + e + b + d
return Complex(.log(onePlus: s)/2, θ)
Rather than:
let (a,b) = Augmented.twoProdFMA(u, u)
let (c,d) = Augmented.twoProdFMA(v, v)
var (s,e) = Augmented.fastTwoSum(-1, a)
s = (s + c) + e + b + d
return Complex(.log(onePlus: s)/2, θ)
• • •
Personally, I had never encountered the terms “twoProdFMA” and “fastTwoSum” before seeing them in Numerics, and their meanings were not immediately clear.
Even today, despite having previously read through their implementations when they were added, I needed to re-read their implementations again because their names did not elicit understanding.
Searching on Google shows only 231 results for “twoProdFMA”, the 2nd-highest of which is Swift Numerics. Actually clicking through the result pages reveals that in fact only 38 distinct results are available.
Doing the same for “fastTwoSum” is slightly better, with 2,480 results appearing at first. However clicking through the pages brings that down to only 89.
• • •
So, even if these are technical terms of art, from my perspective they are such esoteric terms that their use will not actually inform most experts in the art about what they do.
I think it is sufficient to mention the term of art in the documentation for each method, while giving those methods readable names that convey what the result of the operation is:
They are the sum and product operations, and the fact that they are located on Augmented implies the (head, tail) format.
Although the precondition that fastTwoSum takes its arguments in order of decreasing magnitude suggests that perhaps a slightly more specific spelling would be appropriate.
I don’t think the word “two” is useful here, so perhaps fastSum, or sum(large:small:).
