Precision & Quantization Reference

The Babylon simulation uses quantized floating-point values to prevent drift accumulation over long simulations. This reference documents the Gatekeeper Pattern and quantization utilities.

The Gatekeeper Pattern

Quantization is applied at the TYPE level (when values enter Pydantic models), not inside formula calculations. This ensures:

  1. All values entering the simulation are on a fixed grid

  2. Formula internals remain pure mathematical operations

  3. No hidden precision loss during calculations

Key Principle: Constrained types (Probability, Currency, Intensity) apply quantization via Pydantic validators, not formulas.

Epoch 0 Physics Hardening

All floating-point values in the simulation snap to a precision grid:

  • Default Grid: \(10^{-5}\) (0.00001 resolution)

  • Purpose: Prevent drift accumulation over long simulations

  • Rounding: ROUND_HALF_UP (symmetric rounding)

Symmetric Rounding (ROUND_HALF_UP)

The quantization algorithm uses symmetric rounding where ties round away from zero:

Value

Quantized (5 decimals)

Note

0.123456789

0.12346

Rounds up (6 > 5)

-0.123456789

-0.12346

Rounds away from zero

0.123455

0.12346

Tie rounds up

-0.123455

-0.12346

Tie rounds away from zero

0.0

0.0

Zero is fixed point

Implementation:

from babylon.utils.math import quantize

quantize(0.123456789)   # Returns 0.12346
quantize(-0.123456789)  # Returns -0.12346
quantize(0.123455)      # Returns 0.12346 (tie → away from zero)

Precision Configuration

The precision can be adjusted for testing or scenario-specific needs:

Decimal Places

Grid Size

Use Case

1

0.1

Coarse (fast tests)

3

0.001

Currency display

5 (default)

0.00001

Sub-penny precision

10

0.0000000001

Ultra-precise (scientific)

API:

from babylon.utils.math import get_precision, set_precision, quantize

# Check current precision
get_precision()  # Returns 5

# Change precision for testing
set_precision(3)
quantize(0.1234)  # Returns 0.123

# Restore default
set_precision(5)

Constrained Types Integration

Pydantic constrained types automatically apply quantization:

from babylon.models import Probability, Currency, Ratio

# Quantization happens on assignment
prob = Probability(0.123456789)
assert float(prob) == 0.12346

# This is the Gatekeeper: validation at boundary
currency = Currency(99.999999)
assert float(currency) == 100.0

Edge Cases

The quantization function handles edge cases defensively:

Input

Output

Behavior

None

0.0

Treated as zero

0.0

0.0

Fixed point

Very large

Quantized

Stable (no overflow)

Very small

Quantized

Stable (no underflow)

Idempotency: Quantizing an already-quantized value returns the same value:

x = quantize(0.123456789)  # 0.12346
y = quantize(x)            # 0.12346 (unchanged)
assert x == y

See Also