pygeodesy.fmath

Package pygeodesy :: Module fmath |
[frames] | no frames]

# Module fmath

Utilities for precision floating point summation, multiplication, `fused-multiply-add`, polynomials, roots, etc.

Version: 26.01.06

Classes
| Fdot Precision dot product.
| Fdot_ Precision dot product.
| Fhorner Precision polynomial evaluation using the Horner form.
| Fhypot Precision summation and hypotenuse, default `root=2`.
| Fpolynomial Precision polynomial evaluation.
| Fpowers Precision summation of powers, optimized for `power=2, 3 and 4`.
| Froot The root of a precision summation.
| Fcbrt Cubic root of a precision summation.
| Fsqrt Square root of a precision summation.

Functions
bqrt(x) Return the 4-th, bi-quadratic or quartic root, x**(1 / 4), preserving `type(x)`. |
cbrt(x) Compute the cube root x**(1/3), preserving `type(x)`. |
cbrt2(x) Compute the cube root squared x**(2/3), preserving `type(x)`. |
euclid(x, y) Appoximate the norm sqrt(x**2 + y**2) by max(abs(x), abs(y)) + min(abs(x), abs(y)) * 0.4142.... |
euclid_(*xs) Appoximate the norm sqrt(sum(x**2 for x in xs)) by cascaded euclid. |
facos1(x) Fast approximation of pygeodesy.acos1`(x)`, scalar. |
fasin1(x) Fast approximation of pygeodesy.asin1`(x)`, scalar. |
fatan(x) Fast approximation of `atan(x)`, scalar. |
fatan1(x) Fast approximation of `atan(x)` for `0 <= x < 1`, unchecked. |
fatan2(y, x) Fast approximation of `atan2(y, x)`, scalar. |
favg(a, b, f=0.5, nonfinites=True) Return the precise average of two values. |
fdot(xs, *ys, **start_f2product_nonfinites) Return the precision dot product start + sum(xs[i] * ys[i] for i in range(len(xs))). |
fdot_(*xys, **start_f2product_nonfinites) Return the (precision) dot product start + sum(xys[i] * xys[i+1] for i in range(0, len(xys), 2)). |
fdot3(xs, ys, zs, **start_f2product_nonfinites) Return the (precision) dot product start + sum(xs[i] * ys[i] * zs[i] for i in range(len(xs))). |
fhorner(x, *cs, **incx) Horner form evaluation of polynomial sum(cs[i] * x**i for i=0..n) as in- or decreasing exponent sum(... i=n..0), where `n = len(cs) - 1`. |
fidw(xs, ds, beta=2) Interpolate using Inverse Distance Weighting (IDW). |
fma(x, y, z, **nonfinites) Fused-multiply-add, using `math.fma(x, y, z)` in Python 3.13+ or an equivalent implementation. |
fmean(xs) Compute the accurate mean sum(xs) / len(xs). |
fmean_(*xs, **nonfinites) Compute the accurate mean sum(xs) / len(xs). |
f2mul_(x, *ys, **nonfinites) Cascaded, accurate multiplication `x * y * y ...` for all `ys`. |
fpolynomial(x, *cs, **over_f2product_nonfinites) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) [/ over]. |
fpowers(x, n, alts=0) Return a series of powers [x**i for i=1..n], note 1..! |
fprod(xs, start=1) Iterable product, like `math.prod` or `numpy.prod`. |
frandoms(n, seeded=None) Generate `n` (long) lists of random `floats`. |
frange(start, number, step=1) Generate a range of `float`s. |
value |
freduce(function, sequence, initial=...) Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. |
fremainder(x, y) Remainder in range `[-y / 2, y / 2]`. |
hypot(x, y) Return the Euclidean distance, sqrt(x*x + y*y). |
hypot_(*xs) Compute the norm sqrt(sum(x**2 for x in xs)). |
hypot1(x) Compute the norm sqrt(1 + x**2). |
hypot2(x, y) Compute the squared norm x**2 + y**2. |
hypot2_(*xs) Compute the squared norm `fsum(x**2 for x in xs)`. |
norm2(x, y) Normalize a 2-dimensional vector. |
norm_(*xs) Normalize the components of an n-dimensional vector. |
sqrt0(x, Error=None) Return the square root `sqrt(x)` iff `x >` EPS02, preserving `type(x)`. |
sqrt3(x) Return the square root, cubed sqrt(x)**3 or sqrt(x**3), preserving `type(x)`. |
sqrt_a(h, b) Compute the `a` side of a right-angled triangle from `sqrt(h**2 - b**2)`. |
zcrt(x) Return the 6-th, zenzi-cubic root, x**(1 / 6), preserving `type(x)`. |
zqrt(x) Return the 8-th, zenzi-quartic or squared-quartic root, x**(1 / 8), preserving `type(x)`. |

