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_RESIDUAL` to a `float` string greater than `"0.0"` as the threshold to throw a ResidualError for a division, power or root operation of an Fsum instance with a `residual` ratio exceeding the threshold. See methods Fsum.RESIDUAL, Fsum.pow, Fsum.__ipow__ and Fsum.__itruediv__.

Version: 24.05.02

Classes
| Fsum Precision floating point summation and running summation.
| DivMod2Tuple 2-Tuple `(div, mod)` with the quotient `div` and remainder `mod` results of a `divmod` operation.
| Fsum2Tuple 2-Tuple `(fsum, residual)` with the precision running `fsum` and the `residual`, the sum of the remaining partials.
| ResidualError Error raised for a division, power or root operation of an Fsum instance with a `residual` ratio exceeding the RESIDUAL threshold.

Functions
fsum(xs, floats=False) Precision floating point summation based on/like Python's `math.fsum`. |
fsum_(*xs, **floats) Precision floating point summation of all positional arguments. |
fsumf_(*xs) Precision floating point summation iff all `xs` items are known to be scalar. |
fsum1(xs, floats=False) Precision floating point summation, 1-primed. |
fsum1_(*xs, **floats) Precision floating point summation, 1-primed of all positional arguments. |
fsum1f_(*xs) Precision floating point summation iff all `xs` are known to be scalar. |

Variables
| __all__ = `_ALL_LAZY.fsums`

Function Details

### fsum (xs, floats=False) |
Precision floating point summation based on/like Python's `math.fsum`. Arguments: `xs` - Iterable of items to add (each `scalar` or an Fsum or Fsum2Tuple instance). `floats` - Use `floats=True` iff all `xs` items are known to be scalar (`bool`). Returns: Precision `fsum` (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `xs` item. `ValueError` - Invalid or non-finite `xs` item. Note: Exception 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` - Items to add (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. `floats` - Use `floats=True` iff all `xs` items are known to be scalar (`bool`). See Also: Function fsum for further details.

### fsumf_ (*xs) |
Precision floating point summation iff all `xs` items are known to be scalar. See Also: Function fsum_ for further details.

### fsum1 (xs, floats=False) |
Precision floating point summation, 1-primed. Arguments: `xs` - Iterable of items to add (each `scalar` or an Fsum or Fsum2Tuple instance). `floats` - Use `floats=True` iff all `xs` items are known to be scalar (`bool`). See Also: Function fsum for further details.

### fsum1_ (*xs, **floats) |
Precision floating point summation, 1-primed of all positional arguments. Arguments: `xs` - Items to add (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. `floats` - Use `floats=True` iff all `xs` items are known to be scalar (`bool`). See Also: Function fsum_ for further details.

### fsum1f_ (*xs) |
Precision floating point summation iff all `xs` are known to be scalar. See Also: Function fsum_ for further details.