Go Floating-Point Explorer

An educational CLI tool that demonstrates floating-point inaccuracies, rounding behavior, and numeric instability in Go. Perfect for learning about IEEE 754 floating-point arithmetic and understanding precision loss in real-world scenarios.

Features

• 🔍 Basic Precision Loss Examples - Classic demonstrations like 0.1 + 0.2 ≠ 0.3
• 🧮 Expression Calculator - Evaluate expressions with step-by-step precision tracking
• 🔄 Rounding Behavior - Explore different rounding modes (Round, Floor, Ceil, Trunc)
• ⚠️ Numeric Instability - See catastrophic cancellation, associativity loss, and accumulation errors
• 💾 Binary Representation - View IEEE 754 binary/hex encoding of floating-point numbers

Installation

# Clone the repository
git clone https://github.com/BaseMax/go-fp-explorer.git
cd go-fp-explorer

# Build the binary
go build -o fp-explorer

# Run the tool
./fp-explorer

Usage

Interactive Mode

Run without arguments to enter interactive mode:

./fp-explorer

Available commands:

• 1 - Basic precision loss examples
• 2 - Expression calculator with precision tracking
• 3 - Rounding behavior demonstrations
• 4 - Numeric instability examples
• 5 - Representation examples (binary/hex)
• help - Show help menu
• exit - Exit the program

Command-Line Mode

Evaluate expressions directly from the command line:

./fp-explorer "0.1 + 0.2"
./fp-explorer "1.0 - 0.9"
./fp-explorer "0.1 * 10"

Or run specific demonstrations:

./fp-explorer 1  # Basic precision loss examples
./fp-explorer 4  # Numeric instability examples

Examples

Classic Precision Loss

=== Basic Precision Loss Examples ===

Example 1: Classic 0.1 + 0.2
  Expression: 0.1 + 0.2
  Expected:   0.3
  Actual:     0.30000000000000004
  Exact:      0.30000000000000004
  ⚠ Precision loss detected!

Detailed Expression Analysis

=== Detailed Analysis ===

Step 1: Input Values
  Left operand:  0.10000000000000001 (exact: 0.10000000000000001)
  Operator:      +
  Right operand: 0.20000000000000001 (exact: 0.20000000000000001)
  Binary (left):  0011111110111001100110011001100110011001100110011001100110011010
  Binary (right): 0011111111001001100110011001100110011001100110011001100110011010

Step 2: Operation
  Computing: 0.10000000000000001 + 0.20000000000000001

Step 3: Result
  Result (default):    0.30000000000000004
  Result (exact):      0.30000000000000004
  Result (scientific): 3.000000e-01
  Binary representation: 0011111111010011001100110011001100110011001100110011001100110100

Step 4: Precision Analysis
  Theoretical result: 0.30000000000000004
  ⚠ Classic precision loss: 0.1 + 0.2 ≠ 0.3
  Reason: 0.1 and 0.2 cannot be exactly represented in binary
  ULP (Unit in Last Place): 5.551115e-17
  Machine epsilon (ε):      2.220446e-16

Numeric Instability

=== Numeric Instability Examples ===

1. Catastrophic Cancellation
   When subtracting nearly equal numbers:
   a = 1.00000000000000000
   b = 1.00000000000000000
   a - b = 0.00000000000000000e+00
   Significant digits lost in subtraction!

2. Quadratic Formula Instability
   Solving: x² - 10000000000x + 1 = 0
   Standard formula:
     x₁ = 10000000000.00000000000000000
     x₂ = 0.00000000000000000e+00
   Alternative formula for x₂:
     x₂ = 1.00000000000000004e-10
   Better precision using alternative computation!

4. Accumulation Error
   Adding 0.1 repeatedly vs multiplying:
   Sum (0.1 added 10 times):  0.99999999999999989
   Product (0.1 × 10):        1.00000000000000000
   Expected:                  1.0
   Difference: -1.11022302462515654e-16
   ⚠ Accumulation error detected!

Educational Purpose

This tool is designed for:

• Students learning about floating-point arithmetic
• Developers debugging precision issues in numerical code
• Researchers exploring IEEE 754 behavior
• Educators demonstrating floating-point concepts

Key Concepts Demonstrated

1. Binary Representation - Why decimal numbers like 0.1 can't be exactly represented
2. Precision Loss - How arithmetic operations compound rounding errors
3. Catastrophic Cancellation - Loss of significant digits when subtracting similar numbers
4. Associativity - Floating-point addition is not associative
5. Accumulation - Errors accumulate in repeated operations
6. Rounding Modes - Different approaches to rounding (banker's rounding, floor, ceil, truncate)
7. ULP Analysis - Understanding Unit in the Last Place
8. Machine Epsilon - The smallest difference between representable numbers

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new demonstrations
• Improve documentation
• Add more educational examples

Author

Max Base - @BaseMax