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

# Class Fsum

      object --+
               |
    named._Named --+
                   |
                  Fsum

Known Subclasses:
  - fmath.Froot
  - , fmath.Fdot
  - , fmath.Fhorner
  - , fmath.Fhypot
  - , fmath.Fpolynomial
  - , fmath.Fpowers

Precision floating point summation, running summation and accurate multiplication.

Unlike Python's `math.fsum`, this class accumulates values and provides intermediate, running, precision floating point summations. Accumulation may continue after any intermediate, running summuation.

Notes:

- Values may be Fsum, Fsum2Tuple, `int`, `float` or `scalar` instances, i.e. any `type` having method `__float__`.
- Handling of non-finites as `inf`, `INF`, `NINF`, `nan` and `NAN` is determined by function nonfiniterrors for the default and by method nonfinites for individual `Fsum` instances, overruling the default. For backward compatibility, non-finites raise exceptions by default.

See Also:
  Hettinger, Kahan, Klein, Python 2.6+ file Modules/mathmodule.c and the issue log Full precision summation., Method f2product for details about accurate TwoProduct multiplication., Module fsums for env variables `PYGEODESY_FSUM_F2PRODUCT`, `PYGEODESY_FSUM_NONFINITES` and `PYGEODESY_FSUM_RESIDUAL`.

