CMake build support for arm64/macOS

This release adds support for the CMake build in macOS on arm64. Thanks to @DanboDuan for the patch.

Differentiable cannot be stable

This tag contains no code changes, but clarifies in the readme that API defined in a conformance to Differentiable cannot be source-stable, because Differentiable itself is not stable. Thanks @rxwei for reminding me to clarify this.

Stable at last!

Welcome to the first stable release of Swift Numerics!

Not much has changed from 0.1.0, except that I'm declaring the API of RealModule and ComplexModule to be stable. There is some expanded documentation for the reciprocal property on AlgebraicField, including discussion of error bounds for Real and Complex types.

The only breaking change from 0.1.0 is that Augmented.fastTwoSum and Augmented.twoProdFMA have been deprecated and renamed Augmented.sum(large:small:) and Augmented.product. This change is not expected to effect many users, and the deprecation should make clear how to update your code if necessary. As always, raise a GitHub issue or post on the forums if you have questions.

Complex ... and yet Elementary

Howdy buckaroos! It's been a while since the last release, as I've been busy with some real-life stuff.

But now I'm back to the grindstone, and I've got a fun release for you. There's a bunch of cleanups and improvements from various contributors (@NevinBR and @markuswntr come to mind), but the big news is that Complex types now conform to the ElementaryFunctions protocol, which means that all your favorite math functions are available for complex types.

The branch cuts of these complex functions should generally match C and C++'s (because all implementations follow Kahan's standard paper on the subject), though the exact numerical results will be slightly different in general. Unlike the real functions, the complex elementary functions are all implemented in Swift--we don't delegate to the host system math library. This is because the general quality of <complex.h> implementations is significantly lower than <math.h> implementations, and some platforms (Windows) don't provide those operations at all. In general, I believe that the basic algorithms used by Swift Numerics for these operations are as good as (and often better) than what C libraries provide, but there is always a possibility of bugs, especially with new code. Don't hesitate to raise an issue if you see anything you suspect.

Special thanks to @compnerd for going above and beyond tracking down a Swift bug that held up this tag (and @eeckstein for fixing it!)

Xcode 12 support

This is a quick-fix release to address a bug reported with Float16 availability in Xcode 12 on Catalina. No puns, sorry 😂

This time will be different...iable?

Hey all, lots of updates in this release:

First, the big features:

