NumericAL
A header-only C++20 lexer built on REAL
Loading...
Searching...
No Matches
Namespaces | Macros | Functions | Variables
complex_math.hpp File Reference

The elementary functions of a complex number of float or double as the GNU C library computes them (NumPy's on Linux, to the bit): C's Annex G for the infinities and NaNs, scaled against overflow, the logarithm's real part near the unit circle from an almost exact x² + y² − 1. More...

#include <algorithm>
#include <array>
#include <cmath>
#include <complex>
#include <concepts>
#include <cstddef>
#include <limits>
#include <numbers>
Include dependency graph for complex_math.hpp:

Go to the source code of this file.

Namespaces

namespace  numerical
 The NumericAL public API.
 
namespace  numerical::detail
 

Macros

#define NUMERICAL_OUT_OF_LINE   [[gnu::noinline]]
 

Functions

void numerical::detail::sine_and_cosine (double x, double &sine, double &cosine)
 sin and cos of x together, as glibc's complex functions take them: its sincos under glibc (whose single-precision one strayed from sinf and cosf by a unit in the last place before 2.29), the system's __sincos on macOS (a compiler may fuse a sin and a cos into it where it inlines them, and it strays from them by a unit: the same call in every context), std::sin and std::cos elsewhere.
 
void numerical::detail::sine_and_cosine (float x, float &sine, float &cosine)
 sine_and_cosine of a float.
 
template<std::floating_point R>
R numerical::detail::separate_sine (R x)
 std::sin of x in a call of its own, as NumPy's formulas take it: no build fuses it with a cos of the same argument into a sincos, which strays from them by a unit in the last place (glibc's sincosf before 2.29, macOS's __sincos).
 
template<std::floating_point R>
R numerical::detail::separate_cosine (R x)
 std::cos of x in a call of its own, as separate_sine.
 
bool numerical::detail::libm_fuses () noexcept
 Whether the C library's complex functions fuse their sums of products, a·b + c·d as fma(a, b, c·d), off arm64 (where FMA is in every build's baseline, and they do): under glibc as its build does, read once from its ctan of a number whose cos² + sinh² the two round apart. glibc 2.43 fuses there on an AMD EPYC 7763 (GitHub's Ubuntu 26.04 runners) and not on an Intel Core i5-8500, the same library; NumPy's complex functions are glibc's. Elsewhere no.
 
template<std::floating_point R>
R numerical::detail::libm_sum_of_products (R a, R b, R c, R d)
 a·b + c·d as the C library's build computes it: fma(a, b, c·d) where it fuses (libm_fuses), each product rounded elsewhere.
 
template<std::floating_point R>
R numerical::detail::libm_add_product (R s, R a, R b)
 s + a·b as the C library's build computes s += a·b: fused where it fuses, as libm_sum_of_products.
 
template<std::floating_point R>
void numerical::detail::small_sincos (R x, R &sine, R &cosine)
 sin and cos of x (sine_and_cosine), or x and 1 for one under the smallest normal value (an exact sine there).
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_exp (const std::complex< R > &z)
 exp(z): exp(re) times cos(im) + i sin(im), a real part past exp_bound taken off in steps of it (each a factor exp(bound) on the sine and the cosine), so that a finite product does not overflow early.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_cosh (const std::complex< R > &z)
 cosh(z): cosh(re) cos(im) + i sinh(re) sin(im); past exp_bound, exp(|re|) / 2 times the cosine and the sine, taken off in steps as complex_exp does.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_sinh (const std::complex< R > &z)
 sinh(z): sinh(re) cos(im) + i cosh(re) sin(im) of |re|, the sign of re carried by the cosine; past exp_bound as complex_cosh.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_cos (const std::complex< R > &z)
 cos(z), as cosh(i z): complex_cosh of −im + i re.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_sin (const std::complex< R > &z)
 sin(z): sin(re) cosh(im) + i cos(re) sinh(im) of |re|, the sign of re carried by the sine; an imaginary part past exp_bound as complex_sinh's real part.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_tanh (const std::complex< R > &z)
 tanh(z): (sinh(re) cosh(re) + i sin(im) cos(im)) / (sinh(re)² + cos(im)²); past half_exp_bound the real part is ±1 and the imaginary one 4 sin(im) cos(im) / exp(2|re|), divided in steps.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_tan (const std::complex< R > &z)
 tan(z): (sin(re) cos(re) + i sinh(im) cosh(im)) / (cos(re)² + sinh(im)²); past half_exp_bound the imaginary part is ±1 and the real one 4 sin(re) cos(re) / exp(2|im|), divided in steps.
 
double numerical::detail::unit_circle_offset (double x, double y)
 x² + y² − 1 for 0.5 ≤ x < 1, y ≤ x and x² + y² ≥ 0.5, almost exactly: each square split into its rounded value and its error (a fused multiply-add), the five terms summed by magnitude, each pair's error carried to the next.
 
float numerical::detail::unit_circle_offset (float x, float y)
 unit_circle_offset of floats, in double: (x − 1)(x + 1) + y².
 
template<std::floating_point R>
bool numerical::detail::unit_circle_squares_reach_half (R x, R y)
 Whether x² + y² ≥ 0.5, as glibc's build computes the sum (libm_sum_of_products).
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_log (const std::complex< R > &z)
 log(z): log|z| + i arg(z), log|z| as log1p(|z|² − 1) / 2 near the unit circle (|z|² − 1 exact or almost, unit_circle_offset) and as log(hypot) elsewhere, the larger part scaled by 2 near overflow and both by 2^digits under the smallest normal value.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_sqrt (const std::complex< R > &z)
 The square root of a complex number, as the GNU C library's csqrt computes it (NumPy's on Linux, to the bit): the infinities and NaNs of C's Annex G; a real or an imaginary argument apart (the root of -1 is i exactly, that of y i has equal parts); otherwise sqrt((|z| ± re) / 2) for the larger part and the imaginary part over twice it for the other, scaled by 4 near overflow and by a power of 2 among subnormal parts. std::sqrt of libc++ goes through the polar form: sqrt(-1e20 + 1j) in single precision had a real part of 755 for 5e-11.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_atanh (const std::complex< R > &z)
 atanh(z), as glibc's catanh: C's Annex G for the infinities and NaNs; π/2 and the reciprocal past 16/ε; else the real part log(|1 + z|² / |1 − z|²) / 4 (by log1p(4x / |1 − z|²) where the quotient is at least ½), the imaginary part atan2(2y, 1 − |z|²) / 2, 1 − |z|² from unit_circle_offset where it cancels.
 
