Package pygeodesy :: Module fmath

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 floats.

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 (scalars 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. (scalars).
b - All positional arguments (scalars).

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. (scalars).
b - Iterable, list, tuple, etc. (scalars).
c - Iterable, list, tuple, etc. (scalars).
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 (scalars).

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 (scalars).
ds - Non-negative distances (scalars).
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 (scalars), 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. (scalars).
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 floats.

Arguments:

start - First value (float).
number - The number of floats to generate (int).
step - Increment value (float).

Returns:

A generator (floats).

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 (scalars), 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 (scalars 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 (scalars), 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.