mirror of
https://github.com/apple/swift-numerics
synced 2026-11-22 04:30:45 +00:00
134 lines
4.6 KiB
Swift
134 lines
4.6 KiB
Swift
//===--- Polar.swift ------------------------------------------*- swift -*-===//
|
|
//
|
|
// This source file is part of the Swift Numerics open source project
|
|
//
|
|
// Copyright (c) 2019 - 2021 Apple Inc. and the Swift Numerics project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See https://swift.org/LICENSE.txt for license information
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
import RealModule
|
|
|
|
extension Complex {
|
|
/// The Euclidean norm (a.k.a. 2-norm, `sqrt(real*real + imaginary*imaginary)`).
|
|
///
|
|
/// This property takes care to avoid spurious over- or underflow in
|
|
/// this computation. For example:
|
|
///
|
|
/// let x: Float = 3.0e+20
|
|
/// let x: Float = 4.0e+20
|
|
/// let naive = sqrt(x*x + y*y) // +Inf
|
|
/// let careful = Complex(x, y).length // 5.0e+20
|
|
///
|
|
/// Note that it *is* still possible for this property to overflow,
|
|
/// because the length can be as much as sqrt(2) times larger than
|
|
/// either component, and thus may not be representable in the real type.
|
|
///
|
|
/// For most use cases, you can use the cheaper `.magnitude`
|
|
/// property (which computes the ∞-norm) instead, which always produces
|
|
/// a representable result.
|
|
///
|
|
/// Edge cases:
|
|
/// - If a complex value is not finite, its `.length` is `infinity`.
|
|
///
|
|
/// See also `.magnitude`, `.lengthSquared`, `.phase`, `.polar`
|
|
/// and `init(r:θ:)`.
|
|
@_transparent
|
|
public var length: RealType {
|
|
let naive = lengthSquared
|
|
guard naive.isNormal else { return carefulLength }
|
|
return .sqrt(naive)
|
|
}
|
|
|
|
// Internal implementation detail of `length`, moving slow path off
|
|
// of the inline function. Note that even `carefulLength` can overflow
|
|
// for finite inputs, but only when the result is outside the range
|
|
// of representable values.
|
|
@usableFromInline
|
|
internal var carefulLength: RealType {
|
|
guard isFinite else { return .infinity }
|
|
return .hypot(x, y)
|
|
}
|
|
|
|
/// The squared length `(real*real + imaginary*imaginary)`.
|
|
///
|
|
/// This property is more efficient to compute than `length`, but is
|
|
/// highly prone to overflow or underflow; for finite values that are
|
|
/// not well-scaled, `lengthSquared` is often either zero or
|
|
/// infinity, even when `length` is a finite number. Use this property
|
|
/// only when you are certain that this value is well-scaled.
|
|
///
|
|
/// For many cases, `.magnitude` can be used instead, which is similarly
|
|
/// cheap to compute and always returns a representable value.
|
|
///
|
|
/// See also `.length` and `.magnitude`.
|
|
@_transparent
|
|
public var lengthSquared: RealType {
|
|
x*x + y*y
|
|
}
|
|
|
|
@available(*, unavailable, renamed: "lengthSquared")
|
|
public var unsafeLengthSquared: RealType { lengthSquared }
|
|
|
|
/// The phase (angle, or "argument").
|
|
///
|
|
/// Returns the angle (measured above the real axis) in radians. If
|
|
/// the complex value is zero or infinity, the phase is not defined,
|
|
/// and `nan` is returned.
|
|
///
|
|
/// Edge cases:
|
|
/// - If the complex value is zero or non-finite, phase is `nan`.
|
|
///
|
|
/// See also `.length`, `.polar` and `init(r:θ:)`.
|
|
@inlinable
|
|
public var phase: RealType {
|
|
guard isFinite && !isZero else { return .nan }
|
|
return .atan2(y: y, x: x)
|
|
}
|
|
|
|
/// The length and phase (or polar coordinates) of this value.
|
|
///
|
|
/// Edge cases:
|
|
/// - If the complex value is zero or non-finite, phase is `.nan`.
|
|
/// - If the complex value is non-finite, length is `.infinity`.
|
|
///
|
|
/// See also: `.length`, `.phase` and `init(r:θ:)`.
|
|
public var polar: (length: RealType, phase: RealType) {
|
|
(length, phase)
|
|
}
|
|
|
|
/// Creates a complex value specified with polar coordinates.
|
|
///
|
|
/// Edge cases:
|
|
/// - Negative lengths are interpreted as reflecting the point through the
|
|
/// origin, i.e.:
|
|
/// ```
|
|
/// Complex(length: -r, phase: θ) == -Complex(length: r, phase: θ)
|
|
/// ```
|
|
/// - For any `θ`, even `.infinity` or `.nan`:
|
|
/// ```
|
|
/// Complex(length: .zero, phase: θ) == .zero
|
|
/// ```
|
|
/// - For any `θ`, even `.infinity` or `.nan`, if `r` is infinite then:
|
|
/// ```
|
|
/// Complex(length: r, phase: θ) == .infinity
|
|
/// ```
|
|
/// - Otherwise, `θ` must be finite, or a precondition failure occurs.
|
|
///
|
|
/// See also `.length`, `.phase` and `.polar`.
|
|
@inlinable
|
|
public init(length: RealType, phase: RealType) {
|
|
if phase.isFinite {
|
|
self = Complex(.cos(phase), .sin(phase)).multiplied(by: length)
|
|
} else {
|
|
precondition(
|
|
length.isZero || length.isInfinite,
|
|
"Either phase must be finite, or length must be zero or infinite."
|
|
)
|
|
self = Complex(length)
|
|
}
|
|
}
|
|
}
|