template<std::floating_point R>
std::complex< R > numerical::detail::kernel_asinh (const std::complex< R > &z, bool adjust)
 asinh(z) of a finite nonzero z, as glibc's __kernel_casinh, its imaginary part taken from π/2 where adjust (acos and acosh through it): the first quadrant's |re| and |im|, by the region they lie in, log(2z) past 1/ε, log(z + √(1 + z²)) by log1p and atan2 of parts that do not cancel nearer 1, else that sum by complex_sqrt and complex_log; the signs of z's parts given back last. Each product whose every use is a sum fused where the C library's build fuses (libm_add_product, libm_sum_of_products): GCC's contraction of glibc on arm64.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_asinh (const std::complex< R > &z)
 asinh(z), as glibc's casinh: C's Annex G for the infinities and NaNs, z itself at ±0 ± 0i, else kernel_asinh.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_asin (const std::complex< R > &z)
 asin(z), as glibc's casin: −i asinh(iz); a NaN part as Annex G has it.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_acos (const std::complex< R > &z)
 acos(z), as glibc's cacos: π/2 − asin(z) for the infinities, NaNs and zeros, else kernel_asinh of iz adjusted.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_acosh (const std::complex< R > &z)
 acosh(z), as glibc's cacosh: Annex G for the infinities, NaNs and zeros, else kernel_asinh of iz adjusted, its sign by z's imaginary part's.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_atan (const std::complex< R > &z)
 atan(z), as glibc's catan: C's Annex G for the infinities and NaNs; π/2 and the reciprocal past 16/ε; else the real part atan2(2x, 1 − |z|²) / 2, 1 − |z|² from unit_circle_offset where it cancels, the imaginary part log(|z + i|² / |z − i|²) / 4 (by log1p(4y / |z − i|²) where the quotient is at least ½): complex_atanh's turned a quarter, each operation in glibc's order.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_log2 (const std::complex< R > &z)
 log2(z), as NumPy's: complex_log times log₂ e, each part.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_log10 (const std::complex< R > &z)
 log10(z), as NumPy's: complex_log times log₁₀ e, each part.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_exp2 (const std::complex< R > &z)
 2^z, as NumPy's: complex_exp of z times ln 2, each part.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_expm1 (const std::complex< R > &z)
 exp(z) − 1, as NumPy's: expm1(re) cos(im) − 2 sin²(im/2) + i exp(re) sin(im), the sine and the cosine of im in calls of their own as NumPy's (separate_sine); past exp_bound, a finite im's complex_exp less 1, where exp(re) overflows and NumPy's product with the sine with it (NaN at +∞ + 0i, an infinite 710.2 + 0.1i).
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_log1p (const std::complex< R > &z)
 log(1 + z): the imaginary part atan2(im, 1 + re), as NumPy's; the real part log|1 + z|, by log1p(d) / 2 of d = |1 + z|² − 1 = 2re + re² + im² where |re| and |im| are at most 3 and d at least −½ (the squares exact by fused multiply-adds, the sum compensated: d keeps its digits where it cancels, about the circle |1 + z| = 1 and about 0, where NumPy's log(hypot(1 + re, im)) loses them all); else complex_log of 1 + z, |1 + z| there far from 1 or 1 + re exact, finite to the largest numbers (NumPy's hypot overflows past max / √2). A zero is its own, its signs kept, as log1p of a real −0.
 
template<std::floating_point R>
std::complex< R > numerical::detail::complex_sign (const std::complex< R > &z)
 z / |z|, as NumPy 2's sign of a complex number and the array API's: 0 for 0, NaN for a NaN modulus, and for an infinite modulus ±1 along the infinite part (NaN where both are), 0 across it.
 

Variables

template<std::floating_point R>
constexpr R numerical::detail::exp_bound {static_cast<R>(static_cast<int>(static_cast<R>(std::numeric_limits<R>::max_exponent - 1) * std::numbers::ln2_v<R>))}
 The real part past which exp of it overflows, rounded down: 709 for double, 88 for float.
 
template<std::floating_point R>
constexpr R numerical::detail::half_exp_bound {static_cast<R>(static_cast<int>(static_cast<R>(std::numeric_limits<R>::max_exponent - 1) * std::numbers::ln2_v<R> / R {2}))}
 Half of it, past which tanh's parts are ±1 and a quotient by exp(2x): 354 for double, 44 for float.
 

Detailed Description

The elementary functions of a complex number of float or double as the GNU C library computes them (NumPy's on Linux, to the bit): C's Annex G for the infinities and NaNs, scaled against overflow, the logarithm's real part near the unit circle from an almost exact x² + y² − 1.

std::exp, std::log, std::sin, std::cos, std::tan and std::tanh of a complex number are libc++'s on macOS and MSVC's on Windows, which lose a part where glibc's do not: tan(1e308 + 0j) was NaN for −0.509, sin(1e308 j) had a NaN real part for 0, log(1 + 1e-20 j) a real part of 0 for 5e-41. Each sum below is a statement of its own, so that no build contracts it into a fused multiply-add glibc's does not compute.

Definition in file complex_math.hpp.

Macro Definition Documentation

◆ NUMERICAL_OUT_OF_LINE

#define NUMERICAL_OUT_OF_LINE   [[gnu::noinline]]

Definition at line 29 of file complex_math.hpp.