optPricing 2.0.0__py3-none-any.whl

quantfin/calibration/vectorized_integration_iv.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+from scipy import integrate
+
+from quantfin.models import BSMModel
+
+if TYPE_CHECKING:
+    from quantfin.atoms import Rate
+    from quantfin.models import BaseModel
+
+
+__doc__ = """
+Defines a high-performance, vectorized solver for implied volatility using
+numerical integration of the characteristic function.
+"""
+
+
+class VectorizedIntegrationIVSolver:
+    """
+    A high-performance, vectorized Secant method solver for implied volatility
+    for any model that supports a characteristic function.
+    """
+
+    def __init__(
+        self,
+        max_iter: int = 20,
+        tolerance: float = 1e-7,
+        upper_bound: float = 200.0,
+    ):
+        """
+        Initializes the vectorized IV solver.
+
+        Parameters
+        ----------
+        max_iter : int, optional
+            Maximum number of iterations for the Secant method, by default 20.
+        tolerance : float, optional
+            Error tolerance for convergence, by default 1e-7.
+        upper_bound : float, optional
+            The upper limit for the numerical integration, by default 200.0.
+        """
+        self.max_iter = max_iter
+        self.tolerance = tolerance
+        self.upper_bound = upper_bound
+
+    def solve(
+        self,
+        target_prices: np.ndarray,
+        options: pd.DataFrame,
+        model: BaseModel,
+        rate: Rate,
+    ) -> np.ndarray:
+        """
+        Calculates implied volatility for an array of options and prices.
+
+        This method uses a vectorized Secant root-finding algorithm. The pricing
+        at each step is performed using a vectorized version of the Gil-Pelaez
+        inversion formula.
+
+        Parameters
+        ----------
+        target_prices : np.ndarray
+            An array of market prices for which to find the implied volatility.
+        options : pd.DataFrame
+            A DataFrame of option contracts.
+        model : BaseModel
+            The financial model to use for pricing.
+        rate : Rate
+            The risk-free rate structure.
+
+        Returns
+        -------
+        np.ndarray
+            An array of calculated implied volatilities.
+        """
+        iv0 = np.full_like(target_prices, 0.20)
+        iv1 = np.full_like(target_prices, 0.25)
+
+        p0 = self._price_vectorized(iv0, options, model, rate)
+        p1 = self._price_vectorized(iv1, options, model, rate)
+
+        f0 = p0 - target_prices
+        f1 = p1 - target_prices
+
+        for _ in range(self.max_iter):
+            if np.all(np.abs(f1) < self.tolerance):
+                break
+            denom = f1 - f0
+            denom[np.abs(denom) < 1e-12] = 1e-12
+            iv_next = iv1 - f1 * (iv1 - iv0) / denom
+            iv_next = np.clip(iv_next, 1e-4, 5.0)
+            iv0, iv1 = iv1, iv_next
+            f0 = f1
+            p1 = self._price_vectorized(iv1, options, model, rate)
+            f1 = p1 - target_prices
+
+        return iv1
+
+    def _price_vectorized(
+        self,
+        iv_vector: np.ndarray,
+        options: pd.DataFrame,
+        model: BaseModel,
+        rate: Rate,
+    ) -> np.ndarray:
+        """
+        Internal method to price a vector of options for a given vector of volatilities.
+        """
+        bsm_model = BSMModel(params={"sigma": 0.2})
+        prices = np.zeros_like(iv_vector)
+
+        for T, group in options.groupby("maturity"):
+            idx = group.index
+            S, K = group["spot"].values, group["strike"].values
+            q, r = group["dividend"].values, rate.get_rate(T)
+            is_call = group["optionType"].values == "call"
+
+            bsm_model.params["sigma"] = iv_vector[idx]
+            phi = bsm_model.cf(t=T, spot=S, r=r, q=q)
+            k_log = np.log(K)
+
+            integrand_p2 = lambda u: (np.exp(-1j * u * k_log) * phi(u)).imag / u
+            integrand_p1 = lambda u: (np.exp(-1j * u * k_log) * phi(u - 1j)).imag / u
+
+            integral_p2, _ = integrate.quad_vec(integrand_p2, 1e-15, self.upper_bound)
+
+            phi_minus_i = phi(-1j)
+            phi_minus_i[np.abs(phi_minus_i) < 1e-12] = 1.0
+            integral_p1, _ = integrate.quad_vec(integrand_p1, 1e-15, self.upper_bound)
+
+            P1 = 0.5 + integral_p1 / (np.pi * np.real(phi_minus_i))
+            P2 = 0.5 + integral_p2 / np.pi
+
+            call_prices = S * np.exp(-q * T) * P1 - K * np.exp(-r * T) * P2
+            put_prices = K * np.exp(-r * T) * (1 - P2) - S * np.exp(-q * T) * (1 - P1)
+
+            prices[idx] = np.where(is_call, call_prices, put_prices)
+
+        return prices

