Numerics 1.0 release plans

Hi all --

I am planning to tag Numerics 1.0.0 in the next couple weeks (and have created a release/1.0 branch from which it will be tagged). From that point forward, there will be a somewhat higher bar to any source-breaking changes. If there's anything you would like me to consider tweaking before then, now is the time to speak up.

I do not plan to have any significant changes in the 1.0 tag. I do plan to write some additional documentation between now and then, so any notes about things that you would like me to clarify are especially appreciated.


There is an Augmented type which contains a few utility functions and is not documented. It looks like it was accidentally made public, but it would become stable API if left in for v1.0.

Do you intend to leave it, or should it be made internal?


It has to be public because it is used from ComplexModule. I could move it into Complex as an implementation detail, but these are generally useful, and the API is unlikely to change (the names are weird, but terms of art for low-level numerics stuff). So I am more likely to document them, but I will give it some thought.

Can they be underscored for now?

1 Like

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:).


Right, fastTwoSum can definitely not just be named sum(_:_:). product does not suffer from this difficulty, since it always produces the exact result barring overflow or underflow.


Renaming Augmented to ErrorFreeTransformations, calling the functions either fastTwoSum etc. (and possibly adding more EFTs) or augmentedAddition etc. as in 754-2019?

The IEEE 754 (2019) augmentedAddition is a slightly different operation.

ErrorFreeTransforms feels too verbose for my taste. If I were going to change the name, I would use AugementedArithmetic, but Augmented.product(a, b) reads better than AugmentedArithmetic.product(a, b) at the site of use, to my mind. I do plan to add more of them, but probably only as needed for other things I want to provide.

That's also an option, but I would prefer to just document them, so long as I have a name that I'm happy with (which I think I do); they're stable interfaces up to naming.



Are Quaternions going to be included in the release?

No; I'm going to start looking at merging @markuswntr's quaternions work following 1.0.


Gotcha, thanks!

It's great to see Numerics reach 1.0 :clap: