PreciseSum
Defined in: packages/core/src/number/precise-sum.ts:35
An exactly-rounded running total: fold terms in one at a time with PreciseSum.add, then read PreciseSum.value for the binary64 nearest the true mathematical sum of everything added so far — as if every addition had been performed at infinite precision and rounded once at the end.
Shewchuk’s partial-expansion algorithm (the one behind Python’s math.fsum
and the Math.sumPrecise proposal): each term is folded into a list of
non-overlapping partial sums that together represent the running total
exactly. Intermediate overflow is compensated the way the proposal’s
reference implementation does it, with a biased partial counting how many
times 2 ** 1024 has been factored out — so a run that leaves the finite
range and comes back still answers exactly.
Prefer sumPrecise when the terms are already available as a single
iterable; that is the common case and it reads better. Reach for this class
when they are not — typically one loop feeding several totals at once (a
polygon centroid accumulating cx, cy and the signed area together), where
one iterable per total would mean re-deriving every term.
Exact summation only removes the error of the additions. When the terms
are themselves products, round each one first with @ac-kit/math-scalar’s
diffOfProducts or sumOfProducts; a term that arrives already wrong cannot
be recovered here.
See sumPrecise for when exact summation is worth reaching for at all.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PreciseSum():
PreciseSum
Returns
Section titled “Returns”PreciseSum
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get value():
number
Defined in: packages/core/src/number/precise-sum.ts:123
The exactly-rounded total of every term added so far. Reading is O(k) and leaves the accumulator usable for further add calls.
-0 while no finite term has been added, matching Math.sumPrecise on an
empty input; NaN if any term was NaN or if both infinities were seen.
Returns
Section titled “Returns”number
Methods
Section titled “Methods”add(
value):void
Defined in: packages/core/src/number/precise-sum.ts:54
Folds value into the running total.
O(k) additions, where k is the number of live partials — 1 or 2 for well-conditioned input, bounded by the exponent range at worst.
Parameters
Section titled “Parameters”number
The term to add. Non-finite terms are recorded separately and settled when value is read.
Returns
Section titled “Returns”void