Variables
| __all__ = `_ALL_LAZY.fmath`

Function Details

### bqrt (x) |
Return the 4-th, bi-quadratic or quartic root, x**(1 / 4), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Quartic root (`float` or an Fsum). Raises: `TypeeError` - Invalid `x`. `ValueError` - Negative `x`. See Also: Functions zcrt and zqrt.

### cbrt (x) |
Compute the cube root x**(1/3), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Cubic root (`float` or Fsum). See Also: Functions cbrt2 and sqrt3.

### cbrt2 (x) |
Compute the cube root squared x**(2/3), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Cube root squared (`float` or Fsum). See Also: Functions cbrt and sqrt3.

### euclid (x, y) |
Appoximate the norm sqrt(x**2 + y**2) by max(abs(x), abs(y)) + min(abs(x), abs(y)) * 0.4142.... Arguments: `x` - X component (`scalar`, an Fsum or Fsum2Tuple). `y` - Y component (`scalar`, an Fsum or Fsum2Tuple). Returns: Appoximate norm (`float` or Fsum). See Also: Function euclid_.

### euclid_ (*xs) |
Appoximate the norm sqrt(sum(x**2 for x in xs)) by cascaded euclid. Arguments: `xs` - X arguments (each `scalar`, an Fsum or Fsum2Tuple), all positional. Returns: Appoximate norm (`float` or Fsum). See Also: Function euclid.

### facos1 (x) |
Fast approximation of pygeodesy.acos1`(x)`, scalar. See Also: ShaderFastLibs.h.

### fasin1 (x) |
Fast approximation of pygeodesy.asin1`(x)`, scalar. See Also: facos1.

### fatan1 (x) |
Fast approximation of `atan(x)` for `0 <= x < 1`, unchecked. See Also: ShaderFastLibs.h and Efficient approximations for the arctangent function, IEEE Signal Processing Magazine, 111, May 2006.

### fatan2 (y, x) |
Fast approximation of `atan2(y, x)`, scalar. See Also: fastApproximateAtan(x, y) and fatan1.

### favg (a, b, f=0.5, nonfinites=True) |
Return the precise average of two values. Arguments: `a` - One (`scalar`, an Fsum or Fsum2Tuple). `b` - Other (`scalar`, an Fsum or Fsum2Tuple). `f` - Optional fraction (`float`). `nonfinites` - Optional setting, see function fma. Returns: a + f * (b - a) (`float`).

### fdot (xs, *ys, **start_f2product_nonfinites) |
Return the precision dot product start + sum(xs[i] * ys[i] for i in range(len(xs))). Arguments: `xs` - Iterable of values (each `scalar`, an Fsum or Fsum2Tuple). `ys` - Other values (each `scalar`, an Fsum or Fsum2Tuple), all positional. `start_f2product_nonfinites` - Optional bias `start=0` (`scalar`, an Fsum or Fsum2Tuple) and settings `f2product=None` (`bool`) and `nonfinites=True` (`bool`), see class Fsum. Returns: Dot product (`float`). Raises: `LenError` - Unequal `len(xs)` and `len(ys)`. See Also: Class Fdot, Algorithm 5.10 DotK and function `math.sumprod` in Python 3.12 and later.

### fdot_ (*xys, **start_f2product_nonfinites) |
Return the (precision) dot product start + sum(xys[i] * xys[i+1] for i in range(0, len(xys), 2)). Arguments: `xys` - Pairwise values (each `scalar`, an Fsum or Fsum2Tuple), all positional. Returns: Dot product (`float`). See Also: Function fdot for further details.

### fdot3 (xs, ys, zs, **start_f2product_nonfinites) |
Return the (precision) dot product start + sum(xs[i] * ys[i] * zs[i] for i in range(len(xs))). Arguments: `xs` - X values iterable (each `scalar`, an Fsum or Fsum2Tuple). `ys` - Y values iterable (each `scalar`, an Fsum or Fsum2Tuple). `zs` - Z values iterable (each `scalar`, an Fsum or Fsum2Tuple). Returns: Dot product (`float`). Raises: `LenError` - Unequal `len(xs)`, `len(ys)` and/or `len(zs)`. See Also: Function fdot for further details.