Instance Methods
__init__(self, *xs, **name_f2product_nonfinites_RESIDUAL) New Fsum. |
__abs__(self) Return `abs(self)` as an Fsum. |
__add__(self, other) Return `self + other` as an Fsum. |
__bool__(self) Return `bool(self)`, `True` iff `residual` is zero. |
__ceil__(self) Return this instance' `math.ceil` as `int` or `float`. |
__cmp__(self, other) Compare this with an other instance or `scalar`, Python 2-. |
__divmod__(self, other, **raiser_RESIDUAL) Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. |
__eq__(self, other) Return `(self == other)` as `bool` where `other` is `scalar`, an other Fsum or Fsum2Tuple. |
__float__(self) Return this instance' current, precision running sum as `float`. |
__floor__(self) Return this instance' `math.floor` as `int` or `float`. |
__floordiv__(self, other) Return `self // other` as an Fsum. |
__format__(self, *other) Not implemented. |
__ge__(self, other) Return `(self >= other)`, see `__eq__`. |
__gt__(self, other) Return `(self > other)`, see `__eq__`. |
__hash__(self) Return `hash(self)` as `float`. |
__iadd__(self, other) Apply `self += other` to this instance. |
__ifloordiv__(self, other) Apply `self //= other` to this instance. |
__imatmul__(self, other) Not implemented. |
__imod__(self, other) Apply `self %= other` to this instance. |
__imul__(self, other) Apply `self *= other` to this instance. |
__int__(self) Return this instance as an `int`. |
__invert__(self) Not implemented. |
__ipow__(self, other, *mod, **raiser_RESIDUAL) Apply `self **= other` to this instance. |
__isub__(self, other) Apply `self -= other` to this instance. |
__iter__(self) Return an `iter`ator over a `partials` duplicate. |
__itruediv__(self, other, **raiser_RESIDUAL) Apply `self /= other` to this instance. |
__le__(self, other) Return `(self <= other)`, see `__eq__`. |
__len__(self) Return the number of values accumulated (`int`). |
__lt__(self, other) Return `(self < other)`, see `__eq__`. |
__matmul__(self, other) Not implemented. |
__mod__(self, other) Return `self % other` as an Fsum. |
__mul__(self, other) Return `self * other` as an Fsum. |
__ne__(self, other) Return `(self != other)`, see `__eq__`. |
__neg__(self) Return `copy(self)`, negated. |
__pos__(self) Return this instance as-is, like `float.__pos__()`. |
__pow__(self, other, *mod) Return `self**other` as an Fsum. |
__radd__(self, other) Return `other + self` as an Fsum. |
__rdivmod__(self, other) Return `divmod(other, self)` as 2-tuple `(quotient, remainder)`. |
__rfloordiv__(self, other) Return `other // self` as an Fsum. |
__rmatmul__(self, other) Not implemented. |
__rmod__(self, other) Return `other % self` as an Fsum. |
__rmul__(self, other) Return `other * self` as an Fsum. |
__round__(self, *ndigits) Return `round(self, *ndigits` as an Fsum. |
__rpow__(self, other, *mod) Return `other**self` as an Fsum. |
__rsub__(self, other) Return `other - self` as Fsum. |
__rtruediv__(self, other, **raiser_RESIDUAL) Return `other / self` as an Fsum. |
__str__(self) Return the default `str(self)`. |
__sub__(self, other) Return `self - other` as an Fsum. |
__truediv__(self, other, **raiser_RESIDUAL) Return `self / other` as an Fsum. |
__trunc__(self) Return this instance as an `int`. |
__div__(self, other, **raiser_RESIDUAL) Return `self / other` as an Fsum. |
__idiv__(self, other, **raiser_RESIDUAL) Apply `self /= other` to this instance. |
__long__(self) Return this instance as an `int`. |
__nonzero__(self) Return `bool(self)`, `True` iff `residual` is zero. |
__rdiv__(self, other, **raiser_RESIDUAL) Return `other / self` as an Fsum. |
as_integer_ratio(self) Return this instance as the ratio of 2 integers. |
cmp(self, other) Compare this with an other instance or `scalar`, Python 2-. |
copy(self, deep=False, **name) Copy this instance, `shallow` or `deep`. |
divmod(self, other, **raiser_RESIDUAL) Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. |
fadd(self, xs=`(``)`) Add an iterable's items to this instance. |
fadd_(self, *xs) Add all positional items to this instance. |
fcopy(self, deep=False, **name) Copy this instance, `shallow` or `deep`. |
fdiv(self, other, **raiser_RESIDUAL) Apply `self /= other` to this instance. |
fdivmod(self, other, **raiser_RESIDUAL) Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. |
fint(self, name='', **raiser_RESIDUAL) Return this instance' current running sum as `integer`. |
fint2(self, **name) Return this instance' current running sum as `int` and the integer residual. |
fma(self, other1, other2, **nonfinites) Fused-multiply-add `self *= other1; self += other2`. |
fmul(self, other) Apply `self *= other` to this instance. |
f2mul(self, *others, **raiser) DEPRECATED on 2024.09.13, use method f2mul_. |
f2mul_(self, *others, **nonfinites) Return `self * other * other ...` for all `others` using cascaded, accurate multiplication like with f2product set to `True`. |
fover(self, over, **raiser_RESIDUAL) Apply `self /= over` and summate. |
fpow(self, other, *mod, **raiser_RESIDUAL) Apply `self **= other` to this instance. |
f2product(self, *two) Get and set accurate TwoProduct multiplication for this Fsum, overriding the f2product default. |
fset_(self, *xs) Apply `self.partials = Fsum(*xs).partials`. |
fsub(self, xs=`(``)`) Subtract an iterable's items from this instance. |
fsub_(self, *xs) Subtract all positional items from this instance. |
fsum(self, xs=`(``)`) Add an iterable's items, summate and return the current precision running sum. |
fsum_(self, *xs) Add any positional items, summate and return the current precision running sum. |
Fsum_(self, *xs, **name) Like method Fsum.fsum_ but returning a named Fsum. |
Fsum2Tuple_(self, *xs, **name) Like method Fsum.fsum_ but returning a named Fsum2Tuple. |
fsum2(self, xs=`(``)`, **name) Add an iterable's items, summate and return the current precision running sum and the `residual`. |
fsum2_(self, *xs) Add any positional items, summate and return the current precision running sum and the differential. |
fsumf_(self, *xs) Like method Fsum.fsum_ iff all `xs`, each known to be `scalar`, an Fsum or Fsum2Tuple. |
Fsumf_(self, *xs) Like method Fsum.Fsum_ iff all `xs`, each known to be `scalar`, an Fsum or Fsum2Tuple. |
fsum2f_(self, *xs) Like method Fsum.fsum2_ iff all `xs`, each known to be `scalar`, an Fsum or Fsum2Tuple. |
int_float(self, **raiser_RESIDUAL) Return this instance' current running sum as `int` or `float`. |
is_exact(self) Is this instance' running `fsum` considered to be exact? (`bool`), `True` only if the `residual is` INT0. |
is_finite(self) Is this instance `finite`? (`bool`). |
is_integer(self) Is this instance' running sum `integer`? (`bool`). |
is_math_fma(self) Is accurate f2product multiplication based on Python's `math.fma`? |
is_math_fsum(self) Are the summation functions fsum, fsum_, fsumf_, fsum1, fsum1_ and fsum1f_ based on Python's `math.fsum`? |
is_scalar(self, **raiser_RESIDUAL) Is this instance' running sum `scalar` without residual or with a residual ratio not exceeding the RESIDUAL threshold? |
nonfinites(self, *OK) Handle non-finite `float`s as `inf`, `INF`, `NINF`, `nan` and `NAN` for this Fsum or throw `OverflowError` respectively `ValueError` exceptions, overriding the nonfiniterrors default. |
pow(self, x, *mod, **raiser_RESIDUAL) Return `self**x` as Fsum. |
rdiv(self, other, **raiser_RESIDUAL) Return `other / self` as an Fsum. |
RESIDUAL(self, *threshold) Get and set this instance' ratio for raising ResidualErrors, overriding the default from env variable `PYGEODESY_FSUM_RESIDUAL`. |
root(self, root, **raiser_RESIDUAL) Return `self**(1 / root)` as Fsum. |
signOf(self, res=True) Determine the sign of this instance. |
toRepr(self, **lenc_prec_sep_fmt) Return this `Fsum` instance as representation. |
toStr(self, lenc=True, **prec_sep_fmt) Return this `Fsum` instance as string. |
Inherited from `named._Named`: `__repr__`, `attrs`, `classof`, `dup`, `methodname`, `rename`, `renamed`, `toStr2` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| as_iscalar Get this instance as-is (Fsum with `non-zero residual`, `scalar` or non-finite).
| ceil Get this instance' `ceil` value (`int` in Python 3+, but `float` in Python 2-).
| float_int DEPRECATED, use method `Fsum.int_float`.
| floor Get this instance' `floor` (`int` in Python 3+, but `float` in Python 2-).
| imag Get the `imaginary` part of this instance (`0.0`, always).
| nonfinitesOK Are non-finites `OK` for this Fsum or by default? (`bool`).
| partials Get this instance' current, partial sums (`tuple` of `float`s).
| real Get the `real` part of this instance (`float`).
| residual Get this instance' residual or residue (`float` or `int`): the `sum(partials)` less the precision running sum `fsum`.
Inherited from `named._Named`: `classname`, `classnaming`, `iteration`, `name`, `named`, `named2`, `named3`, `named4`, `sizeof` Inherited from `object`: `__class__`

