🚀 Hull-White Pricing Engine

Mission: Production-grade Hull-White zero coupon bond pricing with finite difference and analytical methods.

Physics

Hull-White SDE: dr = (θ(t) - a·r)dt + σ·dW

PDE: ∂P/∂t + (θ(t) - ar)∂P/∂r + (σ²/2)∂²P/∂r² - rP = 0

Analytical Solution: P(0,T) = exp(A(T) - B(T)·r₀)

Installation

pip install -r requirements.txt

Usage

Command Line Interface

# Basic usage with defaults
python3 hull_white_engine.py

# Custom parameters
python3 hull_white_engine.py -a 0.2 -s 0.03 -r 0.04 -T 2.0

# Analytical only
python3 hull_white_engine.py -m analytical

# Numerical only  
python3 hull_white_engine.py -m numerical

# Quiet output (prices only)
python3 hull_white_engine.py --quiet

Python API

from decimal import Decimal
from hull_white_engine import HullWhiteEngine

# Initialize engine
engine = HullWhiteEngine(
    a=Decimal('0.1'),      # Mean reversion
    sigma=Decimal('0.02'), # Volatility  
    r0=Decimal('0.05')     # Initial rate
)

# Price 1-year zero coupon bond
results = engine.price_bond(Decimal('1.0'))
print(f"Analytical: {results['analytical']}")
print(f"Numerical:  {results['numerical']}")
print(f"Error:      {results['error']}")

# Get only analytical price
analytical = engine.analytical_price(Decimal('1.0'))

# Get only numerical price with custom grid
numerical = engine.finite_difference_price(
    T=Decimal('1.0'),
    N_r=200,  # Rate grid points
    N_t=1000  # Time steps
)

CLI Options

-a, --mean_reversion  Mean reversion speed (default: 0.1)
-s, --sigma          Volatility (default: 0.02)  
-r, --r0             Initial interest rate (default: 0.05)
-T, --maturity       Time to maturity (default: 1.0)
-m, --method         analytical|numerical|both (default: both)
--quiet              Output prices only

Output Example

🚀 Hull-White Zero Coupon Bond Pricing
Parameters: a=0.1, σ=0.02, r₀=0.05, T=1.0

Analytical Price:    0.95180750
Numerical Price:     0.95174822
Absolute Error:      5.93e-05
Relative Error:      0.0062%

🔬 Physics Check:
Discount Factor: 0.951807
Implied Rate:    0.0494 (4.94%)
Expected ~r₀:    0.0500 (5.00%)

Engineering Principles

• Decimal precision: All financial calculations use Decimal for accuracy
• Physics validation: Implied rate verification against expected values
• Production API: Clean interface for integration into larger systems
• CLI flexibility: Command-line tool for standalone usage

Mission complete. Production ready. 🚀