LPPLS Model Implementation

This directory contains a complete implementation of the Log-Periodic Power Law Singularity (LPPLS) model for Bitcoin bubble detection and prediction, as described in LPPLS-model.md.

Files

Core Implementation

• lppls_backtest.py - Main LPPLS model implementation with backtesting framework
• lppls_usage_guide.py - Complete usage guide with examples and explanations
• lppls_comprehensive_demo.py - Comprehensive demonstration across different time periods
• demo_lppls.py - Simple demonstration script
• test_lppls.py - Basic functionality tests

Quick Start

from lppls_backtest import LPPLSBacktest

# Initialize the system
lppls = LPPLSBacktest()

# Run backtest on recent data
results = lppls.run_backtest(
    start_date='2024-01-01',
    end_date='2024-11-30',
    window=10,           # Days for slope calculation
    tc_threshold=5,      # Days before critical time for signals
    slope_threshold=0.001 # Signal sensitivity
)

# Get future predictions
future_pred = lppls.predict_future(days_ahead=30)

Model Overview

The LPPLS model identifies financial bubbles by fitting price data to:

p(t) = A + B(tc - t)^m (1 + C * cos(ω * log(tc - t) + φ))

Where:

• A: Final price level after bubble
• B: Amplitude of power-law decay
• tc: Critical time (bubble peak/crash)
• m: Power-law exponent (0 < m < 1)
• C: Oscillation amplitude
• ω: Angular frequency
• φ: Phase

Key Features

✅ LPPLS Model Fitting - Uses differential evolution optimization for robust parameter estimation

✅ Local Slopes Analysis - Calculates trend slopes over moving windows to enhance signal quality

✅ Signal Generation - Generates buy/sell signals when approaching critical times with favorable trends

✅ Backtesting Framework - Complete portfolio simulation with performance metrics

✅ Future Prediction - Extrapolates model to predict future prices and critical events

✅ Flexible Data Sources - Supports both yfinance API and local CSV data

✅ Comprehensive Analysis - Includes Sharpe ratio, max drawdown, and trade analysis

Usage Examples

Basic Analysis

python lppls_usage_guide.py

Comprehensive Demo

python lppls_comprehensive_demo.py

Simple Backtest

python demo_lppls.py

Parameters Guide

Model Parameters

• window (5-30): Moving window size for slope calculation
• Smaller = more sensitive to short-term trends
• Larger = smoother, longer-term trends

• tc_threshold (1-15): Days before critical time to generate signals
• Smaller = signals closer to predicted event
• Larger = earlier warning signals

• slope_threshold (0.001-0.02): Minimum slope for signal generation
• Smaller = more signals, potentially more noise
• Larger = fewer, higher-quality signals

Optimization Parameters

• max_attempts (3-10): Number of optimization attempts with different starting points
• Initial parameters: Automatically estimated from data

Interpretation

Critical Time (tc)

• Predicted date when bubble/regime change may occur
• Not a guarantee, but statistical indication
• Compare with historical events for validation

Signals

• Buy signals: Generated near tc with positive local slopes
• Sell signals: Generated near tc with negative local slopes
• No signals: May indicate stable market conditions

Performance Metrics

• Total Return: Strategy performance vs buy-and-hold
• Sharpe Ratio: Risk-adjusted returns
• Max Drawdown: Largest portfolio decline
• Number of Trades: Signal frequency

Limitations

🔴 CRITICAL: Extreme Window Sensitivity Detected

The LPPLS model exhibits 100%+ prediction variance depending on training window size. A comprehensive sensitivity analysis (see full report) revealed:

• Predictions vary by 2.66× (166%) for the same target date depending on window choice
• Example for 2026-01-01: $82,330 (3 months) to $219,411 (3 years) - same model, different windows
• Critical time predictions vary by 645 days (Dec 2025 to Sep 2027)
• Default 730 days inadequate for Bitcoin's 4-year halving cycle

⚠️ DO NOT use single LPPLS predictions for investment decisions!

Recommended approach:

• ✅ Test multiple windows (1-4 years) and show prediction RANGES
• ✅ Use ensemble methods (average across multiple windows)
• ✅ Combine with other models (power law, on-chain metrics)
• ✅ Focus on bubble detection during active bubbles, not long-term forecasting
• ❌ Do NOT rely on single-window predictions
• ❌ Do NOT use for long-term investment planning alone

See also:

• LPPLS Window Sensitivity Analysis Report - Full 16-page technical analysis
• LPPLS Sensitivity Summary - Executive summary
• Sensitivity Analysis Visualization - Bar chart showing variance
• Raw Results Data - Machine-readable results

---

Other Limitations

⚠️ Best for Bubble Detection: Model designed for bubble periods, not general prediction

⚠️ Historical Data Required: Needs 100+ days for reliable fitting

⚠️ Parameter Sensitivity: Results depend on parameter choices (window size is the most critical)

⚠️ No Guarantees: Statistical model, not deterministic prediction

⚠️ Research Tool: Use for analysis, not standalone trading

Research Background

Based on the work of:

• Sornette, D. et al. on financial bubble detection
• Johansen, A. & Sornette, D. on log-periodic power laws
• Giovanni's approach combining LPPLS with local slopes

Technical Notes

• Uses scipy.optimize.differential_evolution for global optimization
• Handles numerical edge cases and optimization failures
• Supports both linear and log-space price analysis
• Implements proper bounds and constraints for realistic parameters

Future Enhancements

Potential improvements:

• Multi-timeframe analysis
• Ensemble methods with multiple LPPLS fits
• Machine learning integration for parameter optimization
• Real-time monitoring and alerting
• Additional technical indicators integration

---

For detailed technical information, see the original research documentation in LPPLS-model.md.