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

# Module fmath

Precision floating point functions, utilities and constants.

Version: 19.09.17

Classes
| Fsum Precision summation similar to standard Python function `math.fsum`.
| Fdot Precision dot product.
| Fhorner Precision polynomial evaluation using the Horner form.
| Fpolynomial Precision polynomial evaluation.

Functions
hypot(x, y) Return the Euclidean distance, sqrt(x*x + y*y). |
bool |
isinf(x) Check if float x is infinite (positive or negative). |
bool |
isnan(x) Check if float x is not a number (NaN). |
acos1(x) Return math.acos(max(-1, min(1, x))). |
cbrt(x) Compute the cubic root x**(1/3). |
cbrt2(x) Compute the cubic root squared x**(2/3). |
favg(v1, v2, f=0.5) Return the weighted 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)). |
fhorner(x, *cs) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) using the Horner form. |
fidw(xs, ds, beta=2) Interpolate using using Inverse Distance Weighting (IDW). |
fmean(xs) Compute the accurate mean sum(xs[i] for i=0..len(xs)) / len(xs). |
fpolynomial(x, *cs) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)). |
fpowers(x, n, alts=0) Return a series of powers [x**i for i=1..n]. |
fprod(iterable, start=1.0) Iterable product, like `math.prod` or `numpy.prod`. |
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. |
fStr(floats, prec=6, sep=`'``,` `'`, fmt=`'``%.*f``'`, ints=False) Convert floats to string, optionally with trailing zero decimals stripped. |
fStrzs(fstr) Strip trailing zero decimals from a float string. |
fsum_(*xs) Precision summation of the positional argument vulues. |
fsum(iterable) Return an accurate floating point sum of values in the iterable. |
hypot1(x) Compute the norm sqrt(1 + x**2). |
hypot_(*xs) Compute the norm sqrt(sum(xs[i]**2)) for i=0..len(xs). |
isfinite(obj) Check for `Inf` and `NaN` values. |
isint(obj, both=False) Check for integer type or integer value. |
isneg0(obj) Check for NEG0, negative 0.0. |
isscalar(obj) Check for scalar types. |
len2(seq) Make built-in function `len` work for generators, iterators, etc. |
map1(func, *xs) Apply each argument to a single-argument function and return a tuple of results. |
map2(func, *xs) Apply arguments to a function and return a tuple of results. |
scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) Validate a scalar. |
sqrt3(x) Compute the square root cubed sqrt(x)**3 or sqrt(x**3). |

Variables
| __all__ = `_ALL_LAZY.fmath`
| EPS = `2.22044604925e-16` Epsilon (`float`) 2**-52?
| MANTIS = `53` Mantissa bits ≈53 (`int`)
| MAX = `1.79769313486e+308` Float max (`float`) ≈10**308, 2**1024?
| MIN = `2.22507385851e-308` System's float min (`float`)
| EPS_2 = `1.11022302463e-16` EPS / 2 ≈1.110223024625e-16 (`float`)
| EPS1 = `1.0` 1 - EPS ≈0.9999999999999998 (`float`)
| EPS1_2 = `1.0` 1 - EPS_2 ≈0.9999999999999999 (`float`)
| INF = `inf` Infinity (`float`), see `isinf`, `isfinite`
| NAN = `nan` Not-A-Number (`float`), see `isnan`
| NEG0 = `-0.0` Negative 0.0 (`float`), see `isneg0`

Function Details

### cbrt(x) |
Compute the cubic root x**(1/3). Parameters: `x` - Value (`scalar`). Returns: Cubic root (`float`). See Also: Functions cbrt2 and sqrt3.

### cbrt2(x) |
Compute the cubic root squared x**(2/3). Parameters: `x` - Value (`scalar`). Returns: Cubic root squared (`float`). See Also: Functions cbrt and sqrt3.

### favg(v1, v2, f=0.5) |
Return the weighted average of two values. Parameters: `v1` - One value (`scalar`). `v2` - Other value (`scalar`). `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)). Parameters: `a` - List, sequence, tuple, etc. (`scalar`s). `b` - All positional arguments (`scalar`s). Returns: Dot product (`float`). Raises: `ValueError` - Unequal `len(a)` and `len(b)`. See Also: Class Fdot.

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

### fhorner(x, *cs) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) using the Horner form. Parameters: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`scalar`[]). 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 using Inverse Distance Weighting (IDW). Parameters: `xs` - Known values (`scalar`[]). `ds` - Non-negative distances (`scalar`[]). `beta` - Inverse distance power (`int`, 0, 1, 2, or 3). Returns: Interpolated value `x` (`float`). Raises: `ValueError` - Invalid `beta`, negative `ds` value, weighted `ds` below EPS or unequal `len(ds)` and `len(xs)`. Note: Using `beta=0` returns the mean of `xs`.

### fmean(xs) |
Compute the accurate mean sum(xs[i] for i=0..len(xs)) / len(xs). Parameters: `xs` - Values (`scalar`s). Returns: Mean value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - No `xs` values.

### fpolynomial(x, *cs) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)). Parameters: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`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]. Parameters: `x` - Value (`scalar`). `n` - Highest exponent (`int`). `alts` - Only alternating powers, starting with this exponent (`int`). Returns: Powers of `x` (`float`[]). Raises: `TypeError` - Non-scalar `x` or `n` not `int`. `ValueError` - Non-finite `x` or non-positive `n`.

