deep-quant-lib 0.2.5

A signature-based primal-dual engine for pricing American options.

DeepQuant: An Adaptive Deep Learning Library for Quantitative Finance ⚖️

DeepQuant is a modern, high-performance Python library for pricing American options under advanced stochastic volatility models. It combines state-of-the-art techniques from deep learning and rough path theory to provide accurate, reliable price bounds for complex derivatives.

In-Depth Documentation 📚

For a deeper dive into the methodologies and advanced usage of the library, please refer to the following documents:

• Base Theory: SDEs and Path Signatures: The technical details motivating much of the library's foundations.

• Neural Network Solvers: The technical details driving the implementation of the neural network and kernel solvers.

• Challenges & Enhancements: The technical details describing how challenges were uncovered and how enhancements were made to solve them.

• Advanced Usage and Examples: Details other advanced usages of the library beyond what the ElementaryPricingWorkflow provides.

Installation ⚙️

For Users

⚠️ Important: PyTorch Dependency

This package depends on PyTorch. Due to the way PyTorch is built for different hardware (NVIDIA GPUs, Apple Silicon, etc.), you must install PyTorch manually before installing deepquant.

If you try to install deepquant directly, pip may install a version of PyTorch that is incompatible with your system or with deepquant's other dependencies, which can cause low-level crashes (like a SIGSEGV error).

Please follow the guide for your preferred package manager.

---

Option 1: Mamba / Conda (Recommended)

This is the safest and most reliable method. It ensures all your packages (PyTorch, NumPy, etc.) are 100% binary-compatible.

1. Create a new, strict environment. This command creates a new environment, sets conda-forge as the only source, and installs Python.

   mamba create -n deepquant-env -c conda-forge --strict-channel-priority python=3.10
   

2. Activate the environment.

   mamba activate deepquant-env
   

3. Install PyTorch Install all your complex binary packages from conda-forge first.

   mamba install pytorch -c pytorch
   

4. Install deepquant (forcing a source build). This final step uses pip to install our package, but the --no-binary :all: flag forces it to compile against the PyTorch you just installed, guaranteeing compatibility.

   pip install deep-quant-lib
   

---

Option 2: pip and venv

This method works, but you must be careful to install the correct PyTorch build.

1. Create and activate a virtual environment.

   python -m venv venv
   source venv/bin/activate  # On macOS/Linux
   .\venv\Scripts\activate   # On Windows
   