Method Details

### __init__ (self, *xs, **name_f2product_nonfinites_RESIDUAL) (Constructor) |
New Fsum. Arguments: `xs` - No, one or more initial items to accumulate (each `scalar`, an Fsum or Fsum2Tuple), all positional. `name_f2product_nonfinites_RESIDUAL` - Optional `name=NN` (`str`) and settings `f2product=None` (`bool`), `nonfinites=None` (`bool`) and `RESIDUAL=0.0` threshold (`scalar`) for this Fsum. Overrides: object.__init__ See Also: Methods Fsum.f2product, Fsum.nonfinites, Fsum.RESIDUAL, Fsum.fadd and Fsum.fadd_.

### __add__ (self, other) (Addition operator) |
Return `self + other` as an Fsum. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar`. Returns: The sum (Fsum). See Also: Methods Fsum.fadd_ and Fsum.fadd.

### __ceil__ (self) |
Return this instance' `math.ceil` as `int` or `float`. Returns: An `int` in Python 3+, but `float` in Python 2-. See Also: Methods Fsum.__floor__ and property Fsum.ceil.

### __cmp__ (self, other) (Comparison operator) |
Compare this with an other instance or `scalar`, Python 2-. Returns: -1, 0 or +1 (`int`). Raises: `TypeError` - Incompatible `other` `type`.

### __divmod__ (self, other, **raiser_RESIDUAL) |
Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` modulus. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.fdiv.

### __float__ (self) |
Return this instance' current, precision running sum as `float`. See Also: Methods Fsum.fsum and Fsum.int_float.

### __floor__ (self) |
Return this instance' `math.floor` as `int` or `float`. Returns: An `int` in Python 3+, but `float` in Python 2-. See Also: Methods Fsum.__ceil__ and property Fsum.floor.

### __floordiv__ (self, other) |
Return `self // other` as an Fsum. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. Returns: The `floor` quotient (Fsum). See Also: Methods Fsum.__ifloordiv__.

