There used to not be any way to attach reassociate or contract flags to fadd/fmul from Swift, which meant that we had to use inline C shims to accomplish this. But I added some Builtins to Swift, so now we don't need C to do this any longer.
Add a comprehensive DocC guide for ApproximateEquality covering:
- Background and motivation for approximate equality in floating-point math
- Relative and absolute tolerance guidelines and formulas
- Special value handling (NaN, infinities, signed zeroes)
- Custom norms with AdditiveArithmetic
- Mathematical properties (non-transitivity and why not to use for Equatable)
Also update RealModule.md to link to the DocC article and restore the
Approximate equality section with a link in Sources/RealModule/README.md.
Resolves#153.
Signed-off-by: reginaldalfret <reginaldalfret@gmail.com>
This commit _also_ relaxes the constraint on Augmented algorithms from Real to FloatingPoint. It's worth calling out that fastTwoSum does not work with decimal floating-point types, so the unordered `Augemented.sum(_:_:)` now has a radix check and calls into the ordered twoSum function instead for Decimal. This makes more sense that a `BinaryFloatingPoint` constraint, as otherwise generic code written against Real or FloatingPoint would have to do the check at every call site.
This is potentially useful to identify some bugs, but there are also algorithms (notably Kahan summation) that can be written in terms of fast2sum but would fail this check. Rework documentation to account for the change.
This is potentially useful to identify some bugs, but there are also algorithms (notably Kahan summation) that can be written in terms of fast2sum but would fail this check. Rework documentation to account for the change.
This is formally a source-breaking change. However it is expected to not be source-breaking in practice, because any conforming type either has a real magnitude (in the case of real or complex types), which would necessarily have to support all the AF operations to implement the type, or is perhaps a finite field with a bogus stand-in Magnitude.
This commit adds the following to the RealFunctions protocol:
static func _relaxedAdd(_:Self, _:Self) -> Self
static func _relaxedMul(_:Self, _:Self) -> Self
These are equivalent to + and *, but have "relaxed semantics"; specifically, they license the compiler to reassociate them and to form FMA nodes, which are both significant optimizations that can easily make many common loops 8-10x faster. These transformation perturb results slightly, so they should not be enabled without care, but the results with the relaxed operations are--for most purposes--"just as good as" (and often better than) what strict operations produce. The main thing to beware of is that they are no longer portable; different compiler versions and different targets and optimization flags will result in different results.
They are underscored because they are not stable API. In particular:
- `RealFunctions` is not really the right protocol for these (and neither is `Real`). I need to do some thinking about where to attach them.
- Even if it were the right protocol, these are more like implementation hooks than the API I really want people to use (TBD).
- I like "relaxed" more than other commonly used idioms ("fast"), but I'm not sure it's the name I ultimately want.
In older toolchains, Float16 is marked unavailable on all mac targets; starting with the 5.4 toolchain, it is available starting in macOS 11.0 when targeting Apple Silicon.
These significantly improve on the state of the art for arguments close to the circle where the result vanishes, producing good componentwise relative accuracy as well as relative accuracy in the complex norm.
Also drops the argument parser dependency, which is desirable to avoid possible circular dependencies in the future with algorithms.