2. Install PyTorch FIRST. Go to the Official PyTorch Website and select the correct command for your system (macOS, Linux, Windows) and hardware (CPU, NVIDIA CUDA, Apple MPS).

   For example, for a Mac with an M2 chip, you would run:

   pip install torch
   

   For a Linux machine with CUDA 12.1, you would run:

   pip install torch --index-url [https://download.pytorch.org/whl/cu121](https://download.pytorch.org/whl/cu121)
   

3. Install deepquant. Once PyTorch is successfully installed, you can safely install deepquant.

   pip install deep-quant-lib
   

DeepQuant is available on PyPI and can be installed with pip:

pip install deep-quant-lib

For Developers

If you wish to contribute to the project, you can clone the repository and install it in editable mode:

git clone [https://github.com/your_username/deep-quant.git](https://github.com/your_username/deep-quant.git)
cd deep-quant
pip install -e .

Usage 🚀

Here are two examples demonstrating how to use the deepquant library.

Quick Start: Simple Example

This example shows the simplest way to price a 1-year, at-the-money put option on Apple (AAPL). The workflow uses sensible, heuristically chosen defaults for the simulation parameters (num_paths and num_steps).

# examples/simple_price.py
import yfinance as yf
import pandas as pd
from pathlib import Path
from deepquant.data.loader import YFinanceLoader
from deepquant.workflows.elemtary_pricing_workflow import ElementaryPricingWorkflow

# --- 1. Setup ---
asset_ticker = 'AAPL'
try:
    latest_price = yf.Ticker(asset_ticker).history(period='1d')['Close'][0]
except IndexError:
    print(f"Could not fetch price for {asset_ticker}. Exiting.")
    exit()

strike_price = round(latest_price) # At-the-money

# --- 2. Price the Option ---
# Instantiate the data loader and the main workflow.
data_loader = YFinanceLoader(ticker=asset_ticker)
workflow = ElementaryPricingWorkflow(
    data_loader=data_loader,
    models_dir=Path.cwd() / "models",
    risk_free_rate=0.05
)

# Run the pricing process using default simulation parameters.
price_info, engine_results = workflow.price_option(
    strike=strike_price,
    maturity=252, # 1 year in trading days
    option_type='put',
    
    # Defines within what monetary range the primal's price must be.
    primal_uncertainty=0.05 
    # Since the primal must be computed on a stochastic process,
    # there is uncertainty on each primal computation. The process
    # will generate paths and run the primal until the mean is within
    # a 95% confidence interval of width 2 * primal_uncertainty.
    # 
    # For example, if the deduced option price is $2.05, and primal-uncertainty is $0.05,
    # the process will stop once the deduced price's 95%-confidence interval has shrunk to ($2, $2.10).
)

# --- 3. Display Results ---
results = {"Asset": asset_ticker, "Spot Price": latest_price, **price_info, **engine_results}
print("\n--- FINAL PRICING RESULT ---")
print(pd.Series(results).to_string())

Advanced Usage: Backtesting and Full Configuration

This example showcases the full power of the library for a research use case. We will price a 1-year put option on the S&P 500 (^GSPC) as if we were on January 3rd, 2023. We will force the use of the rough Bergomi model and override the default simulation parameters for a high-fidelity run.

# examples/advanced_backtest.py
import yfinance as yf
import pandas as pd
from pathlib import Path
from deepquant.data.loader import YFinanceLoader
from deepquant.workflows.elemtary_pricing_workflow import ElementaryPricingWorkflow

# --- 1. Setup ---
asset_ticker = 'SPY'
evaluation_date = '2023-01-03'
maturity_date = '2024-01-03'

try:
    spot_price = yf.Ticker(asset_ticker).history(start=evaluation_date, end='2023-01-04')['Close'][0]
except IndexError:
    print(f"Could not fetch price for {asset_ticker} on {evaluation_date}. Exiting.")
    exit()

strike_price = round(spot_price / 50) * 50

# --- 2. Price the Option with Advanced Configuration ---
data_loader = YFinanceLoader(ticker=asset_ticker, end_date=evaluation_date)

workflow = ElementaryPricingWorkflow(
    data_loader=data_loader,
    models_dir=Path.cwd() / "models",
    risk_free_rate=0.05,
    retrain_hurst_interval_days=30,

    force_model='bergomi', # Override the forecast and force the rough model
    bergomi_static_params = { 'H': 0.4, "eta": 1.9, "rho": -0.9 } # Override the bergomi simulation parameters.
)

# Run the pricing process with custom, high-fidelity simulation parameters.
price_info, engine_results = workflow.price_option(
    strike=strike_price,
    maturity=maturity_date,
    option_type='put',
    primal_uncertainty=0.8,

    exchange='NYSE',        # <-- Specify the exchange for which the asset is traded.
    evaluation_date=evaluation_date,

    max_num_paths=300,       # <-- Specify the number of volatility paths to compute.
    max_num_steps=5000,      # <-- Specify the number of steps each volatility path should take.
    # Reduce these paramters in order to reduce resource usage.

    # Note: Smaller values may mean that the primal process will have to run for longer in order to
    # obtain a sufficiently small primal uncertainty on the confidence interval. It may also
    # induce significant bias (ie: miss-pricing the deduced price). Use with caution
)

# --- 3. Display Results ---
results = {"Asset": asset_ticker, "Spot Price": spot_price, **price_info, **engine_results}
print("\n--- FINAL PRICING RESULT (Advanced Backtest) ---")
print(pd.Series(results).to_string())

License ©️

This project is licensed under the MIT License - see the LICENSE file for details.