### __format__ (self, *other) |
Not implemented. Overrides: object.__format__

### __hash__ (self) (Hashing function) |
Return `hash(self)` as `float`. Overrides: object.__hash__

### __iadd__ (self, other) |
Apply `self += other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` value or an iterable of several of the former. Returns: This instance, updated (Fsum). Raises: `TypeError` - Invalid `other`, not `scalar` nor Fsum. See Also: Methods Fsum.fadd_ and Fsum.fadd.

### __ifloordiv__ (self, other) |
Apply `self //= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. Returns: This instance, updated (Fsum). Raises: `ResidualError` - Non-zero, significant residual in `other`. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`. `ZeroDivisionError` - Zero `other`. See Also: Methods Fsum.__itruediv__.

### __imatmul__ (self, other) |
Not implemented. Overrides: named._Named.__imatmul__

### __imod__ (self, other) |
Apply `self %= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` modulus. Returns: This instance, updated (Fsum). See Also: Method Fsum.__divmod__.

### __imul__ (self, other) |
Apply `self *= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` factor. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`.

### __int__ (self) |
Return this instance as an `int`. See Also: Method Fsum.int_float and properties Fsum.ceil and Fsum.floor.

### __ipow__ (self, other, *mod, **raiser_RESIDUAL) |
Apply `self **= other` to this instance. Arguments: `other` - The exponent (`scalar`, an Fsum or Fsum2Tuple). `mod` - Optional modulus (`int` or `None`) for the 3-argument `pow(self, other, mod)` version. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `ResidualError` - Invalid `RESIDUAL` or the residual is non-zero and significant and either `other` is a fractional or negative `scalar` or `mod` is given and not `None`. `TypeError` - Invalid `other` type or 3-argument `pow` invocation failed. `ValueError` - If `other` is a negative `scalar` and this instance is `0` or `other` is a fractional `scalar` and this instance is negative or has a non-zero and significant residual or `mod` is given as `0`. Note: If `mod` is given, the result will be an `integer` Fsum in Python 3+ if this instance `is_integer` or set to `as_integer` and `mod` is given and `None`. See Also: CPython function float_pow.

### __isub__ (self, other) |
Apply `self -= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` value or an iterable of several of the former. Returns: This instance, updated (Fsum). Raises: `TypeError` - Invalid `other` type. See Also: Methods Fsum.fsub_ and Fsum.fsub.

### __itruediv__ (self, other, **raiser_RESIDUAL) |
Apply `self /= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`. `ZeroDivisionError` - Zero `other`. See Also: Method Fsum.__ifloordiv__.

### __matmul__ (self, other) |
Not implemented. Overrides: named._Named.__matmul__

### __mod__ (self, other) |
Return `self % other` as an Fsum. See Also: Method Fsum.__imod__.

### __mul__ (self, other) |
Return `self * other` as an Fsum. See Also: Method Fsum.__imul__.

### __pow__ (self, other, *mod) |
Return `self**other` as an Fsum. See Also: Method Fsum.__ipow__.

### __radd__ (self, other) (Right-side addition operator) |
Return `other + self` as an Fsum. See Also: Method Fsum.__iadd__.

### __rdivmod__ (self, other) |
Return `divmod(other, self)` as 2-tuple `(quotient, remainder)`. See Also: Method Fsum.__divmod__.

### __rfloordiv__ (self, other) |
Return `other // self` as an Fsum. See Also: Method Fsum.__ifloordiv__.

### __rmatmul__ (self, other) |
Not implemented. Overrides: named._Named.__rmatmul__

### __rmod__ (self, other) |
Return `other % self` as an Fsum. See Also: Method Fsum.__imod__.

### __rmul__ (self, other) |
Return `other * self` as an Fsum. See Also: Method Fsum.__imul__.

### __round__ (self, *ndigits) |
Return `round(self, *ndigits` as an Fsum. Arguments: `ndigits` - Optional number of digits (`int`).

### __rpow__ (self, other, *mod) |
Return `other**self` as an Fsum. See Also: Method Fsum.__ipow__.

### __rsub__ (self, other) |
Return `other - self` as Fsum. See Also: Method Fsum.__isub__.

### __rtruediv__ (self, other, **raiser_RESIDUAL) |
Return `other / self` as an Fsum. See Also: Method Fsum.__itruediv__.

