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

# Module fmath

Utilities using precision floating point summation.

Version: 24.04.24

Classes
| 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)`. |
fasin1(x) Fast approximation of pygeodesy.asin1`(x)`. |
fatan(x) Fast approximation of `atan(x)`. |
fatan1(x) Fast approximation of `atan(x)` for `0 <= x <= 1`, unchecked. |
fatan2(y, x) Fast approximation of `atan2(y, x)`. |
favg(v1, v2, f=0.5) Return the average of two values. |
fdot(a, *b) Return the precision dot product sum(a[i] * b[i] for i=0..len(a)). |
fdot3(a, b, c, start=0) Return the precision dot product start + sum(a[i] * b[i] * c[i] for i=0..len(a)-1). |
fhorner(x, *cs) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)-1) using the Horner form. |
fidw(xs, ds, beta=2) Interpolate using Inverse Distance Weighting (IDW). |
fmean(xs) Compute the accurate mean sum(xs) / len(xs). |
fmean_(*xs) Compute the accurate mean sum(xs) / len(xs). |
fpolynomial(x, *cs, **over) 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]. |
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 all n-dimensional vector components. |
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 `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` or Fsum instance). Returns: Quartic root (`float` or Fsum). Raises: `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` or Fsum instance). 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` or Fsum instance). 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` or Fsum instance). `y` - Y component (`scalar` or Fsum instance). 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, positional (`scalar`s or Fsum instances). Returns: Appoximate norm (`float` or Fsum). See Also: Function euclid.

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

### fasin1 (x) |
Fast approximation of pygeodesy.asin1`(x)`. 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)`. See Also: fastApproximateAtan(x, y) and fatan1.

### favg (v1, v2, f=0.5) |
Return the average of two values. Arguments: `v1` - One value (`scalar` or Fsum instance). `v2` - Other value (`scalar` or Fsum instance). `f` - Optional fraction (`float`). Returns: v1 + f * (v2 - v1) (`float`).

### fdot (a, *b) |
Return the precision dot product sum(a[i] * b[i] for i=0..len(a)). Arguments: `a` - Iterable, list, tuple, etc. (`scalar`s). `b` - All positional arguments (`scalar`s). Returns: Dot product (`float`). Raises: `LenError` - Unequal `len(a)` and `len(b)`. See Also: Class Fdot and Algorithm 5.10 DotK.

### fdot3 (a, b, c, start=0) |
Return the precision dot product start + sum(a[i] * b[i] * c[i] for i=0..len(a)-1). Arguments: `a` - Iterable, list, tuple, etc. (`scalar`s). `b` - Iterable, list, tuple, etc. (`scalar`s). `c` - Iterable, list, tuple, etc. (`scalar`s). `start` - Optional bias (`scalar`). Returns: Dot product (`float`). Raises: `LenError` - Unequal `len(a)`, `len(b)` and/or `len(c)`. `OverflowError` - Partial `2sum` overflow.

### fhorner (x, *cs) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)-1) using the Horner form. Arguments: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`scalar`s). Returns: Horner value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `x`. `ValueError` - No `cs` coefficients or `x` is not finite. See Also: Function fpolynomial and class Fhorner.

### fidw (xs, ds, beta=2) |
Interpolate using Inverse Distance Weighting (IDW). Arguments: `xs` - Known values (`scalar`s). `ds` - Non-negative distances (`scalar`s). `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)`. `ValueError` - Invalid `beta`, negative `ds` value, weighted `ds` below EPS. Note: Using `beta=0` returns the mean of `xs`.

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

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

### fpolynomial (x, *cs, **over) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) [/ over]. Arguments: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`scalar`s), all positional. `over` - Optional final, non-zero divisor (`scalar`). Returns: Polynomial value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `x`. `ValueError` - No `cs` coefficients or `x` is not finite. See Also: Function fhorner and class Fpolynomial.

### fpowers (x, n, alts=0) |
Return a series of powers [x**i for i=1..n]. Arguments: `x` - Value (`scalar` or Fsum). `n` - Highest exponent (`int`). `alts` - Only alternating powers, starting with this exponent (`int`). Returns: Tuple of powers of `x` (`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` - Terms to be multiplied, an iterable, list, tuple, etc. (`scalar`s). `start` - Initial term, also the value returned for an empty `xs` (`scalar`). Returns: The product (`float`). 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 instance). Returns: Norm (`float`).

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

### hypot2_ (*xs) |
Compute the squared norm `fsum(x**2 for x in xs)`. Arguments: `xs` - X arguments (`scalar`s or Fsum instances), all positional. Returns: Squared norm (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - Invalid or no `xs` value. See Also: Function hypot_.

### 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 all n-dimensional vector components. Arguments: `xs` - Components (`scalar`s), 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` or Fsum instance). `Error` - Error to raise for negative `x`. Returns: Square root (`float` or Fsum) or `0.0`. 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` or Fsum instance). Returns: Square root cubed (`float` or Fsum). Raises: `ValueError` - Negative `x`. See Also: Functions cbrt and cbrt2.

### sqrt_a (h, b) |
Compute `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` or Fsum instance). Returns: Zenzi-cubic root (`float` or Fsum). Raises: `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` or Fsum instance). Returns: Zenzi-quartic root (`float` or Fsum). Raises: `ValueError` - Negative `x`. See Also: Functions bqrt and zcrt.