Metadata-Version: 2.4
Name: vanilla-option-pricers
Version: 1.3.0
Summary: Fast and vectorised pricer and implied volatility fitters for Black-Scholes and Bachelier models
Author-email: Artur Sepp <artursepp@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ArturSepp/VanillaOptionPricers
Project-URL: Repository, https://github.com/ArturSepp/VanillaOptionPricers.git
Project-URL: Issues, https://github.com/ArturSepp/VanillaOptionPricers/issues
Keywords: option pricing,black-scholes,implied volatility,vanilla options,quantitative finance,numba
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# VanillaOptionPricers (`vanilla-option-pricers`)

**Fast and vectorized option pricers and implied volatility fitters for Black-Scholes-Merton and Bachelier models**

[![PyPI](https://img.shields.io/pypi/v/vanilla-option-pricers?style=flat-square)](https://pypi.org/project/vanilla-option-pricers/)
[![Python](https://img.shields.io/pypi/pyversions/vanilla-option-pricers?style=flat-square)](https://pypi.org/project/vanilla-option-pricers/)
[![License](https://img.shields.io/github/license/ArturSepp/VanillaOptionPricers.svg?style=flat-square)](https://github.com/ArturSepp/VanillaOptionPricers/blob/main/LICENSE.txt)
[![CI](https://github.com/ArturSepp/VanillaOptionPricers/actions/workflows/ci.yml/badge.svg)](https://github.com/ArturSepp/VanillaOptionPricers/actions)
[![Downloads](https://static.pepy.tech/badge/vanilla-option-pricers)](https://pepy.tech/project/vanilla-option-pricers)
[![Monthly](https://static.pepy.tech/badge/vanilla-option-pricers/month)](https://pepy.tech/project/vanilla-option-pricers)

## Why vanilla-option-pricers

Research pipelines rarely need a derivatives library — they need Black-Scholes-Merton and Bachelier prices and implied volatilities for large arrays of strikes, expiries, and underlyings, fast enough to sit inside a calibration loop, a surface fitter, or a Monte Carlo post-processor. Full pricing frameworks deliver this behind heavy dependency trees and object hierarchies; textbook scipy implementations deliver it one option at a time. `vanilla-option-pricers` implements just the closed forms, JIT-compiled and vectorised with Numba over numpy arrays, with two runtime dependencies.

## What makes it different

- **Log-normal and normal models side by side.** Black-Scholes-Merton for equities and FX; Bachelier normal quoting for rates and spread underlyings where negative forwards and normal vols are the market convention.
- **Implied volatility as a first-class fitter.** Vectorised IV inversion designed for full option chains rather than scalar root-finding in a loop.
- **Inverse options.** Coin-denominated inverse calls and puts (`'IC'`/`'IP'`) as traded on cryptocurrency derivatives exchanges — a payoff type largely absent from standard open-source pricers; see Lucic, V. and Sepp, A. (2024), *Valuation and Hedging of Cryptocurrency Inverse Options*, Quantitative Finance, 24(7), 851–869, for the theory.
- **Two dependencies.** numpy and numba. No object hierarchy, no calendar machinery — every function takes arrays in and returns arrays out.

## When to use it — and when not

Use `vanilla-option-pricers` when you need array-valued vanilla prices and implied vols at speed inside research code: option-chain snapshots, vol-surface preprocessing, simulation post-processing, or calibration objectives.

It is deliberately not a derivatives framework: no American or exotic payoffs, no term structures, no settlement conventions, and no stochastic volatility. For pricing and calibration under stochastic volatility, use [`stochvolmodels`](https://github.com/ArturSepp/StochVolModels); for portfolio-level analytics and reporting, use [`qis`](https://github.com/ArturSepp/QuantInvestStrats).

## Installation

### PyPI Installation
```bash
pip install vanilla-option-pricers
```

### Upgrade to Latest Version
```bash
pip install --upgrade vanilla-option-pricers
```

## Requirements

### Core Dependencies
- `python >= 3.10`
- `numba >= 0.60.0`
- `numpy >= 2.0`

The two runtime dependencies are numpy and numba. There is no dependency on any higher-level analytics package.

## Supported Option Types

VanillaOptionPricers supports the following option types (passed as string parameters):

| Option Type | String Code | Description |
|-------------|-------------|-------------|
| Call | `'C'` | Standard call option |
| Put | `'P'` | Standard put option |
| Inverse Call | `'IC'` | Inverse call option |
| Inverse Put | `'IP'` | Inverse put option |

## Quick Start

### Basic Option Pricing

Pricers are parametrised on the forward, not the spot: `forward = spot * exp((r - q) * ttm)`, and `discfactor = exp(-r * ttm)` discounts the forward-measure payoff to today.

```python
import numpy as np
from vanilla_option_pricers import (
    compute_bsm_vanilla_price,
    compute_bsm_vanilla_delta,
    compute_bsm_vanilla_theta_vector,
    infer_bsm_implied_vol,
)

spot = 100.0
strike = 105.0
ttm = 0.25             # time to maturity, in years
vol = 0.20             # annualised lognormal vol
rate = 0.05            # continuously compounded rate
forward = spot * np.exp(rate * ttm)
discfactor = np.exp(-rate * ttm)

price = compute_bsm_vanilla_price(forward=forward,
                                  strike=strike,
                                  ttm=ttm,
                                  vol=vol,
                                  optiontype='C',
                                  discfactor=discfactor)
delta = compute_bsm_vanilla_delta(ttm=ttm, forward=forward, strike=strike, vol=vol, optiontype='C')

# invert the price back to an implied vol (round-trips to `vol`)
implied_vol = infer_bsm_implied_vol(forward=forward,
                                    ttm=ttm,
                                    strike=strike,
                                    given_price=price,
                                    discfactor=discfactor,
                                    optiontype='C')

print(f"price={price:.4f}  delta={delta:.4f}  implied_vol={implied_vol:.4f}")
```

### Vectorized Calculations

```python
import numpy as np
from vanilla_option_pricers import compute_bsm_vanilla_price_vector

# Vectorized pricing for multiple strikes
forwards = np.array([95, 100, 105, 110])
strikes = np.array([100, 100, 100, 100])
vols = np.array([0.15, 0.20, 0.25, 0.30])

option_prices = compute_bsm_vanilla_price_vector(
    forward=forwards,
    strike=strikes,
    ttm=0.25,
    vol=vols,
    optiontype='C'
)

print("Vectorized Option Prices:", option_prices)
```


## Performance Benefits

VanillaOptionPricers leverages Numba's JIT compilation to achieve:

- **Vectorization**: Process arrays of parameters efficiently
- **Speed**: Orders of magnitude faster than pure Python implementations
- **Memory Efficiency**: Optimized memory usage for large-scale calculations
- **Numerical Stability**: Robust implementations with proper handling of edge cases

## Use Cases

VanillaOptionPricers is ideal for:

- **Quantitative Research**: Academic research requiring fast option pricing
- **Trading Systems**: Real-time option pricing in trading applications
- **Risk Management**: Portfolio risk calculations and scenario analysis
- **Market Making**: High-frequency option pricing and implied volatility calculations
- **Financial Education**: Teaching option pricing concepts with efficient implementations

## Ecosystem

This package is part of an open-source Python stack for quantitative finance — full catalogue at [github.com/ArturSepp](https://github.com/ArturSepp):

| Package | Purpose |
|---|---|
| [`qis`](https://github.com/ArturSepp/QuantInvestStrats) | Performance analytics, factsheets, and visualisation |
| [`optimalportfolios`](https://github.com/ArturSepp/OptimalPortfolios) | Portfolio construction and backtesting |
| [`factorlasso`](https://github.com/ArturSepp/factorlasso) | Sparse factor models and factor covariance estimation |
| [`bbg-fetch`](https://github.com/ArturSepp/BloombergFetch) | Bloomberg data fetching |
| [`trendfollowing`](https://github.com/ArturSepp/TrendFollowingSystems) | Trend-following systems: closed-form theory and replication |
| [`goal-based-allocation`](https://github.com/ArturSepp/GoalBasedAllocation) | Dynamic MV allocation under regime-switching jump-diffusions |
| [`stochvolmodels`](https://github.com/ArturSepp/StochVolModels) | Stochastic volatility pricing analytics |
| [`vanilla-option-pricers`](https://github.com/ArturSepp/VanillaOptionPricers) *(this package)* | Vectorised vanilla option pricers and implied volatility fitters |

Dependency links within the stack: `optimalportfolios` builds on `qis` and `factorlasso`; `trendfollowing` builds on `qis`.

## Contributing

We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.

### Development Setup

```bash
git clone https://github.com/ArturSepp/VanillaOptionPricers.git
cd VanillaOptionPricers
pip install -e .
```

## License

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

## Citation

If you use VanillaOptionPricers in your research, please cite it as:

```bibtex
@software{sepp2024vanillaoptionpricers,
  title={VanillaOptionPricers: Fast and vectorized option pricers and implied volatility fitters for Black-Scholes and Merton models},
  author={Sepp, Artur},
  year={2024},
  url={https://github.com/ArturSepp/VanillaOptionPricers},
  note={Python package for high-performance option pricing}
}
```