### __str__ (self) (Informal representation operator) |
Return the default `str(self)`. Overrides: object.__str__

### __sub__ (self, other) (Subtraction operator) |
Return `self - other` as an Fsum. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar`. Returns: The difference (Fsum). See Also: Method Fsum.__isub__.

### __truediv__ (self, other, **raiser_RESIDUAL) |
Return `self / other` as an Fsum. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: The quotient (Fsum). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.__itruediv__.

### __trunc__ (self) |
Return this instance as an `int`. See Also: Method Fsum.int_float and properties Fsum.ceil and Fsum.floor.

### __div__ (self, other, **raiser_RESIDUAL) |
Return `self / other` as an Fsum. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: The quotient (Fsum). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.__itruediv__.

### __idiv__ (self, other, **raiser_RESIDUAL) |
Apply `self /= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`. `ZeroDivisionError` - Zero `other`. See Also: Method Fsum.__ifloordiv__.

### __long__ (self) |
Return this instance as an `int`. See Also: Method Fsum.int_float and properties Fsum.ceil and Fsum.floor.

### __rdiv__ (self, other, **raiser_RESIDUAL) |
Return `other / self` as an Fsum. See Also: Method Fsum.__itruediv__.

### as_integer_ratio (self) |
Return this instance as the ratio of 2 integers. Returns: 2-Tuple `(numerator, denominator)` both `int` with `numerator` signed and `denominator` non-zero and positive. The `numerator` is non-finite if this instance is. See Also: Method Fsum.fint2 and `float.as_integer_ratio` in Python 2.7+.

### cmp (self, other) |
Compare this with an other instance or `scalar`, Python 2-. Returns: -1, 0 or +1 (`int`). Raises: `TypeError` - Incompatible `other` `type`.

### copy (self, deep=False, **name) |
Copy this instance, `shallow` or `deep`. Arguments: `name` - Optional, overriding `name='"copy"` (`str`). Returns: The copy (Fsum). Overrides: named._Named.copy

### divmod (self, other, **raiser_RESIDUAL) |
Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` modulus. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.fdiv.

### fadd (self, xs=`(``)`) |
Add an iterable's items to this instance. Arguments: `xs` - Iterable of items to add (each `scalar` or an Fsum or Fsum2Tuple instance). Returns: This instance (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - An invalid `xs` item. `ValueError` - Invalid or non-finite `xs` value.

### fadd_ (self, *xs) |
Add all positional items to this instance. Arguments: `xs` - Values to add (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. See Also: Method Fsum.fadd for further details.

### fcopy (self, deep=False, **name) |
Copy this instance, `shallow` or `deep`. Arguments: `name` - Optional, overriding `name='"copy"` (`str`). Returns: The copy (Fsum).

### fdiv (self, other, **raiser_RESIDUAL) |
Apply `self /= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` divisor. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`. `ZeroDivisionError` - Zero `other`. See Also: Method Fsum.__ifloordiv__.

### fdivmod (self, other, **raiser_RESIDUAL) |
Return `divmod(self, other)` as a DivMod2Tuple with quotient `div` an `int` in Python 3+ or `float` in Python 2- and remainder `mod` an Fsum instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` modulus. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.fdiv.

### fint (self, name='', **raiser_RESIDUAL) |
Return this instance' current running sum as `integer`. Arguments: `name` - Optional, overriding `name="fint"` (`str`). `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: The `integer` sum (Fsum) if this instance `is_integer` with a zero or insignificant integer residual. Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Methods Fsum.fint2, Fsum.int_float and Fsum.is_integer.

### fint2 (self, **name) |
Return this instance' current running sum as `int` and the integer residual. Arguments: `name` - Optional name (`str`). Returns: An Fsum2Tuple`(fsum, residual)` with `fsum` an `int` and integer `residual` a `float` or `INT0` if the `fsum` is considered to be exact. The `fsum` is non-finite if this instance is.

### fma (self, other1, other2, **nonfinites) |
Fused-multiply-add `self *= other1; self += other2`. Arguments: `other1` - Multiplier (`scalar`, an Fsum or Fsum2Tuple). `other2` - Addend (`scalar`, an Fsum or Fsum2Tuple). `nonfinites` - Use `nonfinites=True` or `False`, to override nonfinites and nonfiniterrors default (`bool`).

