MMAR/README.md

# MMAR Volatility Forecasting

Multifractal Model of Asset Returns (MMAR) implementation for volatility forecasting, based on the work of Mandelbrot, Calvet, and Fisher (1997) and the empirical methodology of Zhang (2017).

This project accompanies the MQL5 article series:
- **Part 1**: [GARCH vs MMAR: A Python Comparison](https://www.mql5.com/en/articles/22438)
- **Part 2**: Native MQL5 library implementation (forthcoming)
- **Part 3**: Expert Advisor integration (forthcoming)

---

## Overview

The MMAR models financial returns as a Fractional Brownian Motion compounded by multifractal trading time:

```
X(t) = B_H[theta(t)]
```

Where:
- **B_H(t)** is a Fractional Brownian Motion with Hurst exponent H, capturing long memory and persistence in returns.
- **theta(t)** is multifractal trading time (the CDF of a multifractal measure constructed via multiplicative cascade), capturing volatility clustering and fat tails.

This compound process produces long memory, fat tails, volatility clustering, and scale consistency simultaneously — not as separate patches, but as natural consequences of a single generative mechanism.

---

## The 7-Step Pipeline

| Step | Module | Purpose |
|------|--------|---------|
| 1 | `step1_check_fractality.py` | Partition function analysis — tests whether moment scaling exists |
| 2 | `step2_extract_scaling.py` | Extract scaling function tau(q) and estimate Hurst exponent H |
| 3 | `step3_fit_spectrum.py` | Legendre transform to f(alpha), fit four theoretical distributions |
| 4 | `step4_generate_cascade.py` | Multiplicative cascade to produce multifractal trading time |
| 5 | `step5_generate_fbm.py` | Davies-Harte FBM generation with Cholesky fallback |
| 6 | `step6_combine_model.py` | Compound process X(t) = B_H[theta(t)] via linear interpolation |
| 7 | `step7_monte_carlo.py` | 1,000 Monte Carlo simulations for volatility forecasting |

Each step produces serialized output consumed by subsequent steps, allowing any individual step to be re-run without repeating the entire pipeline.

---

## Quick Start

### Prerequisites

- Python 3.9+
- MetaTrader 5 terminal (for live data; CSV fallback available)

### Installation

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt
```

### Configuration

Edit `config.py`:

```python
SYMBOL = "EURUSD"
TIMEFRAME_MT5 = "M5"
TIMEFRAME_MINUTES = 5
START_DATE = "2024-08-03"
END_DATE = "2026-03-01"
FORECAST_DAYS = 25
```

### Running the Pipeline

```bash
python run_step1.py    # Check fractality
python run_step2.py    # Extract scaling function and Hurst exponent
python run_step3.py    # Fit multifractal spectrum
python run_step4.py    # Generate cascade / trading time
python run_step5.py    # Generate FBM
python run_step6.py    # Combine into MMAR process
python run_step7.py    # Monte Carlo forecast
```

### Comparison with GARCH

```bash
python run_garch_comparison.py   # Head-to-head: MMAR vs GARCH(1,1)
python run_comparison.py         # MMAR vs realized volatility
```

---

## Project Structure

```
MMAR_Forecast/
├── config.py                   # All parameters and validation
├── data_loader.py              # MT5 data loading with CSV fallback
├── utils.py                    # Shared utilities
├── step1_check_fractality.py   # Partition function analysis
├── step2_extract_scaling.py    # Scaling function + Hurst estimation
├── step3_fit_spectrum.py       # Legendre transform + distribution fitting
├── step4_generate_cascade.py   # Multiplicative cascade
├── step5_generate_fbm.py       # Davies-Harte / Cholesky FBM
├── step6_combine_model.py      # MMAR compound process
├── step7_monte_carlo.py        # Monte Carlo volatility forecaster
├── garch_model.py              # GARCH(1,1) benchmark
├── compare_forecast.py         # Forecast validation against realized vol
├── run_step[1-7].py            # Runner scripts for each step
├── run_comparison.py           # MMAR vs realized validation
├── run_garch_comparison.py     # MMAR vs GARCH head-to-head
├── results/                    # Serialized intermediate results
├── plots/                      # Diagnostic visualizations
└── data/                       # CSV price data (optional)
```

---

## References

1. Mandelbrot, B. B., Calvet, L., Fisher, A. (1997). "The Multifractal Model of Asset Returns." Cowles Foundation Discussion Paper No. 1164.
2. Calvet, L., Fisher, A. (2002). "Multifractality in Asset Returns: Theory and Evidence." Review of Economics and Statistics, 84(3), 381-406.
3. Zhang, Y. T. (2017). "Volatility Forecasting with the Multifractal Model of Asset Returns." University of Florida.
4. Engle, R. F. (1982). "Autoregressive Conditional Heteroscedasticity with Estimates of the Variance of United Kingdom Inflation." Econometrica, 50(4), 987-1007.
5. Bollerslev, T. (1986). "Generalized Autoregressive Conditional Heteroskedasticity." Journal of Econometrics, 31(3), 307-327.

---

## License

This project is licensed under CC BY-NC 4.0. Free for academic and personal use. Commercial use requires permission. See LICENSE.md for details.

---

## Disclaimer

This code implements academic research for educational purposes. It is not financial advice. Volatility forecasting carries inherent uncertainty. Always validate on out-of-sample data and test on demo accounts before risking live capital.