### fhorner (x, *cs, **incx) |
Horner form evaluation of polynomial sum(cs[i] * x**i for i=0..n) as in- or decreasing exponent sum(... i=n..0), where `n = len(cs) - 1`. Returns: Horner sum (`float`). See Also: Class Fhorner for further details.

### fidw (xs, ds, beta=2) |
Interpolate using Inverse Distance Weighting (IDW). Arguments: `xs` - Known values (each `scalar`, an Fsum or Fsum2Tuple). `ds` - Non-negative distances (each `scalar`, an Fsum or Fsum2Tuple). `beta` - Inverse distance power (`int`, 0, 1, 2, or 3). Returns: Interpolated value `x` (`float`). Raises: `LenError` - Unequal or zero `len(ds)` and `len(xs)`. `TypeError` - An invalid `ds` or `xs`. `ValueError` - Invalid `beta`, negative `ds` or weighted `ds` below EPS. Note: Using `beta=0` returns the mean of `xs`.

### fma (x, y, z, **nonfinites) |
Fused-multiply-add, using `math.fma(x, y, z)` in Python 3.13+ or an equivalent implementation. Arguments: `x` - Multiplicand (`scalar`, an Fsum or Fsum2Tuple). `y` - Multiplier (`scalar`, an Fsum or Fsum2Tuple). `z` - Addend (`scalar`, an Fsum or Fsum2Tuple). `nonfinites` - Use `nonfinites=True` or `=False`, to override default nonfiniterrors (`bool`), see method Fsum.fma. Returns: `(x * y) + z` (`float` or Fsum).

### fmean (xs) |
Compute the accurate mean sum(xs) / len(xs). Arguments: `xs` - Values (each `scalar`, or Fsum or Fsum2Tuple). Returns: Mean value (`float`). Raises: `LenError` - No `xs` values. `OverflowError` - Partial `2sum` overflow.

### fmean_ (*xs, **nonfinites) |
Compute the accurate mean sum(xs) / len(xs). See Also: Function fmean for further details.

### f2mul_ (x, *ys, **nonfinites) |
Cascaded, accurate multiplication `x * y * y ...` for all `ys`. Arguments: `x` - Multiplicand (`scalar`, an Fsum or Fsum2Tuple). `ys` - Multipliers (each `scalar`, an Fsum or Fsum2Tuple), all positional. `nonfinites` - Use `nonfinites=True` or `=False`, to override default nonfiniterrors (`bool`), see method Fsum.f2mul_. Returns: The cascaded TwoProduct (`float`, `int` or Fsum). See Also: Equations 2.3

### fpolynomial (x, *cs, **over_f2product_nonfinites) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) [/ over]. Arguments: `over_f2product_nonfinites` - Optional final divisor `over=None` (non-zero `scalar`) and other settings, see class Fpolynomial. Returns: Polynomial value (`float` or Fpolynomial).

### fpowers (x, n, alts=0) |
Return a series of powers [x**i for i=1..n], note 1..! Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). `n` - Highest exponent (`int`). `alts` - Only alternating powers, starting with this exponent (`int`). Returns: Tuple of powers of `x` (each `type(x)`). Raises: `TypeError` - Invalid `x` or `n` not `int`. `ValueError` - Non-finite `x` or invalid `n`.

### fprod (xs, start=1) |
Iterable product, like `math.prod` or `numpy.prod`. Arguments: `xs` - Iterable of values to be multiplied (each `scalar`, an Fsum or Fsum2Tuple). `start` - Initial value, also the value returned for an empty `xs` (`scalar`). Returns: The product (`float` or Fsum). See Also: NumPy.prod.

### frandoms (n, seeded=None) |
Generate `n` (long) lists of random `floats`. Arguments: `n` - Number of lists to generate (`int`, non-negative). `seeded` - If `scalar`, use `random.seed(seeded)` or if `True`, seed using today's `year-day`. See Also: Hettinger.

### frange (start, number, step=1) |
Generate a range of `float`s. Arguments: `start` - First value (`float`). `number` - The number of `float`s to generate (`int`). `step` - Increment value (`float`). Returns: A generator (`float`s). See Also: NumPy.prod.