### fmul (self, other) |
Apply `self *= other` to this instance. Arguments: `other` - An Fsum, Fsum2Tuple or `scalar` factor. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Invalid `other` type. `ValueError` - Invalid or non-finite `other`.

### f2mul (self, *others, **raiser) |
DEPRECATED on 2024.09.13, use method f2mul_. Decorators: `@deprecated_method`

### f2mul_ (self, *others, **nonfinites) |
Return `self * other * other ...` for all `others` using cascaded, accurate multiplication like with f2product set to `True`. Arguments: `others` - Multipliers (each `scalar`, an Fsum or Fsum2Tuple), all positional. `nonfinites` - Use `nonfinites=True` or `False`, to override both nonfinites and the nonfiniterrors default (`bool`). Returns: The cascaded TwoProduct (Fsum or `float`). See Also: Equations 2.3

### fover (self, over, **raiser_RESIDUAL) |
Apply `self /= over` and summate. Arguments: `over` - An Fsum or `scalar` denominator. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: Precision running sum (`float`). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Methods Fsum.fsum and Fsum.__itruediv__.

### fpow (self, other, *mod, **raiser_RESIDUAL) |
Apply `self **= other` to this instance. Arguments: `other` - The exponent (`scalar`, an Fsum or Fsum2Tuple). `mod` - Optional modulus (`int` or `None`) for the 3-argument `pow(self, other, mod)` version. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This instance, updated (Fsum). Raises: `OverflowError` - Partial `2sum` overflow. `ResidualError` - Invalid `RESIDUAL` or the residual is non-zero and significant and either `other` is a fractional or negative `scalar` or `mod` is given and not `None`. `TypeError` - Invalid `other` type or 3-argument `pow` invocation failed. `ValueError` - If `other` is a negative `scalar` and this instance is `0` or `other` is a fractional `scalar` and this instance is negative or has a non-zero and significant residual or `mod` is given as `0`. Note: If `mod` is given, the result will be an `integer` Fsum in Python 3+ if this instance `is_integer` or set to `as_integer` and `mod` is given and `None`. See Also: CPython function float_pow.

### f2product (self, *two) |
Get and set accurate TwoProduct multiplication for this Fsum, overriding the f2product default. Arguments: `two` - If omitted, leave the override unchanged, if `True`, turn TwoProduct on, if `False` off, if `None`e remove th override (`bool` or `None`). Returns: The previous setting (`bool` or `None` if not set). See Also: Function f2product. Note: Use `f.f2product() or f2product()` to determine whether multiplication is accurate for Fsum `f`.

### fset_ (self, *xs) |
Apply `self.partials = Fsum(*xs).partials`. Arguments: `xs` - Optional, new values (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. Returns: This instance, replaced (`Fsum`). See Also: Method Fsum.fadd for further details.

### fsub (self, xs=`(``)`) |
Subtract an iterable's items from this instance. See Also: Method Fsum.fadd for further details.

### fsub_ (self, *xs) |
Subtract all positional items from this instance. See Also: Method Fsum.fadd_ for further details.

### fsum (self, xs=`(``)`) |
Add an iterable's items, summate and return the current precision running sum. Arguments: `xs` - Iterable of items to add (each item `scalar` or an Fsum or Fsum2Tuple instance). Returns: Precision running sum (`float` or `int`). See Also: Method Fsum.fadd. Note: Accumulation can continue after summation.

### fsum_ (self, *xs) |
Add any positional items, summate and return the current precision running sum. Arguments: `xs` - Items to add (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. Returns: Precision running sum (`float` or `int`). See Also: Methods Fsum.fsum, Fsum.Fsum_ and Fsum.fsumf_.

### Fsum_ (self, *xs, **name) |
Like method Fsum.fsum_ but returning a named Fsum. Arguments: `name` - Optional name (`str`). Returns: Copy of this updated instance (Fsum).

### Fsum2Tuple_ (self, *xs, **name) |
Like method Fsum.fsum_ but returning a named Fsum2Tuple. Arguments: `name` - Optional name (`str`). Returns: Precision running sum (Fsum2Tuple).

### fsum2 (self, xs=`(``)`, **name) |
Add an iterable's items, summate and return the current precision running sum and the `residual`. Arguments: `xs` - Iterable of items to add (each item `scalar` or an Fsum or Fsum2Tuple instance). `name` - Optional `name=NN` (`str`). Returns: Fsum2Tuple`(fsum, residual)` with `fsum` the current precision running sum and `residual`, the (precision) sum of the remaining `partials`. The `residual is INT0` if the `fsum` is considered to be exact. See Also: Methods Fsum.fint2, Fsum.fsum and Fsum.fsum2_

### fsum2_ (self, *xs) |
Add any positional items, summate and return the current precision running sum and the differential. Arguments: `xs` - Values to add (each `scalar` or an Fsum or Fsum2Tuple instance), all positional. Returns: 2Tuple `(fsum, delta)` with the current, precision running `fsum` like method Fsum.fsum and `delta`, the difference with previous running `fsum`, `float`. See Also: Methods Fsum.fsum_ and Fsum.fsum.

### int_float (self, **raiser_RESIDUAL) |
Return this instance' current running sum as `int` or `float`. Arguments: `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: This `int` sum if this instance `is_integer`, otherwise the `float` sum if the residual is zero or not significant. Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Methods Fsum.fint, Fsum.fint2, Fsum.is_integer, Fsum.RESIDUAL and property Fsum.as_iscalar.

### is_finite (self) |
Is this instance `finite`? (`bool`). See Also: Function isfinite.

### is_integer (self) |
Is this instance' running sum `integer`? (`bool`). See Also: Methods Fsum.fint, Fsum.fint2 and Fsum.is_scalar.

### is_math_fma (self) |
Is accurate f2product multiplication based on Python's `math.fma`? Returns: `True` if accurate multiplication uses `math.fma`, `False` an `fma` implementation as `math.fma` or `None`, a previous `PyGeodesy` implementation.

### is_math_fsum (self) |
Are the summation functions fsum, fsum_, fsumf_, fsum1, fsum1_ and fsum1f_ based on Python's `math.fsum`? Returns: `True` if summation functions use `math.fsum`, `False` otherwise.

### is_scalar (self, **raiser_RESIDUAL) |
Is this instance' running sum `scalar` without residual or with a residual ratio not exceeding the RESIDUAL threshold? Arguments: `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: `True` if this instance' non-zero residual `ratio` exceeds the RESIDUAL threshold (`bool`). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.RESIDUAL, Fsum.is_integer and property Fsum.as_iscalar.

### nonfinites (self, *OK) |
Handle non-finite `float`s as `inf`, `INF`, `NINF`, `nan` and `NAN` for this Fsum or throw `OverflowError` respectively `ValueError` exceptions, overriding the nonfiniterrors default. Arguments: `OK` - If omitted, leave the override unchanged, if `True`, non-finites are `OK`, if `False` throw exceptions or if `None` remove the override (`bool` or `None`). Returns: The previous setting (`bool` or `None` if not set). See Also: Function nonfiniterrors. Note: Use property nonfinitesOK to determine whether non-finites are `OK` for this Fsum and by the nonfiniterrors default.

### pow (self, x, *mod, **raiser_RESIDUAL) |
Return `self**x` as Fsum. Arguments: `x` - The exponent (`scalar`, an Fsum or Fsum2Tuple). `mod` - Optional modulus (`int` or `None`) for the 3-argument `pow(self, other, mod)` version. `raiser_RESIDUAL` - Use `raiser=False` to ignore ResidualErrors (`bool`) and `RESIDUAL=scalar` to override the current RESIDUAL. Returns: The `pow(self, x)` or `pow(self, x, *mod)` result (Fsum). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. Note: If `mod` is given and `None`, the result will be an `integer` Fsum provided this instance `is_integer` or set to `integer` by an Fsum.fint call. See Also: Methods Fsum.__ipow__, Fsum.fint, Fsum.is_integer and Fsum.root.

### rdiv (self, other, **raiser_RESIDUAL) |
Return `other / self` as an Fsum. See Also: Method Fsum.__itruediv__.

### RESIDUAL (self, *threshold) |
Get and set this instance' ratio for raising ResidualErrors, overriding the default from env variable `PYGEODESY_FSUM_RESIDUAL`. Arguments: `threshold` - If `scalar`, the ratio to exceed for raising ResidualErrors in division and exponention, if `None`, restore the default set with env variable `PYGEODESY_FSUM_RESIDUAL` or if omitted, keep the current setting. Returns: The previous `RESIDUAL` setting (`float`), default `0.0`. Raises: `ResidualError` - Invalid `threshold`. Note: ResidualErrors may be thrown if (1) the non-zero ratio `residual / fsum` exceeds the given `threshold` and (2) the `residual` is non-zero and (3) is significant vs the `fsum`, i.e. `(fsum + residual) != fsum` and (4) optional keyword argument `raiser=False` is missing. Specify a negative `threshold` for only non-zero `residual` testing without the significant case.

### root (self, root, **raiser_RESIDUAL) |
Return `self**(1 / root)` as Fsum. Arguments: `root` - Non-zero order (`scalar`, an Fsum or Fsum2Tuple). `raiser_RESIDUAL` - Use `raiser=False` to ignore any ResidualErrors (`bool`) or `RESIDUAL=scalar` to override the current RESIDUAL. Returns: The `self ** (1 / root)` result (Fsum). Raises: `ResidualError` - Non-zero, significant residual or invalid `RESIDUAL`. See Also: Method Fsum.pow.

### signOf (self, res=True) |
Determine the sign of this instance. Arguments: `res` - If `True`, consider the residual, otherwise ignore the latter (`bool`). Returns: The sign (`int`, -1, 0 or +1).

### toRepr (self, **lenc_prec_sep_fmt) |
Return this `Fsum` instance as representation. Arguments: `lenc_prec_sep_fmt` - Optional keyword arguments for method Fsum.toStr. Returns: This instance (`repr`). Overrides: named._Named.toRepr

### toStr (self, lenc=True, **prec_sep_fmt) |
Return this `Fsum` instance as string. Arguments: `lenc` - If `True`, include the current `[len]` of this Fsum enclosed in [brackets] (`bool`). `prec_sep_fmt` - Optional keyword arguments for method Fsum2Tuple.toStr. Returns: This instance (`str`). Overrides: named._Named.toStr

Property Details

### as_iscalar Get this instance as-is (Fsum with `non-zero residual`, `scalar` or non-finite). Get method: as_iscalar(self) - Get this instance as-is (Fsum with `non-zero residual`, `scalar` or non-finite). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### ceil Get this instance' `ceil` value (`int` in Python 3+, but `float` in Python 2-). Get method: ceil(self) - Get this instance' `ceil` value (`int` in Python 3+, but `float` in Python 2-). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. Note: This `ceil` takes the `residual` into account. See Also: Method Fsum.int_float and properties Fsum.floor, Fsum.imag and Fsum.real.

### float_int DEPRECATED, use method `Fsum.int_float`. Get method: float_int(self) - DEPRECATED, use method `Fsum.int_float`. Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### floor Get this instance' `floor` (`int` in Python 3+, but `float` in Python 2-). Get method: floor(self) - Get this instance' `floor` (`int` in Python 3+, but `float` in Python 2-). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. Note: This `floor` takes the `residual` into account. See Also: Method Fsum.int_float and properties Fsum.ceil, Fsum.imag and Fsum.real.

### imag Get the `imaginary` part of this instance (`0.0`, always). Get method: imag(self) - Get the `imaginary` part of this instance (`0.0`, always). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. See Also: Property Fsum.real.

### nonfinitesOK Are non-finites `OK` for this Fsum or by default? (`bool`). Get method: nonfinitesOK(self) - Are non-finites `OK` for this Fsum or by default? (`bool`). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### partials Get this instance' current, partial sums (`tuple` of `float`s). Get method: partials(self) - Get this instance' current, partial sums (`tuple` of `float`s). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value.

### real Get the `real` part of this instance (`float`). Get method: real(self) - Get the `real` part of this instance (`float`). Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. See Also: Methods Fsum.__float__ and Fsum.fsum and properties Fsum.ceil, Fsum.floor, Fsum.imag and Fsum.residual.

### residual Get this instance' residual or residue (`float` or `int`): the `sum(partials)` less the precision running sum `fsum`. Get method: residual(self) - Get this instance' residual or residue (`float` or `int`): the `sum(partials)` less the precision running sum `fsum`. Set method: _fset_error(inst, val) - Throws an `AttributeError`, always. Delete Method: _fdel(inst) - Zap the cached/memoized `property` value. Note: The `residual is INT0` iff the precision running `fsum` is considered to be exact. See Also: Methods Fsum.fsum, Fsum.fsum2 and Fsum.is_exact.