Module fsums
Class Fsum
for precision floating point summation similar to Python's
math.fsum, but enhanced with precision running
summation plus optionally, accurate TwoProduct multiplication.
Accurate multiplication is based on the math.fma function
from Python 3.13 and newer or an equivalent fma
implementation 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
floats 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.
|
|
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.
|
|
|
f2product(two=None)
Turn accurate TwoProduct multiplication on or off. |
|
|
|
|
nonfiniterrors(raiser=None)
Throw OverflowError and ValueError
exceptions for or handle non-finite floats 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. |
|
|
|
|
__all__ = _ALL_LAZY.fsums
|
|
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=None)
|
|
Throw OverflowError and ValueError
exceptions for or handle non-finite floats 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.
|
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.
|
|
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.
|
|
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.
|
|
Precision floating point summation of all positional items, 1-primed
and with non-finites OK.
See Also:
Function fsum_ for further details.
|