• Differentiable and Float16 support is live in Swift Numerics. These are protected behind swift version checks, so you'll only see them when you're building with a Swift 5.3 or later toolchain (because earlier toolchains don't have the necessary support). For Float16, you need to also be targeting a platform with support in the standard library (i.e. not macOS). For Differentiable, you need to be using a toolchain that was built with differentiable programming support enabled.

• Approximate equality comparisons have been added for types conforming to Numeric when the associatedtype Magnitude conforms to FloatingPoint. This includes all of the Real types, but also includes Complex, and can be extended to lots of other useful types as well. The most basic use is:

  a.isApproximatelyEqual(to: b)
  

  which performs a comparison with default relative tolerance. You can manually specify an absolute or relative tolerance (or both), as well as a norm to use via overloads and optional arguments. Consult the doc comments for more information now, but I plan to write a more in-depth README for the feature in the coming weeks.

Two implementation details have also been added on Real, which are useful for building out other parts of the library:

• cosMinusOne(_ x: Self) -> Self
  This is "just expMinusOne(_:Self), but for cosine". It's a somewhat niche feature (and trivially implementable via the half-angle formula), but it turns out to be useful when building out ElementaryFunctions support for Complex types, so it seems to make good sense to make more broadly available.
• _mulAdd(_ a: Self, _ b: Self, _ c: Self) -> Self
  This is intended to use either an FMA or separate multiply and add to evaluate a*b + c as efficiently as possible. This is a much more niche implementation detail, and the name is subject to change (hence the underscore), but it's useful enough to expose for anyone who wants to use it.

Speaking of ElementaryFunctions support for Complex types, that's something that's in progress now (#146). I'll be working through it over the next few weeks, and would love to have contributions. If you'd like to contribute, be sure to read the implementation goals. Simply borrowing from C or C++ implementations will probably not be sufficient for the goals we have and semantics defined for Complex, but you can use them as a starting point if you're willing to iterate with me a bit.

Thanks everyone!

Forums discussion here: https://forums.swift.org/t/0-0-7-release-notes/39680

Fenestration

There are a bunch of small changes in this release:

• Added Windows support via CMake build system, contributed by @compnerd (special thanks for your patience!)

• I removed the Complex benchmarks from the test targets. Semantically, benchmarks are not the same as tests, and we don't need these to run in the same conditions. Further, the Xcode benchmark infrastructure isn't quite what we want for these, and they don't work on Windows anyway, because clang does not support C complex multiplication or division on Windows. These benchmarks will return in the next release in the form of an executable target.

• Complex<T> now conforms to Differentiable if you are using a toolchain that supports Differentiable programming and T is Differentiable. Thanks to @rxwei and @dan-zheng for their work on this.

• Some documentation fixes for Complex fell out from work that @markuswntr has been doing on Quaternions (check out the Quaternions branch to play with it, and help review his PRs)

• I fixed a bug in pow(Float/Double, Int) for exceptionally large exponents. It's unlikely that this ever caused any real problems, because it only occurs when the exponent is so large that the result should always be 0, 1, or infinity, but now we get the right answer for these cases.

A reminder that Float16 support is available on the swift-5.3 branch, which will be merged to master when swift-5.3 is released. When that happens, I will also create a LTS swift-5.2 branch to support older toolchains that do not have Float16 support.

Any questions or problems can be discussed on the GitHub repo or on the Swift Forums: https://forums.swift.org/t/0-0-6-release-notes/38146

I saw the Sign, and it opened up my mind

There are two changes in this release:

• AlgebraicField now refines SignedNumeric instead of Numeric. This should have no visible change for most users, because all conforming types (Float, Double, Float80, and Complex) already conform to SignedNumeric. However, users who have code that is generic over the AlgebraicField protocol can now use unary negation (or remove existing explicit SignedNumeric constraints from that code).

• The Real and Complex modules have been renamed RealModule and ComplexModule. If you import Numerics, then this change does not affect you. However, if you currently import either Real or Complex directly, you will need to update your import statements. (sorry!)

  This is not a change that I make lightly; I would very much prefer to avoid this sort of churn, even though Swift Numerics hasn't yet declared 1.0. However, there are real limitations of the current name lookup system, which prevents use of some nice patterns when a module name shadows a type.

  E.g. with this change, a user who mostly only wants to work with complex doubles can do the following:

  import ComplexModule
  
  typealias Complex = ComplexModule.Complex<Double>
  
  // Can now use the simpler name Complex for Complex<Double>:
  func foo(_ z: Complex) -> Complex {
    ...
  }
  
  // But can still get at the generic type when necessary:
  let a = ComplexModule.Complex<Float>

  Any Swift Numerics module that might have this ambiguity will be suffixed with Module in the future (just like the pattern of protocols being suffixed with Protocol when necessary to break ambiguity).

As always, if you have any questions or comments, there is a forums thread for discussing this release.

We will not be Fielding further questions at this time

There are two changes in this release to call out specifically:

• Complex's conformance to Codable now uses an unkeyed container, so e.g. .zero gets encoded as [0,0] in JSON instead of the old {"x":0, "y":0}.

• There's a new protocol, AlgebraicField refining Numeric by adding the /, /= operators, and a .reciprocal: Self? property. The Real protocol refines it and Complex<T> conforms to it, allowing you to write code that is generic over them. There are some additional operations that it probably makes sense to add to this protocol (e.g. square root); I expect to add them gradually as needed.

I also want to draw special attention to a change that I expect to make in the next tag. In order to make certain use patterns simpler, I intend to give the Complex module a name that doesn't conflict with the Complex type. If you have opinions about this change, or suggestions for a naming pattern to adopt for modules in Swift Numerics, please weigh in on that thread.

If you have any questions, use this discussion thread on the Swift forums.

We have the power

In earlier releases, Real.pow(Self, Int) simply called through to libm_pow. This is generally acceptable on platforms with a decent math library, but gets some cases wrong for Float and Double when the exponent is so large that it would be rounded in conversion to Self.

For example, consider Float.pow(-1, 0x1000001). Since the exponent is odd, the result should be -1, but when we simply called libm_pow(-1, Float(0x1000001)), the exponent was rounded to an even number, and the result was 1.

This behavior is fixed in this release; in particular the parity of integer exponents is always preserved, so that we will not have sign errors like above. There is still additional work to be done on the Real.pow implementations--especially to provide better support for platforms with suspect math libraries--but this is a significant improvement to these operations.