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

# Module fsums

Class Fsum for precision floating point summation and running summation, based on respectively similar to Python's `math.fsum`.

Generally, an Fsum instance is considered a `float` plus a small or zero `residual` value, see property Fsum.residual. However, there are several `integer` Fsum cases, for example the result of `ceil`, `floor`, `Fsum.__floordiv__` and methods Fsum.fint and Fsum.fint2.

Also, Fsum methods Fsum.pow, Fsum.__ipow__, Fsum.__pow__ and Fsum.__rpow__ return a (very long) `int` if invoked with optional argument `mod` set to `None`. The `residual` of an `integer` Fsum may be between `-1.0` and `+1.0`, including `INT0` if considered to be exact.

Set env variable `PYGEODESY_FSUM_PARTIALS` to an empty string (or anything other than `"fsum"`) for backward compatible summation of Fsum partials.

Set env variable `PYGEODESY_FSUM_RESIDUAL` to a `float` string for the threshold to throw a ResidualError in division or exponention of an Fsum instance with a relative `residual` exceeding the threshold, see methods Fsum.RESIDUAL, Fsum.pow, Fsum.__ipow__ and Fsum.__itruediv__.

Version: 22.09.24

Classes
| Fsum Precision floating point running summation similar to standard Python's `math.fsum`.
| Fsum2Tuple 2-Tuple `(fsum, residual)` with the precision running `fsum` and the `residual`, the sum of the remaining partials.
| ResidualError Error raised for an operation involving a pygeodesy.sums.Fsum instance with a non-zero `residual`, integer or otherwise.

Functions
fsum(xs, floats=False) Precision floating point summation based on or like Python's `math.fsum`. |
fsum_(*xs, **floats) Precision floating point summation of all positional arguments. |
fsum1(xs, floats=False) Precision floating point summation of a few values, 1-primed. |
fsum1_(*xs, **floats) Precision floating point summation of a few arguments, 1-primed. |

Variables
| __all__ = `_ALL_LAZY.fsums`

Function Details

### fsum (xs, floats=False) |
Precision floating point summation based on or like Python's `math.fsum`. Arguments: `xs` - Iterable, list, tuple, etc. of values (`scalar` or Fsum instances). `floats` - Optionally, set `floats=True` iff all `xs` are known to be `float`. Returns: Precision `fsum` (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `xs` value. `ValueError` - Invalid or non-finite `xs` value. Note: Exceptions and non-finite handling may differ if not based on Python's `math.fsum`. See Also: Class Fsum and methods Fsum.fsum and Fsum.fadd.

### fsum_ (*xs, **floats) |
Precision floating point summation of all positional arguments. Arguments: `xs` - Values to be added (`scalar` or Fsum instances), all positional. `floats` - Optionally, set `floats=True` iff all `xs` are known to be `float`. Returns: Precision `fsum` (`float`). See Also: Function `fsum`.

### fsum1 (xs, floats=False) |
Precision floating point summation of a few values, 1-primed. Arguments: `xs` - Iterable, list, tuple, etc. of values (`scalar` or Fsum instances). `floats` - Optionally, set `floats=True` iff all `xs` are known to be `float`. Returns: Precision `fsum` (`float`). See Also: Function `fsum`.

### fsum1_ (*xs, **floats) |
Precision floating point summation of a few arguments, 1-primed. Arguments: `xs` - Values to be added (`scalar` or Fsum instances), all positional. `floats` - Optionally, set `floats=True` iff all `xs` are known to be `float`. Returns: Precision `fsum` (`float`). See Also: Function `fsum`