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

# Module fsums

Class Fsum for precision floating point summation similar to Python's `math.fsum` enhanced with running summation and as an option, accurate TwoProduct multiplication.

Accurate multiplication is based on the `math.fma` function for Python 3.13 and newer or one of two equivalent `fma` implementations for Python 3.12 and older. To enable accurate multiplication, set env variable `PYGEODESY_FSUM_F2PRODUCT` to `"std"` or any non-empty string or invoke function `pygeodesy.f2product(True)` or set. With `"std"` the `fma` implemention follows the `math.fma` function, otherwise the `PyGeodesy 24.09.09` release.

Generally, an Fsum instance is considered a `float` plus a small or zero `residue` aka `residual` value, see property Fsum.residual.

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 with a `residual` ratio exceeding the threshold. See methods Fsum.RESIDUAL, Fsum.pow, Fsum.__ipow__ and Fsum.__itruediv__.

There are several `integer` Fsum cases, for example the result from functions `ceil`, `floor`, `Fsum.__floordiv__` and methods Fsum.fint, Fsum.fint2 and Fsum.is_integer. 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 is between `-1.0` and `+1.0` and will be `INT0` if that is considered to be exact.

Set env variable `PYGEODESY_FSUM_NONFINITES` to `"std"` or use function `pygeodesy.nonfiniterrors(False)` to allow non-finite `float`s like `inf`, `INF`, `NINF`, `nan` and `NAN` and to ignore `OverflowError` respectively `ValueError` exceptions. However, in that case non-finite results may differ from Python's `math.fsum` results.

Version: 24.10.22

Classes
| Fsum Precision floating point summation, running summation and accurate multiplication.
| 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
f2product(*two) Turn accurate TwoProduct multiplication on or off. |
nonfiniterrors(*raiser) Throw `OverflowError` and `ValueError` exceptions for or handle non-finite `float`s as `inf`, `INF`, `NINF`, `nan` and `NAN` in summations and multiplications. |
fsum(xs, nonfinites=None, **floats) Precision floating point summation from Python's `math.fsum`. |
fsum_(*xs, **nonfinites) Precision floating point summation of all positional items. |
fsumf_(*xs) Precision floating point summation of all positional items with non-finites `OK`. |
fsum1(xs, **nonfinites) Precision floating point summation, 1-primed. |
fsum1_(*xs, **nonfinites) Precision floating point summation of all positional items, 1-primed. |
fsum1f_(*xs) Precision floating point summation of all positional items, 1-primed and with non-finites `OK`. |

Variables
| __all__ = `_ALL_LAZY.fsums`

Function Details

### f2product (*two) |
Turn accurate TwoProduct multiplication on or off. Arguments: `two` - If `True`, turn TwoProduct on, if `False` off or if `None` or omitted, keep the current setting. Returns: The previous setting (`bool`). See Also: TwoProduct multiplication is based on the TwoProductFMA Algorithm 3.5 using function `math.fma` from Python 3.13 and later or an equivalent, slower implementation when not available.

### nonfiniterrors (*raiser) |
Throw `OverflowError` and `ValueError` exceptions for or handle non-finite `float`s as `inf`, `INF`, `NINF`, `nan` and `NAN` in summations and multiplications. Arguments: `raiser` - If `True`, throw exceptions, if `False` handle non-finites or if `None` or omitted, leave the setting unchanged. Returns: Previous setting (`bool`). Note: `inf`, `INF` and `NINF` throw an `OverflowError`, `nan` and `NAN` a `ValueError`.

### fsum (xs, nonfinites=None, **floats) |
Precision floating point summation from Python's `math.fsum`. Arguments: `xs` - Iterable of items to add (each `scalar`, an Fsum or Fsum2Tuple). `nonfinites` - Use `nonfinites=True` if non-finites are `OK`, if `False` non-finites raise an Overflow-/ValueError or if `None`, nonfiniterrors applies (`bool` or `None`). `floats` - DEPRECATED keyword argument `floats=False` (`bool`), use keyword argument `nonfinites=False` instead. Returns: Precision `fsum` (`float`). Raises: `OverflowError` - Infinite `xs` item or intermediate `math.fsum` overflow. `TypeError` - Invalid `xs` item. `ValueError` - Invalid or `NAN` `xs` item. See Also: Function nonfiniterrors, class Fsum and methods Fsum.nonfinites, Fsum.fsum, Fsum.fadd and Fsum.fadd_.

### fsum_ (*xs, **nonfinites) |
Precision floating point summation of all positional items. Arguments: `xs` - Items to add (each `scalar`, an Fsum or Fsum2Tuple), all positional. `nonfinites` - Use `nonfinites=True` if non-finites are `OK` (`bool`). See Also: Function fsum for further details.

### fsumf_ (*xs) |
Precision floating point summation of all positional items with non-finites `OK`. Arguments: `xs` - Items to add (each `scalar`, an Fsum or Fsum2Tuple), all positional. See Also: Function fsum_ for further details.

### fsum1 (xs, **nonfinites) |
Precision floating point summation, 1-primed. Arguments: `xs` - Iterable of items to add (each `scalar`, an Fsum or Fsum2Tuple). `nonfinites` - Use `nonfinites=True` if non-finites are `OK` (`bool`). See Also: Function fsum for further details.

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

### fsum1f_ (*xs) |
Precision floating point summation of all positional items, 1-primed and with non-finites `OK`. See Also: Function fsum_ for further details.