quantfin/cli.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from typing import Annotated
+
+import typer
+
+from quantfin.config import PROJECT_ROOT, _config
+from quantfin.data import (
+    get_available_snapshot_dates,
+    load_market_snapshot,
+    save_historical_returns,
+    save_market_snapshot,
+)
+from quantfin.workflows import BacktestWorkflow, DailyWorkflow
+from quantfin.workflows.configs import ALL_MODEL_CONFIGS
+
+__doc__ = """
+This module provides the command-line interface (CLI) for the quantfin library.
+
+It uses the Typer library to create a user-friendly interface for running
+calibrations, backtests, data management tasks, and launching the dashboard.
+"""
+
+# Create the main Typer application
+app = typer.Typer(
+    name="optPricing",
+    help="A quantitative finance library for option pricing and analysis.",
+    add_completion=False,
+)
+
+# Create a subcommand for data-related tasks
+data_app = typer.Typer(name="data", help="Tools for downloading and managing data.")
+app.add_typer(data_app)
+
+
+# Utility function for logging setup
+def setup_logging(verbose: bool):
+    """
+    Configures the root logger based on the verbosity flag.
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s - %(levelname)s - %(message)s",
+    )
+
+
+# CLI Commands
+
+
+@app.command()
+def dashboard():
+    """
+    Launches the Streamlit dashboard application.
+    """
+    # Note: We point directly to the source file now.
+    app_path = PROJECT_ROOT / "src" / "quantfin" / "dashboard" / "app.py"
+    typer.echo(f"Launching Streamlit dashboard from: {app_path}")
+
+    if not app_path.exists():
+        typer.secho(
+            f"Error: Dashboard entry point not found at '{app_path}'.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        subprocess.run(
+            ["streamlit", "run", str(app_path)],
+            check=True,
+        )
+    except FileNotFoundError:
+        typer.secho(
+            "Error: 'streamlit' command not found; install: "
+            "'pip install optPricing[app]'",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+
+@data_app.command(name="download")
+def download_data(
+    tickers: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--ticker",
+            "-t",
+            help="Stock ticker to download. Can be used multiple times.",
+        ),
+    ] = None,
+    all_default: Annotated[
+        bool,
+        typer.Option(
+            "--all", help="Download all default tickers specified in config.yaml."
+        ),
+    ] = False,
+    period: Annotated[
+        str,
+        typer.Option(
+            "--period",
+            "-p",
+            help="Time period for historical data (e.g., '10y', '5y').",
+        ),
+    ] = "10y",
+):
+    """
+    Downloads and saves historical log returns for specified tickers or all defaults.
+    """
+    if all_default:
+        tickers_to_download = _config.get("default_tickers", [])
+        if not tickers_to_download:
+            typer.secho(
+                "Error: --all flag used, but no 'default_tickers' found "
+                "in config.yaml.",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1)
+        typer.echo(f"Downloading all default tickers for period {period}...")
+    elif tickers:
+        tickers_to_download = tickers
+        typer.echo(
+            f"Downloading {period} historical data for tickers: "
+            f"{', '.join(tickers_to_download)}"
+        )
+    else:
+        typer.secho(
+            "Error: Please provide at least one --ticker or use the --all flag.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    save_historical_returns(tickers_to_download, period=period)
+    typer.secho("Download complete.", fg=typer.colors.GREEN)
+
+
+@app.command()
+def calibrate(
+    ticker: Annotated[
+        str,
+        typer.Option("--ticker", "-t", help="The stock ticker to calibrate against."),
+    ],
+    model: Annotated[
+        list[str],
+        typer.Option(
+            "--model", "-m", help="Model to calibrate. Can be used multiple times."
+        ),
+    ],
+    date: Annotated[
+        str | None,
+        typer.Option(
+            "--date",
+            "-d",
+            help="Snapshot date (YYYY-MM-DD). Defaults to latest available.",
+        ),
+    ] = None,
+    fix_param: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--fix",
+            help="Fix a parameter (e.g., 'sigma=0.25'). Can be used multiple times.",
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Enable detailed logging.")
+    ] = False,
+):
+    """
+    Calibrates one or more models to market data for a given ticker and date.
+
+    Saves the calibrated parameters to the 'artifacts/calibrated_params' directory.
+    """
+    setup_logging(verbose)
+
+    # --- 1. Determine the snapshot date to use ---
+    if date is None:
+        typer.echo(
+            f"No date specified for {ticker}. Finding latest available snapshot..."
+        )
+        available_dates = get_available_snapshot_dates(ticker)
+        if not available_dates:
+            typer.secho(
+                f"Error: No market data snapshots found for ticker '{ticker}'.",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1)
+        date = available_dates[0]
+        typer.echo(f"Using latest date: {date}")
+
+    # --- 2. Load the market data ---
+    market_data = load_market_snapshot(ticker, date)
+    if market_data is None:
+        typer.secho(
+            f"Error: Failed to load market data for {ticker} on {date}.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    # --- 3. Parse fixed parameters ---
+    frozen_params = {}
+    if fix_param:
+        for p in fix_param:
+            try:
+                key, value = p.split("=")
+                frozen_params[key.strip()] = float(value)
+            except ValueError:
+                typer.secho(
+                    f"Invalid format for fixed parameter: '{p}'. Use 'key=value'.",
+                    fg=typer.colors.RED,
+                )
+                raise typer.Exit(code=1)
+
+    # --- 4. Loop through and run workflow for each model ---
+    for model_name in model:
+        if model_name not in ALL_MODEL_CONFIGS:
+            typer.secho(
+                f"Warning: Model '{model_name}' not found. Skipping.",
+                fg=typer.colors.YELLOW,
+            )
+            continue
+
+        config = ALL_MODEL_CONFIGS[model_name].copy()
+        config["ticker"] = ticker
+        config["frozen"] = {**config.get("frozen", {}), **frozen_params}
+
+        workflow = DailyWorkflow(market_data, config)
+        workflow.run()
+
+        # --- 5. Display and save results ---
+        if workflow.results["Status"] == "Success":
+            typer.secho(
+                f"\nCalibration for {model_name} on {date} SUCCEEDED.",
+                fg=typer.colors.GREEN,
+            )
+            typer.echo(f"  - Final RMSE: {workflow.results['RMSE']:.6f}")
+            typer.echo(
+                f"  - Calibrated Params: {workflow.results['Calibrated Params']}"
+            )
+
+            # Save the parameters
+            params_to_save = {
+                "model": model_name,
+                "ticker": ticker,
+                "date": date,
+                "params": workflow.results["Calibrated Params"],
+            }
+            # Example filename: SPY_Heston_2023-01-01.json
+            filename = f"{ticker}_{model_name}_{date}.json"
+            save_path = PROJECT_ROOT / "artifacts" / "calibrated_params" / filename
+            with open(save_path, "w") as f:
+                json.dump(params_to_save, f, indent=4)
+            typer.echo(f"  - Saved parameters to: {save_path}")
+
+        else:
+            typer.secho(
+                f"\nCalibration for {model_name} on {date} FAILED.", fg=typer.colors.RED
+            )
+            typer.echo(f"  - Error: {workflow.results.get('Error', 'Unknown error')}")
+
+
+@app.command()
+def backtest(
+    ticker: Annotated[
+        str, typer.Option("--ticker", "-t", help="The stock ticker to backtest.")
+    ],
+    model: Annotated[
+        str, typer.Option("--model", "-m", help="The single model to backtest.")
+    ],
+    # Other options like start/end date, fixed params can be added here
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Enable detailed logging.")
+    ] = False,
+):
+    """
+    Runs a historical backtest for a given model and ticker.
+    """
+    setup_logging(verbose)
+
+    if model not in ALL_MODEL_CONFIGS:
+        typer.secho(
+            "Error: Model "
+            f"'{model}' not found. Available models: "
+            f"{list(ALL_MODEL_CONFIGS.keys())}",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    config = ALL_MODEL_CONFIGS[model].copy()
+    config["ticker"] = ticker
+
+    workflow = BacktestWorkflow(ticker, config)
+    workflow.run()
+    workflow.save_results()
+
+
+@app.command()
+def demo(
+    model_name: Annotated[
+        str | None,
+        typer.Argument(help="Run a demo for a specific model name."),
+    ] = None,
+):
+    """
+    Runs a benchmark demo to showcase model and technique performance.
+
+    If a model name is provided (e.g., 'BSM'), it runs only that benchmark.
+    Otherwise, it runs the full suite.
+    """
+    benchmark_script_path = PROJECT_ROOT / "demo" / "benchmark.py"
+    typer.echo(f"Executing benchmark demo from: {benchmark_script_path}")
+
+    command_to_run = ["python", str(benchmark_script_path)]
+    if model_name:
+        command_to_run.append(model_name)
+
+    try:
+        subprocess.run(command_to_run, check=True)
+    except FileNotFoundError:
+        typer.secho(
+            f"Error: Demo script not found at '{benchmark_script_path}'.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+
+@data_app.command(name="snapshot")
+def save_snapshot(
+    tickers: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--ticker",
+            "-t",
+            help="Stock ticker to snapshot. Can be used multiple times.",
+        ),
+    ] = None,
+    all_default: Annotated[
+        bool,
+        typer.Option(
+            "--all", help="Snapshot all default tickers specified in config.yaml."
+        ),
+    ] = False,
+):
+    """
+    Fetches and saves a live market data snapshot for specified tickers.
+
+    The data provider (yfinance or polygon) is determined by your config.yaml file.
+    """
+    if all_default:
+        tickers_to_download = _config.get("default_tickers", [])
+        if not tickers_to_download:
+            typer.secho(
+                "Error: --all flag used, but no 'default_tickers' in config.yaml.",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1)
+        typer.echo("Saving live market snapshots for all default tickers...")
+    elif tickers:
+        tickers_to_download = tickers
+        typer.echo(
+            f"Saving live market snapshots; tickers: {', '.join(tickers_to_download)}"
+        )
+    else:
+        typer.secho(
+            "Error: Please provide at least one --ticker or use the --all flag.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    save_market_snapshot(tickers_to_download)
+    typer.secho("Snapshot complete.", fg=typer.colors.GREEN)

quantfin/config.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+CONFIG_FILE_PATH = PROJECT_ROOT / "config.yaml"
+
+if not CONFIG_FILE_PATH.exists():
+    print(f"Config file not found. Creating default config.yaml at {CONFIG_FILE_PATH}")
+    default_config = {
+        "polygon_api_key": "YOUR_POLYGON_API_KEY_HERE",
+        "live_data_provider": "yfinance",
+        "data_directory": "data",
+        "artifacts_directory": "artifacts",
+    }
+    with open(CONFIG_FILE_PATH, "w") as f:
+        yaml.dump(
+            default_config,
+            f,
+            default_flow_style=False,
+            sort_keys=False,
+        )
+
+with open(CONFIG_FILE_PATH) as f:
+    _config = yaml.safe_load(f) or {}
+
+# API Key Management
+POLYGON_API_KEY = os.environ.get("POLYGON_API_KEY", _config.get("polygon_api_key"))
+
+# Directory Management
+DATA_DIR = PROJECT_ROOT / _config.get("data_directory", "data")
+ARTIFACTS_DIR = PROJECT_ROOT / _config.get("artifacts_directory", "artifacts")
+
+# Input Data Directories
+MARKET_SNAPSHOT_DIR = DATA_DIR / "market_data_snapshots"
+HISTORICAL_DIR = DATA_DIR / "historical_data"
+
+# Output Artifact Directories
+BACKTEST_LOGS_DIR = ARTIFACTS_DIR / "backtest_logs"
+CALIBRATED_PARAMS_DIR = ARTIFACTS_DIR / "calibrated_params"
+CALIBRATION_LOGS_DIR = ARTIFACTS_DIR / "calibration_logs"
+
+# Ensure all directories exist
+ALL_DIRS = [
+    DATA_DIR,
+    ARTIFACTS_DIR,
+    MARKET_SNAPSHOT_DIR,
+    HISTORICAL_DIR,
+    BACKTEST_LOGS_DIR,
+    CALIBRATED_PARAMS_DIR,
+    CALIBRATION_LOGS_DIR,
+]
+for path in ALL_DIRS:
+    path.mkdir(parents=True, exist_ok=True)

quantfin/dashboard/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+__doc__ = """
+This package contains all components for the Streamlit dashboard UI,
+including the main service layer, plotting functions, and UI widgets.
+"""
+
+from .service import DashboardService
+from .widgets import render_parity_analysis_widget
+
+__all__ = [
+    "DashboardService",
+    "render_parity_analysis_widget",
+]

quantfin/dashboard/app.py

@@ -0,0 +1,26 @@
+import streamlit as st
+
+st.set_page_config(
+    page_title="QuantFin Library Showcase",
+    layout="wide",
+)
+
+st.title("Welcome to the QuantFin Library Showcase!")
+st.sidebar.success("Select a tool above to begin.")
+
+# ruff: noqa: E501
+st.markdown(
+    """
+    This application is a showcase for a comprehensive, high-performance
+    quantitative finance library built in Python.
+
+    **Select a tool from the sidebar** to see different features in action:
+
+    - **Calibration:** Calibrate models to market data and visualize the results.
+    - **Pricer and Greeks:** An interactive tool to price options with any model/technique and see the effect of changing parameters.
+    - **Financial Tools:** Utilities for pricing interest rate derivatives and analyzing put-call parity.
+
+    This entire application is built on a robust, library with a focus
+    on speed, accuracy, and extensibility.
+    """
+)

quantfin/dashboard/pages/1_Calibration.py

@@ -0,0 +1,57 @@
+import streamlit as st
+
+from quantfin.config import _config
+from quantfin.dashboard.service import DashboardService
+from quantfin.data import get_available_snapshot_dates
+from quantfin.workflows.configs import ALL_MODEL_CONFIGS
+
+st.set_page_config(layout="wide", page_title="QuantFin | Calibration")
+st.title("Model Calibration & IV Surface Analysis")
+st.caption(
+    "Calibrate models to market data and visualize the resulting volatility smiles."
+)
+AVAILABLE_TICKERS = _config.get("default_tickers", ["SPY", "AAPL"])
+
+with st.sidebar:
+    st.header("Configuration")
+    ticker = st.selectbox("Ticker", AVAILABLE_TICKERS)
+    data_source_options = get_available_snapshot_dates(ticker)
+    snapshot_date = st.selectbox("Snapshot Date", data_source_options)
+    model_selection = st.multiselect(
+        "Select Models to Calibrate",
+        list(ALL_MODEL_CONFIGS.keys()),
+        default=["Merton"],
+    )
+    run_button = st.button("Run Calibration Analysis")
+
+if run_button:
+    selected_configs = {name: ALL_MODEL_CONFIGS[name] for name in model_selection}
+    with st.spinner("Initializing analysis..."):
+        service = DashboardService(ticker, snapshot_date, selected_configs)
+        try:
+            service.run_calibrations()
+            smile_fig, surface_fig = service.get_iv_plots()
+            st.session_state.service = service
+            st.session_state.smile_fig = smile_fig
+            st.session_state.surface_fig = surface_fig
+        except Exception as e:
+            st.error(f"An error occurred during analysis: {e}")
+            if "service" in st.session_state:
+                del st.session_state.service
+
+if "service" in st.session_state:
+    service = st.session_state.service
+    st.header(f"Analysis for {service.ticker} on {service.snapshot_date}")
+    st.subheader("Calibration Summary")
+    if service.summary_df is not None:
+        st.dataframe(service.summary_df)
+    else:
+        st.error("Calibration failed for all selected models.")
+
+    if "smile_fig" in st.session_state:
+        st.subheader("Volatility Smile Visualization")
+        st.pyplot(st.session_state.smile_fig)
+        st.subheader("Implied Volatility Surface (3D)")
+        st.plotly_chart(st.session_state.surface_fig, use_container_width=True)
+else:
+    st.info("Select parameters and click 'Run Analysis' in the sidebar to begin.")