Python math.fsum(): High-Precision Floating-Point Summation

Syntax & Parameters 🔝

The math.fsum() function is part of Python's standard math module:

import math

math.fsum(iterable)

Basic Usage with Diverse Iterables 🔝

math.fsum() accepts any Python iterable, automatically converting integers and floats into a consolidated float total:

import math

# 1. Summing a list of integers and floats
num_list = [10, 20.5, 30, 40.25]
print("List sum:     ", math.fsum(num_list))   # Output: 100.75

# 2. Summing a tuple
num_tuple = (1.1, 2.2, 3.3)
print("Tuple sum:    ", math.fsum(num_tuple))  # Output: 6.6

# 3. Summing a set (distinct values)
num_set = {5, 10, 15}
print("Set sum:      ", math.fsum(num_set))    # Output: 30.0

# 4. Summing a range object
print("Range sum:    ", math.fsum(range(1, 11))) # Output: 55.0

# 5. Summing a generator expression (memory efficient)
squares_gen = (x**2 for x in range(1, 6))
print("Generator sum:", math.fsum(squares_gen)) # Output: 55.0

# 6. Empty iterable returns 0.0
print("Empty sum:    ", math.fsum([]))           # Output: 0.0

Output:

List sum:      100.75
Tuple sum:     6.6
Set sum:       30.0
Range sum:     55.0
Generator sum: 55.0
Empty sum:     0.0

Why math.fsum() Beats sum(): Precision & Catastrophic Cancellation 🔝

The primary motivation for math.fsum() is preventing floating-point rounding errors. Python's built-in sum() adds numbers sequentially: accum = accum + x. At every addition step, IEEE 754 rounds the result to 53 bits of precision, discarding low-order bits.

Scenario 1: Accumulation of Repeated Decimals

In base-2 binary floating point, the decimal 0.1 cannot be represented finitely. Repeated sequential additions compound rounding noise:

import math

tenths = [0.1] * 10

print("Built-in sum():  ", sum(tenths))        # 0.9999999999999999
print("math.fsum():     ", math.fsum(tenths))   # 1.0 (Exact!)
print("sum() == 1.0?     ", sum(tenths) == 1.0)
print("math.fsum() == 1.0?", math.fsum(tenths) == 1.0)

Output:

Built-in sum():   0.9999999999999999
math.fsum():      1.0
sum() == 1.0?     False
math.fsum() == 1.0? True

Scenario 2: Catastrophic Cancellation

Catastrophic cancellation occurs when numbers with huge magnitude differences cancel each other out. With naive summation, adding a small number to a massive number drops the small number entirely off the precision register:

import math

# 1e100 and -1e100 cancel out, leaving exactly 1.0
values = [1e100, 1.0, -1e100]

print("Built-in sum():", sum(values))       # Evaluates: (1e100 + 1.0) - 1e100 = 0.0 !
print("math.fsum():   ", math.fsum(values))  # Correctly tracks 1.0 !

Output:

Built-in sum(): 0.0
math.fsum():    1.0

How Shewchuk's Algorithm Works 🔝

The C implementation of math.fsum() uses Jonathan Shewchuk's famous adaptive-precision summation algorithm (1997):

• Instead of maintaining a single running float total, math.fsum() maintains an array of partial sums called an expansion.
• When each new number is added, error terms (the bits that would normally be discarded during rounding) are captured and saved into lower-order buckets in the expansion.
• Only after every number in the iterable has been processed does math.fsum() compress the expansion into a single IEEE 754 float, performing exactly one rounding operation at the very end.

math.fsum() vs. sum() vs. numpy.sum() 🔝

Special Values: Infinities and NaNs 🔝

math.fsum() adheres strictly to IEEE 754 arithmetic standards when encountering special floating-point numbers:

import math

# Adding infinity to finite numbers yields infinity
print("fsum([1.0, 2.0, inf]): ", math.fsum([1.0, 2.0, float('inf')]))

# Opposing infinities (+inf and -inf) produce NaN (indeterminate form)
print("fsum([inf, -inf]):      ", math.fsum([float('inf'), float('-inf')]))

# Any NaN element propagates to NaN
print("fsum([10.0, nan, 5.0]):  ", math.fsum([10.0, float('nan'), 5.0]))

Output:

fsum([1.0, 2.0, inf]):  inf
fsum([inf, -inf]):      nan
fsum([10.0, nan, 5.0]):  nan

Hands-on Exercise: High-Volume Financial Ledger Auditor with Assertions 🔝

In financial banking and cryptocurrency clearinghouses, transactions span orders of magnitude: massive institutional transfers (e.g. $10,000,000.00) interleave with millions of retail micro-transactions ($0.10, $0.05). If an accounting reconciliation system uses naive summation, cumulative rounding errors falsely trigger fraud or imbalance alerts.

Let's build an audit function that verifies whether an accounting ledger balances to zero, comparing naive sum() against math.fsum():

import math

def audit_ledger_balance(transactions, tolerance=1e-12):
    """
    Audits a stream of debit and credit transactions.
    Returns (is_balanced, fsum_total, naive_sum_total).
    """
    if not isinstance(transactions, (list, tuple)):
        raise TypeError("Transactions must be a list or tuple.")
    
    exact_total = math.fsum(transactions)
    naive_total = sum(transactions)
    balanced = math.isclose(exact_total, 0.0, abs_tol=tolerance)
    
    return (balanced, exact_total, naive_total)

# Test Case: 10 small deposits of $0.10 offset by a single $1.00 withdrawal
balanced_batch = [0.1] * 10 + [-1.0]
is_bal, f_tot, n_tot = audit_ledger_balance(balanced_batch)

print(f"Batch 1 Balanced? {is_bal} | fsum: {f_tot} | naive sum: {n_tot}")

# Unit Assertions
assert is_bal is True
assert f_tot == 0.0
assert n_tot != 0.0  # Naive sum fails (-1.1102e-16)!

# Massive institutional offset batch
large_batch = [50000000.0, 0.07, -50000000.0, -0.07]
is_bal2, f_tot2, _ = audit_ledger_balance(large_batch)
assert is_bal2 is True
assert f_tot2 == 0.0

print("All financial ledger audit assertions passed successfully!")

Practice in Google Colab & GitHub 🔝

Open in Google Colab View on GitHub

Run all math.fsum() precision tests interactively, reproduce catastrophic cancellation benchmarks, compare with sum(), and audit financial transaction ledgers in Google Colab.

More Details & Related Guides 🔝

• Python Math Module Overview — Master arithmetic, trigonometry, and numeric constants in Python.
• Python sum() Built-in Function — Summing numbers with Python's core built-in function.
• math.fmod() Function — Precise floating-point modulus calculation.
• math.frexp() Function — Decompose floats into binary mantissa and exponent.
• math.ldexp() Function — Reconstruct floats by multiplying mantissa by powers of two.
• Python Iterators & Iterables — Comprehensive guide to sequences, generators, and iterators.
• Python Lists Tutorial — Working with dynamic arrays and lists in Python.
• Python float Data Type — Complete guide to IEEE 754 floating-point mechanics.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: