Metadata-Version: 2.4
Name: VIX-Spike
Version: 1.0.2
Summary: A Python library for pricing VIX options using shot noise models
Author: VIX Spike VolOfVol Research Team
License: MIT
Project-URL: Homepage, https://pypi.org/project/VIX-Spike/
Keywords: vix,options,pricing,finance,derivatives,monte-carlo,fft,shot-noise
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# VIX Pricer

> **Replication package for:**
>
> Fan, Z., Ryu, D., & Ye, Y. (2026). *Valuation of VIX derivatives: Incorporating larger spikes in volatility-of-volatility dynamics.*

A Python library for pricing VIX options using stochastic volatility models. This package implements both Fourier-based methods and Monte Carlo methods for efficient option pricing.

## Features

- **Affine Characteristic Function**: Solves coupled Riccati-type ODEs for VIX direct models
- **FFT Pricing**: Carr-Madan FFT method for fast European option pricing
- **Monte Carlo Simulation**: Euler-Maruyama discretization for path simulation
- **Model Validation**: Built-in framework to compare FFT and MC pricing accuracy
- **Flexible Architecture**: Modular design for easy extension and customization

## Installation

### From PyPI

```bash
pip install VIX-Spike
```

## Quick Start

### Basic Option Pricing

```python
from Pricer import ModelParameters, InitialConditions, FFTPricer

# Define model parameters
params = ModelParameters(
    T=0.0833,           # Time to maturity (1 month)
    kappa=5.0,          # Mean-reversion speed
    kappam=0.5,         # Long-term variance mean-reversion
    thetam=0.04,        # Long-run variance mean
    omegam=0.3,         # Variance volatility
    kappa1=3.0,         # Instantaneous variance mean-reversion
    theta1=0.04,        # Instantaneous variance long-run mean
    omega1=0.5,         # Vol-of-vol
    rho1=-0.7,          # Correlation
    bv=10.0,            # Shot noise decay rate
    lamb=5.0,           # Jump intensity
    muJV=0.02,          # Mean jump size
)

# Set initial conditions
initial = InitialConditions(
    lnS0=2.7,           # Initial log-VIX
    m0=0.04,            # Initial variance center
    v10=0.04,           # Initial instantaneous variance
    Lv0=0.01,           # Initial shot noise level
)

# Price a call option
strike = 15.0
risk_free_rate = 0.0
strikes, prices = FFTPricer.price_call_fft(
    r=risk_free_rate,
    T=params.T,
    params=params,
    initial=initial,
    K=strike
)

print(f"Call option price at K={strike}: {prices[0]:.4f}")
```

### Monte Carlo Simulation

```python
from Pricer import MonteCarloSimulator

# Create simulator
mc = MonteCarloSimulator()

# Generate paths
paths = mc.generate_paths(
    params=params,
    initial=initial,
    num_paths=10000,
    num_steps=100
)

# Price option using Monte Carlo
mc_price = mc.price_call_mc(
    r=risk_free_rate,
    T=params.T,
    params=params,
    initial=initial,
    K=strike,
    num_paths=100000
)

print(f"Monte Carlo price: {mc_price:.4f}")
```

### Model Validation

```python
from Pricer import ModelValidator

# Create validator
validator = ModelValidator()

# Compare FFT vs Monte Carlo across multiple strikes
results = validator.validate_pricing(
    params=params,
    initial=initial,
    strikes=[12, 13, 14, 15, 16, 17, 18],
    r=risk_free_rate,
    num_mc_paths=50000
)

print(results)
```

## Model Description

The library implements a reduced VIX shot noise model with the following dynamics:

**Log-VIX Process:**
$$d\ln S_t = \kappa(\theta_t - \ln S_t)dt + \sqrt{v_{1t}}dW_t^{(1)}$$

**Stochastic central tendency (OU Process):**
$$dm_t = \kappa_m(\theta_m - m_t)dt + \omega_m dW_t^{(m)}$$

**Instantaneous Variance (CIR-type):**
$$dv_{1t} = \kappa_1(\theta_1 - v_{1t})dt + \omega_1\sqrt{v_{1t}}dW_t^{(v)} + dL_{vt}$$

**Variance Shot Noise:**
$$dL_{vt} = -b_v L_{vt}dt + dJ_t^{(v)}$$

Where:
- $\theta_t = m_t + L_{vt}$ (time-varying target)
- $dW_t^{(1)}$ and $dW_t^{(v)}$ have correlation $\rho_1$
- $J_t^{(v)}$ is a compound Poisson process with exponential jump sizes

## Package Structure

```
vix-pricer/
├── Pricer/
│   ├── __init__.py                    # Package initialization
│   ├── model_config.py                # Model parameters and initial conditions
│   ├── characteristic_function.py     # Affine characteristic function solver
│   ├── fft_pricing.py                 # FFT-based option pricing
│   ├── monte_carlo.py                 # Monte Carlo simulation
│   ├── validator.py                   # Model validation framework
│   └── solvers.py                     # Numerical ODE solvers
├── pyproject.toml                     # Modern package configuration
├── setup.py                           # Legacy setup script
├── README.md                          # This file
└── LICENSE                            # MIT License
```

## Dependencies

- Python ≥ 3.8
- NumPy ≥ 1.20.0
- SciPy ≥ 1.7.0
- Pandas ≥ 1.3.0
- tqdm ≥ 4.60.0

## Development

### Installing Development Dependencies

```bash
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest tests/ -v --cov=Pricer
```

### Code Formatting

```bash
black Pricer/
flake8 Pricer/
```

## Citation

If you use this library in your research, please cite:

```bibtex
@article{fan2026vix,
  author = {Fan, Z. and Ryu, D. and Ye, Y.},
  title = {Valuation of {VIX} derivatives: Incorporating larger spikes in volatility-of-volatility dynamics},
  year = {2026},
  journal = {Working Paper}
}
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For questions and support:
- Open an issue on [GitHub](https://github.com/vixspike/vix-pricer/issues)
- Check the [documentation](https://github.com/vixspike/vix-pricer/blob/main/README.md)

## Acknowledgments

Developed by the VIX Spike VolOfVol Research Team for quantitative finance research and applications.
