mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
Massage docc files to make the Documentation check happier
This commit is contained in:
8 files changed
+38
-15
No files matched your search
@@ -185,7 +185,7 @@ extension Complex {
|
||||
self.init(real, 0)
|
||||
}
|
||||
|
||||
/// The complex number with specified imaginary part and zero real part.
|
||||
/// The complex number with zero real part and specified imaginary part.
|
||||
///
|
||||
/// Equivalent to `Complex(0, imaginary)`.
|
||||
@inlinable
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# ``Complex``
|
||||
|
||||
A Complex number type that conforms to ``AlgebraicField`` (so all the normal
|
||||
arithmetic operations are available) and ``ElementaryFunctions`` (so all
|
||||
the usual math functions are available).
|
||||
A Complex number type that conforms to `AlgebraicField`
|
||||
(so all the normal arithmetic operations are available) and
|
||||
`ElementaryFunctions` (so all the usual math functions are
|
||||
available).
|
||||
|
||||
A `Complex` value is represented with two `RealType` values, corresponding to
|
||||
the real and imaginary parts of the number.
|
||||
@@ -42,7 +43,7 @@ details.
|
||||
- ``imaginary``
|
||||
- ``rawStorage``
|
||||
- ``init(_:_:)``
|
||||
- ``init(_:)-(RealType)``
|
||||
- ``init(_:)-5aesj``
|
||||
- ``init(imaginary:)``
|
||||
|
||||
### Phase, length and magnitude
|
||||
|
||||
@@ -2,7 +2,9 @@
|
||||
|
||||
Types and operations for working with complex numbers.
|
||||
|
||||
## Representation
|
||||
## Overview
|
||||
|
||||
### Representation
|
||||
|
||||
The `Complex` type is generic over an associated `RealType`; complex numbers
|
||||
are represented as two `RealType` values, the real and imaginary parts of the
|
||||
@@ -28,7 +30,7 @@ Functions taking complex arguments in these other languages are not
|
||||
automatically converted on import, but you can safely write shims that
|
||||
map them into Swift types by converting pointers.
|
||||
|
||||
## Real-Complex arithmetic
|
||||
### Real-Complex arithmetic
|
||||
|
||||
Because the real numbers are a subset of the complex numbers, many
|
||||
languages support arithmetic with mixed real and complex operands.
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
Semantics of `Complex` zero and infinity values, and important considerations
|
||||
when porting code from other languages.
|
||||
|
||||
## Overview
|
||||
|
||||
Unlike C and C++'s complex types, `Complex` does not attempt to make a
|
||||
semantic distinction between different infinity and NaN values. Any `Complex`
|
||||
datum with a non-finite component is treated as the "point at infinity" on
|
||||
@@ -12,7 +14,7 @@ As a consequence, all values with either component infinite or NaN compare
|
||||
equal, and hash the same. Similarly, all zero values compare equal and hash
|
||||
the same.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
This choice has some drawbacks,¹ but also some significant advantages.
|
||||
In particular, complex multiplication is the most common operation performed
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
Introduction to the concept of norm and discussion of the `Complex` type's
|
||||
`.magnitude` property.
|
||||
|
||||
## Overview
|
||||
|
||||
In mathematics, a *norm* is a function that gives each element of a vector
|
||||
space a non-negative length.¹
|
||||
|
||||
@@ -33,7 +35,7 @@ The three most commonly-used norms are:
|
||||
The `Complex` type gives special names to two of these norms; `length`
|
||||
for the 2-norm, and `magnitude` for the ∞-norm.
|
||||
|
||||
## Magnitude:
|
||||
### Magnitude:
|
||||
|
||||
The `Numeric` protocol requires us to choose a norm to call `magnitude`,
|
||||
but does not give guidance as to which one we should pick. The easiest choice
|
||||
@@ -68,7 +70,7 @@ Complex(2, 3).magnitude // 3
|
||||
Complex(-1, 0.5).magnitude // 1
|
||||
```
|
||||
|
||||
## Length:
|
||||
### Length:
|
||||
|
||||
The `length` property of a `Complex` value is its Euclidean norm.
|
||||
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Namespace for augmented arithmetic operations.
|
||||
public enum Augmented { }
|
||||
|
||||
extension Augmented {
|
||||
@@ -96,10 +97,11 @@ extension Augmented {
|
||||
/// error from that computation rounded to the closest representable
|
||||
/// value.
|
||||
///
|
||||
/// Unlike ``sum(large:small:)``, the magnitude of the summands does not
|
||||
/// matter. If you know statically that `a.magnitude >= b.magnitude`, you
|
||||
/// should use ``sum(large:small:)``. If you do not have such a static
|
||||
/// bound, you should use this function instead.
|
||||
/// The magnitude of the summands does not change the result of this
|
||||
/// operation. If you know statically that `a.magnitude >= b.magnitude`,
|
||||
/// you may want to consider using ``sum(large:small:)`` to get the same
|
||||
/// result somewhat more efficiently. If you do not have such a static
|
||||
/// bound, you usually want to use this function instead.
|
||||
///
|
||||
/// Unlike ``product(_:_:)``, the rounding error of a sum never underflows.
|
||||
///
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# ``Augmented``
|
||||
|
||||
A namespace for a family of algorithms that compute the results of floating-
|
||||
point arithmetic using multiple values such that either the error is minimized
|
||||
or the result is exact.
|
||||
|
||||
## Overview
|
||||
|
||||
Consider multiplying two Doubles. A Double has 53 significand bits, so their
|
||||
@@ -17,4 +21,11 @@ the low-order part of the product suddenly becomes significant:
|
||||
let result = 1 - c // exactly zero, but "should be" 2⁻¹⁰⁴
|
||||
```
|
||||
Augmented arithmetic is a building-block that library writers can use to
|
||||
handle cases like this more carefully.
|
||||
handle cases like this more carefully. For the example above, one might
|
||||
compute:
|
||||
```swift
|
||||
let (head, tail) = Augmented.product(a,b)
|
||||
```
|
||||
`head` is then 1.0 and `tail` is -2⁻¹⁰⁴, so no information has been lost.
|
||||
Of course, the result is now split across two Doubles instead of one, but the
|
||||
information in `tail` can be carried forward into future computations.
|
||||
@@ -1,5 +1,8 @@
|
||||
# ``Relaxed``
|
||||
|
||||
A namespace for a family of operations that "relax" the usual rules for
|
||||
floating-point to allow reassociation of arithmetic and FMA formation.
|
||||
|
||||
## Overview
|
||||
|
||||
Because of rounding, and the arithmetic rules for infinity and NaN values,
|
||||
|
||||
Reference in new issue
Block a user