### freduce (function, sequence, initial=...) |
Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty. Returns: value

### fremainder (x, y) |
Remainder in range `[-y / 2, y / 2]`. Arguments: `x` - Numerator (`scalar`). `y` - Modulus, denominator (`scalar`). Returns: Remainder (`scalar`, preserving signed 0.0) or `NAN` for any non-finite `x`. Raises: `ValueError` - Infinite or near-zero `y`. See Also: Karney's Math.remainder and Python 3.7+ math.remainder.

### hypot_ (*xs) |
Compute the norm sqrt(sum(x**2 for x in xs)). Similar to Python 3.8+ n-dimension math.hypot, but exceptions, `nan` and `infinite` values are handled differently. Arguments: `xs` - X arguments (`scalar`s), all positional. Returns: Norm (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - Invalid or no `xs` values. Note: The Python 3.8+ Euclidian distance math.dist between 2 n-dimensional points p1 and p2 can be computed as hypot_(*((c1 - c2) for c1, c2 in zip(p1, p2))), provided p1 and p2 have the same, non-zero length n.

### hypot1 (x) |
Compute the norm sqrt(1 + x**2). Arguments: `x` - Argument (`scalar` or Fsum or Fsum2Tuple). Returns: Norm (`float` or Fhypot).

### hypot2 (x, y) |
Compute the squared norm x**2 + y**2. Arguments: `x` - X (`scalar`, an Fsum or Fsum2Tuple). `y` - Y (`scalar`, an Fsum or Fsum2Tuple). Returns: `x**2 + y**2` (`float`).

### hypot2_ (*xs) |
Compute the squared norm `fsum(x**2 for x in xs)`. Arguments: `xs` - Components (each `scalar`, an Fsum or Fsum2Tuple), all positional. Returns: Squared norm (`float`). See Also: Class Fpowers for further details.

### norm2 (x, y) |
Normalize a 2-dimensional vector. Arguments: `x` - X component (`scalar`). `y` - Y component (`scalar`). Returns: 2-Tuple `(x, y)`, normalized. Raises: `ValueError` - Invalid `x` or `y` or zero norm.

### norm_ (*xs) |
Normalize the components of an n-dimensional vector. Arguments: `xs` - Components (each `scalar`, an Fsum or Fsum2Tuple), all positional. Returns: Yield each component, normalized. Raises: `ValueError` - Invalid or insufficent `xs` or zero norm.

### sqrt0 (x, Error=None) |
Return the square root `sqrt(x)` iff `x >` EPS02, preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). `Error` - Error to raise for negative `x`. Returns: Square root (`float` or Fsum) or `0.0`. Raises: `TypeeError` - Invalid `x`. Note: Any `x <` EPS02 including `x < 0` returns `0.0`.

### sqrt3 (x) |
Return the square root, cubed sqrt(x)**3 or sqrt(x**3), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Square root cubed (`float` or Fsum). Raises: `TypeeError` - Invalid `x`. `ValueError` - Negative `x`. See Also: Functions cbrt and cbrt2.

### sqrt_a (h, b) |
Compute the `a` side of a right-angled triangle from `sqrt(h**2 - b**2)`. Arguments: `h` - Hypotenuse or outer annulus radius (`scalar`). `b` - Triangle side or inner annulus radius (`scalar`). Returns: `copysign(a, h)` or `unsigned 0.0` (`float`). Raises: `TypeError` - Non-scalar `h` or `b`. `ValueError` - If `abs(h) < abs(b)`. See Also: Inner tangent chord d of an annulus and function annulus_area.

### zcrt (x) |
Return the 6-th, zenzi-cubic root, x**(1 / 6), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Zenzi-cubic root (`float` or Fsum). Raises: `TypeeError` - Invalid `x`. `ValueError` - Negative `x`. See Also: Functions bqrt and zqrt.

### zqrt (x) |
Return the 8-th, zenzi-quartic or squared-quartic root, x**(1 / 8), preserving `type(x)`. Arguments: `x` - Value (`scalar`, an Fsum or Fsum2Tuple). Returns: Zenzi-quartic root (`float` or Fsum). Raises: `TypeeError` - Invalid `x`. `ValueError` - Negative `x`. See Also: Functions bqrt and zcrt.