### fprod(iterable, start=1.0) |
Iterable product, like `math.prod` or `numpy.prod`. Parameters: `iterable` - Values to be multiplied (`scalar`[]). `start` - Initial product, also the value returned for an empty iterable (`scalar`). Returns: The product (`float`). See Also: NumPy.prod.

### frange(start, number, step=1) |
Generate a range of `float`s. Parameters: `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

### fStr(floats, prec=6, sep=`'``,` `'`, fmt=`'``%.*f``'`, ints=False) |
Convert floats to string, optionally with trailing zero decimals stripped. Parameters: `floats` - List, sequence, tuple, etc. (`scalar`s). `prec` - Optional precision, number of decimal digits (0..9). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec` values. `sep` - Optional, separator to join (string). `fmt` - Optional, float format (string). `ints` - Optionally, remove decimal dot (`bool`). Returns: The floats as 'f, f, ... f' (string).

### fStrzs(fstr) |
Strip trailing zero decimals from a float string. Parameters: `fstr` - Float (string). Returns: Float (string).

### fsum_(*xs) |
Precision summation of the positional argument vulues. Parameters: `xs` - Values to be added (`scalar`[]). Returns: Accurate fsum (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `xs` value. `ValueError` - Invalid or non-finite `xs` value.

### fsum(iterable) |
Return an accurate floating point sum of values in the iterable. Assumes IEEE-754 floating point arithmetic.

### hypot1(x) |
Compute the norm sqrt(1 + x**2). Parameters: `x` - Argument (`scalar`). Returns: Norm (`float`).

### hypot_(*xs) |
Compute the norm sqrt(sum(xs[i]**2)) for i=0..len(xs). Parameters: `xs` - X arguments, positional (`scalar`[]). Returns: Norm (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - Invalid or no `xs` value. See Also: Similar to Python 3.8+ math.hypot, but handling of exceptions, `nan` and `infinite` values is different. Note: The Python 3.8+ math.dist Euclidian distance 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.

### isfinite(obj) |
Check for `Inf` and `NaN` values. Parameters: `obj` - Value (`scalar`). Returns: `False` if `obj` is `INF` or `NAN`, `True` otherwise. Raises: `TypeError` - Non-scalar `obj`.

### isint(obj, both=False) |
Check for integer type or integer value. Parameters: `obj` - The object (any `type`). `both` - Optionally, check both type and value (`bool`). Returns: `True` if `obj` is `int`, `False` otherwise.

### isneg0(obj) |
Check for NEG0, negative 0.0. Parameters: `obj` - Value (`scalar`). Returns: `True` if `obj` is `NEG0` or -0.0, `False` otherwise.

### isscalar(obj) |
Check for scalar types. Parameters: `obj` - The object (any `type`). Returns: `True` if `obj` is `scalar`, `False` otherwise.

### len2(seq) |
Make built-in function `len` work for generators, iterators, etc. since those can only be started exactly once. Parameters: `seq` - Generator, iterator, list, range, tuple, etc. Returns: 2-Tuple (number, ...) of items (`int`, `list` or `range` or `tuple`).

### map1(func, *xs) |
Apply each argument to a single-argument function and return a tuple of results. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`any positional`). Returns: Function results (`tuple`).

### map2(func, *xs) |
Apply arguments to a function and return a tuple of results. Unlike Python 2's built-in `map`, Python 3+ `map` returns a `map` object, an iterator-like object which generates the results only once. Converting the `map` object to a tuple maintains Python 2 behavior. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`list, tuple, ...`). Returns: Function results (`tuple`).

### scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) |
Validate a scalar. Parameters: `value` - The value (`scalar`). `low` - Optional lower bound (`scalar`). `high` - Optional upper bound (`scalar`). `name` - Optional name of value (`str`). `Error` - Exception to raise (`ValueError`). Returns: New value (`type` of `low`). Raises: `TypeError` - Non-scalar `value`. `ValueError` - Out-of-bounds `value`.

### sqrt3(x) |
Compute the square root cubed sqrt(x)**3 or sqrt(x**3). Parameters: `x` - Value (`scalar`). Returns: Cubed square root (`float`). Raises: `ValueError` - Negative `x`. See Also: Functions cbrt and cbrt2.