Create README.md

README.md

@@ -0,0 +1,140 @@
+---
+title: "Hull-White Simulator"
+emoji: 📊
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit
+tags:
+  - actuarial
+  - finance
+  - stochastic-models
+  - monte-carlo
+  - interest-rates
+  - quantitative-finance
+  - gradio
+  - dashboard
+  - hull-white
+  - risk-management
+---
+
+# 📊 Hull-White Interest Rate Model Dashboard
+
+An interactive web dashboard for exploring the Hull-White short rate model, designed specifically for actuaries and financial professionals.
+
+[![Open in Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/alidenewade/hull-white-simulator)
+
+## 🎯 Overview
+
+The Hull-White model is a widely-used short rate model in quantitative finance, particularly valuable for:
+- **Interest rate derivatives pricing**
+- **Risk management and ALM**
+- **Solvency II capital calculations**
+- **Insurance liability valuation**
+
+This dashboard provides an intuitive interface to explore the model's behavior through Monte Carlo simulations.
+
+## 📈 Model Description
+
+The Hull-White model follows the stochastic differential equation:
+
+dr(t) = (θ(t) - ar(t))dt + σdW
+
+
+Where:
+- `r(t)` = instantaneous short rate at time t
+- `a` = mean reversion speed parameter
+- `σ` = volatility parameter  
+- `θ(t)` = time-dependent drift function
+- `dW` = Wiener process increment
+
+## 🚀 Features
+
+### Interactive Visualizations
+- **📊 Short Rate Paths**: Visualize multiple simulated interest rate trajectories
+- **📉 Mean Convergence**: Compare Monte Carlo means against theoretical expectations
+- **📈 Variance Analysis**: Examine variance convergence properties
+- **💰 Discount Factors**: Analyze zero-coupon bond pricing convergence
+- **🔍 Parameter Sensitivity**: Study the critical σ/a ratio effects
+- **📋 Statistics Table**: Summary statistics at key time points
+
+### Adjustable Parameters
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| Scenarios | 100 - 10,000 | Number of Monte Carlo paths |
+| Time Horizon | 5 - 50 years | Simulation time length |
+| Time Steps | 100 - 500 | Discretization granularity |
+| Mean Reversion (a) | 0.01 - 0.5 | Speed of mean reversion |
+| Volatility (σ) | 0.01 - 0.3 | Interest rate volatility |
+| Initial Rate (r₀) | 0.01 - 0.15 | Starting interest rate |
+
+## 🎛️ How to Use
+
+1. **Adjust Model Parameters**: Use the sliders in the left panel to modify Hull-White parameters
+2. **Explore Visualizations**: Click through the tabs to see different aspects of the model
+3. **Analyze Convergence**: Pay special attention to the σ/a ratio - values > 1 show poor convergence
+4. **Compare Theory vs Practice**: Observe how simulated results converge to theoretical expectations
+5. **Generate Statistics**: Review the summary table for quantitative analysis
+
+## 📊 Key Insights
+
+### Convergence Properties
+- **σ/a < 1**: Good Monte Carlo convergence
+- **σ/a ≈ 1**: Moderate convergence issues  
+- **σ/a > 1**: Poor convergence, especially for discount factors
+
+### Practical Considerations
+- **More scenarios** improve convergence but increase computation time
+- **Higher volatility** requires more scenarios for stable results
+- **Longer time horizons** show more pronounced convergence issues
+
+## 🔧 Technical Implementation
+
+### Model Features
+- **Gaussian Process**: Exploits Hull-White's analytical properties
+- **Conditional Moments**: Uses exact conditional mean and variance formulas
+- **Vector Operations**: Efficient numpy-based simulations
+- **Reproducible Results**: Fixed random seed for consistency
+
+### Performance Optimized
+- Real-time parameter updates
+- Efficient matrix operations
+- Responsive visualization updates
+- Memory-efficient data handling
+
+## 📚 Educational Value
+
+Perfect for:
+- **University Finance Courses**: Teaching stochastic interest rate models
+- **Actuarial Training**: Understanding ALM and risk management
+- **Professional Development**: Exploring quantitative finance concepts
+- **Model Validation**: Testing parameter sensitivity and convergence
+
+## 🎓 Theoretical Background
+
+The implementation follows established literature:
+- **Brigo & Mercurio**: Interest Rate Models - Theory and Practice
+- **Glasserman**: Monte Carlo Methods in Financial Engineering
+- **Hull**: Options, Futures, and Other Derivatives
+
+### Key Mathematical Properties
+- **Mean**: E[r(t)|ℱₛ] = r(s)e^(-a(t-s)) + α(t) - α(s)e^(-a(t-s))
+- **Variance**: Var[r(t)|ℱₛ] = (σ²/2a)(1 - e^(-2a(t-s)))
+- **Alpha Function**: α(t) = f^M(0,t) + (σ²/2a²)(1-e^(-at))²
+
+## 🛠️ Installation & Deployment
+
+### Local Development
+```bash
+# Clone the repository
+git clone https://github.com/YOUR-USERNAME/hull-white-dashboard.git
+cd hull-white-dashboard
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python app.py