Precision & Tolerances

Core Precision Concepts

Automatic Tolerance Inference

• Derived per transaction individually
• Calculated separately for each currency
• Uses half of the last significant digit
• Example:

2013-04-03 * "Buy Fund"
  Assets:Fund     10.22626 FUND {37.61 USD}  ; Tolerance: 0.000005 FUND
  Assets:Cash     -384.61 USD                 ; Tolerance: 0.005 USD

Transaction Weight Rules

1. Simple Amount: Uses exact amount
2. Price Posting: Amount × Price
3. Cost Posting: Amount × Cost
4. Cost+Price: Uses cost only, price ignored for balancing

Precision Inference Rules

1. Number Format

   • Integer amounts do not contribute to precision
   • Maximum automatic precision is 0.05 units
   • Costs and prices are excluded from tolerance inference
   • Multiple precisions use the coarsest (largest) value

2. Default Handling

; Global default
option "inferred_tolerance_default" "*:0.001"

; Currency-specific
option "inferred_tolerance_default" "USD:0.003"

3. Tolerance Multiplier

option "inferred_tolerance_multiplier" "1.2"

4. Cost-Based Inference

option "infer_tolerance_from_cost" "TRUE"

Balance Assertions

Basic Format

2015-05-08 balance Assets:Fund  4.271 RGAGX   ; Tolerance: ±0.001
2015-05-08 balance Assets:Fund  4.27 RGAGX    ; Tolerance: ±0.01

Explicit Tolerances

2015-05-08 balance Assets:Fund  4.271 ~ 0.01 RGAGX

Rounding Management

Rounding Error Tracking

option "account_rounding" "Equity:RoundingError"

2000-01-01 open Equity:RoundingError

2013-02-23 * "Purchase"
  Assets:Invest     1.245 RGAGX {43.23 USD}
  Assets:Cash      -53.82 USD
  Equity:RoundingError   -0.00135 USD

Inferred Number Precision

1. No Tolerance Specified

   • Uses full precision
   • No rounding occurs

2. With Default Tolerance

option "default_tolerance" "USD:0.001"
; Number quantized to 0.001 before insertion

3. With Rounding Account

option "default_tolerance" "USD:0.01"
option "account_rounding" "Equity:RoundingError"
; Residuals captured in rounding account

Implementation Details

1. Number Representation

   • Uses decimal representation (not float)
   • 28 decimal places precision
   • Preserves exact decimal precision

2. DisplayContext Class

   • Controls number formatting
   • Currency-specific precision handling
   • Supports alignment and comma insertion

3. Precision vs Tolerance

   • Precision: Display format
   • Tolerance: Balance verification allowance

Best Practices

1. Initial Setup

option "inferred_tolerance_default" "*:0.005"
option "inferred_tolerance_multiplier" "1.1"
option "account_rounding" "Equity:RoundingError"

2. Troubleshooting Tips

   • Add digits for local tolerance inference
   • Use explicit tolerances for problematic assertions
   • Track rounding errors in dedicated account
   • Consider currency-specific defaults

3. Migration Strategy

   • Start with generous global tolerance
   • Gradually tighten and fix errors
   • Add explicit digits where needed
   • Monitor rounding accumulation

This technical guide covers the core aspects of precision handling in Beancount while maintaining exact fidelity to the documented behavior.