optPricing 2.4.0__tar.gz → 2.6.0__tar.gz

optpricing-2.6.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions come from git tags
+(`vX.Y.Z`) via setuptools_scm.
+
+## [Unreleased]
+
+### Performance
+
+- Monte Carlo engine rebuilt: the numba kernels draw their own random numbers from per-chunk
+  `numpy.random.Generator`s (spawned from one seed, fixed chunk size) and run concurrently on a thread pool
+  (`n_jobs`, `chunk_size` options; `OPTPRICING_MC_THREADS`). Results depend only on the seed and chunk size,
+  common-random-number Greeks are preserved, and jump sizes now come from the seeded stream. 100k-path
+  BSM 27.7 → 3.4 ms, Heston (Euler) 88.7 → 7.5 ms on 10 cores.
+- Heston/Bates Monte Carlo defaults to Andersen's Quadratic-Exponential variance scheme with martingale
+  correction (`variance_scheme="qe"`; `"euler"` keeps full truncation). 20 QE steps are more accurate than
+  252 Euler steps; on long-dated, high vol-of-vol parameters Euler was off by several price units.
+- Closed forms use `scipy.special.ndtr` (BSM price 28 → 2 µs); the Merton series is vectorised with log-space
+  Poisson weights (2.7 ms → 14 µs, no overflow past 170 terms).
+- `IntegrationTechnique` evaluates the Gil–Pelaez integrals on a cached composite Gauss–Legendre rule
+  (`method="gauss"`, 0.69 → 0.07 ms; `method="quad"` keeps the adaptive rule); the calibration chain pricer
+  uses the same rule (400 options 19.5 → 1.7 ms). `FFTTechnique` interpolates cubically and defaults to
+  `eta=0.125` (ATM error 5e-4 → 1e-6 at the same cost).
+- Longstaff–Schwartz: parallel power-sum regression on moneyness, time-major path matrices
+  (20k paths 32 → 13 ms); Crank–Nicolson PDE marches in numba with the two constant matrices factorised once
+  (200×200 grid 2.3 → 0.3 ms).
+- Kernel signatures changed: SDE kernels take `(gen, n_paths, n_steps, antithetic, ...)`, path kernels return
+  `(n_steps + 1, n_paths)` arrays, and `longstaff_schwartz_pricer` takes `n_threads`.
+
+### Changed
+
+- Python 3.10 support dropped (end of life); supported versions are 3.11–3.14, with 3.15 tested as experimental.
+- Dependency pins relaxed from `~=` to verified minimum versions (`numpy>=2.3.2`, `scipy>=1.16.1`, `pandas>=2.3.3`, `numba>=0.63`, `pyyaml>=6.0.3`, `typer>=0.15.3`, `yfinance>=0.2.63`). Current releases (numpy 2.5, pandas 3.1, numba 0.68, yfinance 1.x) are supported.
+- Streamlit and Plotly moved to the optional `ui` extra: `pip install "optpricing[ui]"` for the dashboard.
+- Development tooling moved from the `dev` extra to PEP 735 dependency groups (`uv sync`; `pip install -e . --group dev`).
+- Package metadata uses a PEP 639 license expression; the source distribution no longer bundles `data/`, `artifacts/` or docs (24 MB → ~0.1 MB).
+- CI rebuilt on uv: lint, Python 3.11–3.15 matrix, minimum-dependency-versions job, build/twine checks; docs and publish workflows split into build and deploy jobs with hash-pinned actions.
+
+### Removed
+
+- Unused runtime dependencies `matplotlib`, `tabulate` and the explicit `click` pin (Click arrives via Typer).
+
+### Fixed
+
+- `test_price_command` relied on a hard-coded maturity date that is now in the past.
+- **European Monte Carlo for Heston, Bates, SABR and SABR-jump applied the spot/variance correlation twice** (once in `MonteCarloTechnique`, once in the kernels), biasing prices by up to 2 % at ρ = −0.7. Heston MC now agrees with QuantLib's analytic engine within Monte Carlo error.
+- NIG exact sampler drew the inverse-Gaussian subordinator with shape 1 instead of (δT)²; prices were ~3 % low.
+- CEV exact sampler used an incorrect noncentral-χ² parametrisation (terminal mean 100.6 for a forward of 105.1), ignored the dividend yield and the seeded generator, and divided by zero at r = 0. It now samples the absorbed squared-Bessel law exactly (Makarov & Glew 2010) and matches the Cox/Schroder closed form.
+- CGMY: the Lévy exponent was singular at Y = 0 and Y = 1 (Γ(−Y) poles) and the only Monte Carlo path was guarded on Y = 1 while implementing the Y = 0 law. Both limits are closed-form now; other Y sample by characteristic-function inversion.
+- Hyperbolic model: characteristic function was neither the Lévy-process law nor the horizon-T hyperbolic law (so the drift was not a martingale correction for T ≠ 1), and the sampler passed α, β where scipy expects αδ, βδ. It is now the hyperbolic Lévy motion (φₜ = φ₁ᵗ) with exact sampling at T = 1 and CF inversion otherwise.
+- PDE (Crank–Nicolson) Greeks were read at the grid node below the spot (delta off by ≈ 0.02); the spot now sits on a node, boundary values track the time level (with the dividend discount), and a Rannacher start-up is used.
+- Longstaff–Schwartz regressed on raw powers of S through an explicit inverse of XᵀX (ill-conditioned beyond degree 2) and swallowed failures with a bare `except`; it now uses moneyness-scaled regressors and least squares.
+- SABR kernels could leave the spot negative after a large down-move (puts paid more than the strike); zero is absorbing for 0 < β < 1.
+- Parameter validation now rejects parameter sets without a risk-neutral measure: Kou η₁ ≤ 1, VG θν + σ²ν/2 ≥ 1, NIG/Hyperbolic |β+1| ≥ α, CGMY M ≤ 1.
+- `optpricing.config` no longer writes `config.yaml` and data directories at import time (previously into `site-packages/lib` for installed packages); the root is `$OPTPRICING_HOME` or the working directory and folders are created when first written to.
+- Heston and Bates read `v0` from the model parameters when it is not passed as a pricing kwarg.
+- Feller-condition messages are `UserWarning`s instead of prints; pandas 3 (`inplace`, `Timestamp.utcnow`) and `importlib.resources.path` deprecations removed; `fastmath` dropped from the numba kernels (≤ 5 % measured cost, bit-identical results).
+
+- SABR is now the four-parameter model of Hagan et al. (2002) on the forward: `alpha` is the initial volatility and the new `nu` the volatility of volatility (previously `alpha` played both roles). The old three-parameter form is still accepted with a `DeprecationWarning` (`nu = alpha`). Monte Carlo simulates the forward dynamics (prices move by O((r−q)T(1−β)) relative to the old spot-with-drift kernel) and the SABR kernels' `alpha` argument is renamed `nu`.
+- Heston and Bates default parameters now satisfy the Feller condition (`vol_of_vol` 0.5 → 0.3).
+
+### Added
+
+- `SABRModel.implied_volatility` (Hagan's lognormal expansion, bit-identical to QuantLib's `sabrVolatility`), an optional `shift` parameter for shifted SABR, and a Black-76 closed form so `ClosedFormTechnique`, the CLI and calibration price SABR analytically.
+- `benchmarks/run_benchmarks.py` with recorded before/after results, and a reference-value test suite (`tests/correctness/`) pinned to QuantLib 1.44 and textbook closed forms.
+
+## [2.0.0] - 2025-06-26
+
+### Added
+
+- Shipped to PyPI `pyproject.toml`

{optpricing-2.4.0/src/optpricing.egg-info → optpricing-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optpricing
-Version: 2.4.0
+Version: 2.6.0
 Summary: A financial options pricing and analysis library.
 Author: Diljit Singh
 License-Expression: MIT

optpricing-2.6.0/benchmarks/run_benchmarks.py

@@ -0,0 +1,184 @@
+"""Micro-benchmarks for the core pricing paths.
+
+Usage (from the repository root)::
+
+    uv run python benchmarks/run_benchmarks.py                # print table
+    uv run python benchmarks/run_benchmarks.py --out results/x.json
+    uv run python benchmarks/run_benchmarks.py --repeats 9 --only mc_heston_100k
+
+Each case is warmed up once (numba compilation, caches) and then timed
+``repeats`` times; the median and minimum wall-clock times are reported.
+Numbers are only comparable on the same machine, so results files record the
+platform, interpreter and library versions alongside the git revision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import statistics
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+
+import numba
+import numpy as np
+import scipy
+
+from optpricing import BSMModel, HestonModel, Option, OptionType, Rate, Stock
+from optpricing.techniques import (
+    AmericanMonteCarloTechnique,
+    ClosedFormTechnique,
+    FFTTechnique,
+    IntegrationTechnique,
+    MonteCarloTechnique,
+    PDETechnique,
+)
+
+OPTION = Option(strike=100.0, maturity=1.0, option_type=OptionType.CALL)
+PUT = Option(strike=100.0, maturity=1.0, option_type=OptionType.PUT)
+STOCK = Stock(spot=100.0, dividend=0.01)
+RATE = Rate(rate=0.05)
+BSM = BSMModel(params={"sigma": 0.2})
+HESTON = HestonModel(
+    params={"v0": 0.04, "kappa": 2.0, "theta": 0.05, "rho": -0.7, "vol_of_vol": 0.5}
+)
+
+
+def _bsm_closed_form() -> float:
+    tech = ClosedFormTechnique()
+    for _ in range(1000):
+        p = tech.price(OPTION, STOCK, BSM, RATE).price
+    return p
+
+
+def _heston_fft() -> float:
+    return FFTTechnique().price(OPTION, STOCK, HESTON, RATE, v0=0.04).price
+
+
+def _heston_integration() -> float:
+    return IntegrationTechnique().price(OPTION, STOCK, HESTON, RATE, v0=0.04).price
+
+
+def _cn_pde() -> float:
+    return PDETechnique(M=200, N=200).price(OPTION, STOCK, BSM, RATE).price
+
+
+def _mc_bsm_100k() -> float:
+    mc = MonteCarloTechnique(n_paths=100_000, n_steps=100, seed=1)
+    return mc.price(OPTION, STOCK, BSM, RATE).price
+
+
+def _mc_heston_100k() -> float:
+    mc = MonteCarloTechnique(n_paths=100_000, n_steps=100, seed=1)
+    return mc.price(OPTION, STOCK, HESTON, RATE, v0=0.04).price
+
+
+def _lsmc_bsm_20k() -> float:
+    amc = AmericanMonteCarloTechnique(n_paths=20_000, n_steps=50, seed=1)
+    return amc.price(PUT, STOCK, BSM, RATE).price
+
+
+def _heston_chain_400() -> float:
+    import pandas as pd
+
+    from optpricing.calibration.vectorized_pricer import price_options_vectorized
+
+    chain = pd.DataFrame(
+        [
+            {"strike": k, "maturity": t, "optionType": typ}
+            for t in (0.1, 0.25, 0.5, 1.0, 2.0)
+            for k in np.linspace(60, 150, 40)
+            for typ in ("call", "put")
+        ]
+    )
+    return float(price_options_vectorized(chain, STOCK, HESTON, RATE, v0=0.04).sum())
+
+
+CASES: dict[str, tuple[Callable[[], float], str]] = {
+    "bsm_closed_form_x1000": (_bsm_closed_form, "1000 closed-form BSM prices"),
+    "heston_fft": (_heston_fft, "Carr-Madan FFT, N=4096"),
+    "heston_integration": (_heston_integration, "Gil-Pelaez quadrature"),
+    "cn_pde_200x200": (_cn_pde, "Crank-Nicolson, 200 x 200 grid"),
+    "mc_bsm_100k": (_mc_bsm_100k, "100k paths x 100 steps, antithetic"),
+    "mc_heston_100k": (_mc_heston_100k, "100k paths x 100 steps, antithetic"),
+    "lsmc_bsm_20k": (_lsmc_bsm_20k, "Longstaff-Schwartz, 20k paths x 50 steps"),
+    "heston_chain_400": (
+        _heston_chain_400,
+        "vectorised chain pricer, 400 options x 5 maturities",
+    ),
+}
+
+
+def _git_rev() -> str:
+    try:
+        rev = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        dirty = subprocess.run(
+            ["git", "status", "--porcelain"], capture_output=True, text=True, check=True
+        ).stdout.strip()
+        return rev + ("-dirty" if dirty else "")
+    except Exception:  # pragma: no cover - git may be unavailable
+        return "unknown"
+
+
+def run(repeats: int, only: list[str] | None) -> dict:
+    results = {}
+    for name, (fn, desc) in CASES.items():
+        if only and name not in only:
+            continue
+        value = fn()  # warm-up: numba compile, lazy imports
+        times = []
+        for _ in range(repeats):
+            t0 = time.perf_counter()
+            fn()
+            times.append(time.perf_counter() - t0)
+        results[name] = {
+            "description": desc,
+            "median_ms": 1e3 * statistics.median(times),
+            "min_ms": 1e3 * min(times),
+            "repeats": repeats,
+            "value": float(value),
+        }
+    return results
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--repeats", type=int, default=5)
+    parser.add_argument("--only", nargs="*", help="subset of case names")
+    parser.add_argument("--out", type=Path, help="write JSON results to this path")
+    args = parser.parse_args()
+
+    results = run(args.repeats, args.only)
+    payload = {
+        "timestamp": datetime.now(UTC).isoformat(timespec="seconds"),
+        "git": _git_rev(),
+        "platform": platform.platform(),
+        "machine": platform.machine(),
+        "python": sys.version.split()[0],
+        "numpy": np.__version__,
+        "scipy": scipy.__version__,
+        "numba": numba.__version__,
+        "results": results,
+    }
+
+    print(f"{'case':26s}{'median ms':>12s}{'min ms':>10s}   value")
+    for name, r in results.items():
+        print(f"{name:26s}{r['median_ms']:12.3f}{r['min_ms']:10.3f}   {r['value']:.6f}")
+    if args.out:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(payload, indent=2) + "\n")
+        print(f"\nwrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()

{optpricing-2.4.0 → optpricing-2.6.0}/pyproject.toml

@@ -135,6 +135,10 @@ testpaths = ["tests"]
 # Coverage is opt-in: `pytest --cov` (CI does this); plain `pytest` stays fast and debuggable.
 addopts = "-ra --strict-markers --strict-config"
 xfail_strict = true
+filterwarnings = [
+    # Several fixtures deliberately use Feller-violating Heston/CIR parameters.
+    "ignore:.*do not satisfy the Feller condition.*:UserWarning",
+]
 
 [tool.coverage.run]
 source = ["optpricing"]

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/calibration/iv_surface.py

@@ -95,7 +95,7 @@ class VolatilitySurface:
         market_ivs = self._calculate_ivs(stock, rate, self.data["marketPrice"])
         self.surface = self.data.copy()
         self.surface["iv"] = market_ivs
-        self.surface.dropna(inplace=True)
+        self.surface = self.surface.dropna()
         self.surface = self.surface[
             (self.surface["iv"] > 1e-4) & (self.surface["iv"] < 2.0)
         ]
@@ -146,5 +146,5 @@ class VolatilitySurface:
         )
         self.surface = self.data.copy()
         self.surface["iv"] = model_ivs
-        self.surface.dropna(inplace=True)
+        self.surface = self.surface.dropna()
         return self

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/calibration/vectorized_bsm_iv.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import numpy as np
 import pandas as pd
-from scipy.stats import norm
+from scipy.special import ndtr
 
 from optpricing.atoms import Rate, Stock
 
@@ -78,13 +78,14 @@ class BSMIVSolver:
                 sqrt_T = np.sqrt(T)
                 d1 = (np.log(S / K) + (r - q + 0.5 * iv**2) * T) / (iv * sqrt_T)
                 d2 = d1 - iv * sqrt_T
-                vega = S * np.exp(-q * T) * sqrt_T * norm.pdf(d1)
-                call_prices = S * np.exp(-q * T) * norm.cdf(d1) - K * np.exp(
-                    -r * T
-                ) * norm.cdf(d2)
-                put_prices = K * np.exp(-r * T) * norm.cdf(-d2) - S * np.exp(
-                    -q * T
-                ) * norm.cdf(-d1)
+                pdf_d1 = np.exp(-0.5 * d1 * d1) / np.sqrt(2.0 * np.pi)
+                vega = S * np.exp(-q * T) * sqrt_T * pdf_d1
+                call_prices = S * np.exp(-q * T) * ndtr(d1) - K * np.exp(-r * T) * ndtr(
+                    d2
+                )
+                put_prices = K * np.exp(-r * T) * ndtr(-d2) - S * np.exp(-q * T) * ndtr(
+                    -d1
+                )
             model_prices = np.where(is_call, call_prices, put_prices)
             error = model_prices - target_prices
             if np.all(np.abs(error) < self.tolerance):

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/calibration/vectorized_pricer.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
-from scipy import integrate
+
+from optpricing.techniques.integration import IntegrationTechnique
 
 if TYPE_CHECKING:
     import pandas as pd
@@ -64,15 +65,12 @@ def price_options_vectorized(
         phi = model.cf(t=T, spot=S, r=r, q=q, **kwargs)
         lnK = np.log(K)
 
-        def _integrand_p2(u: float) -> np.ndarray:
-            return (np.exp(-1j * u * lnK) * phi(u)).imag / u
-
-        def _integrand_p1(u: float) -> np.ndarray:
-            return (np.exp(-1j * u * lnK) * phi(u - 1j)).imag / u
-
-        # Vectorised quad once per maturity
-        p2, _ = integrate.quad_vec(_integrand_p2, 1e-15, upper_bound)
-        p1, _ = integrate.quad_vec(_integrand_p1, 1e-15, upper_bound)
+        # Composite Gauss-Legendre (same rule as IntegrationTechnique): one CF
+        # evaluation per maturity, integrands as a (strikes x nodes) matrix.
+        u, w = IntegrationTechnique.gauss_nodes(upper_bound, 24)
+        twist = np.exp(-1j * np.outer(lnK, u)) / u  # (n_strikes, n_nodes)
+        p2 = (twist * phi(u)).imag @ w
+        p1 = (twist * phi(u - 1j)).imag @ w
 
         denom = np.real(phi(-1j))
         denom = 1.0 if abs(denom) < 1e-12 else denom

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/cli/commands/dashboard.py

@@ -15,7 +15,8 @@ def dashboard():
     Launches the Streamlit dashboard application.
     """
     try:
-        with resources.path("optpricing.dashboard", "Home.py") as app_path:
+        home = resources.files("optpricing.dashboard").joinpath("Home.py")
+        with resources.as_file(home) as app_path:
             typer.echo(f"Launching Streamlit dashboard from: {app_path}")
             subprocess.run(["streamlit", "run", str(app_path)], check=True)
     except FileNotFoundError:

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/cli/commands/price.py

@@ -172,7 +172,7 @@ def price(
     stock = Stock(spot=spot, dividend=q_div)
     rate = Rate(rate=r_rate)
     maturity_years = (
-        pd.to_datetime(maturity) - pd.Timestamp.utcnow().tz_localize(None)
+        pd.to_datetime(maturity) - pd.Timestamp.now(tz="UTC").tz_localize(None)
     ).days / 365.25
     if maturity_years <= 0:
         _err("Maturity date must be in the future.")

optpricing-2.6.0/src/optpricing/config.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+__doc__ = """
+Resolve the project root, read the optional ``config.yaml`` and expose the data
+and artifact directories.
+
+The root is ``$OPTPRICING_HOME`` if set, otherwise the current working directory.
+Running from a source checkout therefore behaves as before, while an installed
+package no longer writes ``config.yaml`` or data folders next to its own modules
+in ``site-packages``. Nothing is created at import time; writers create the
+directory they need (see :func:`ensure_directories`).
+"""
+
+DEFAULT_CONFIG: dict[str, object] = {
+    "live_data_provider": "yfinance",
+    "data_directory": "data",
+    "artifacts_directory": "artifacts",
+}
+
+PROJECT_ROOT = Path(os.environ.get("OPTPRICING_HOME", Path.cwd())).resolve()
+CONFIG_FILE_PATH = PROJECT_ROOT / "config.yaml"
+
+
+def _load_config(path: Path) -> dict:
+    if not path.exists():
+        return dict(DEFAULT_CONFIG)
+    with open(path) as f:
+        loaded = yaml.safe_load(f) or {}
+    return {**DEFAULT_CONFIG, **loaded}
+
+
+_config = _load_config(CONFIG_FILE_PATH)
+
+# Directory Management
+DATA_DIR = PROJECT_ROOT / str(_config.get("data_directory", "data"))
+ARTIFACTS_DIR = PROJECT_ROOT / str(_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"
+
+ALL_DIRS = [
+    DATA_DIR,
+    ARTIFACTS_DIR,
+    MARKET_SNAPSHOT_DIR,
+    HISTORICAL_DIR,
+    BACKTEST_LOGS_DIR,
+    CALIBRATED_PARAMS_DIR,
+    CALIBRATION_LOGS_DIR,
+]
+
+
+def ensure_directories() -> None:
+    """Create all data and artifact directories (idempotent)."""
+    for path in ALL_DIRS:
+        path.mkdir(parents=True, exist_ok=True)

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/data/historical_manager.py

@@ -42,6 +42,7 @@ def save_historical_returns(
 
             log_returns = np.log(data["Close"] / data["Close"].shift(1)).dropna()
             filename = HISTORICAL_DIR / f"{ticker}_{period}_returns.parquet"
+            filename.parent.mkdir(parents=True, exist_ok=True)
             log_returns.to_frame(name="log_return").to_parquet(filename)
 
             print(f"  -> Saved to {filename}")

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/data/market_data_manager.py

@@ -45,9 +45,8 @@ def _fetch_from_yfinance(ticker: str) -> pd.DataFrame | None:
             "last_price", ticker_obj.history("1d")["Close"].iloc[0]
         )
 
-        chain_df.dropna(
+        chain_df = chain_df.dropna(
             subset=["marketPrice", "strike", "maturity", "impliedVolatility"],
-            inplace=True,
         )
         chain_df = chain_df[
             (chain_df["marketPrice"] > 0.01) & (chain_df["maturity"] > 1 / 365.25)
@@ -112,6 +111,7 @@ def save_market_snapshot(tickers: list[str]):
             continue
 
         filename = MARKET_SNAPSHOT_DIR / f"{ticker}_{today_str}.parquet"
+        filename.parent.mkdir(parents=True, exist_ok=True)
         chain_df.to_parquet(filename)
         print(f"  -> Successfully saved {len(chain_df)} options to {filename}")
 

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/models/base/__init__.py

@@ -7,6 +7,7 @@ parameter validation tools.
 """
 
 from .base_model import CF, BaseModel, PDECoeffs
+from .cf_sampler import sample_from_cf
 from .validators import ParamValidator
 
 __all__ = [
@@ -14,4 +15,5 @@ __all__ = [
     "CF",
     "PDECoeffs",
     "ParamValidator",
+    "sample_from_cf",
 ]

optpricing-2.6.0/src/optpricing/models/base/cf_sampler.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+__doc__ = """
+Inverse-transform sampling of a univariate law from its characteristic function.
+
+Used by pure-jump Levy models whose terminal distribution has no tractable exact
+sampler at an arbitrary horizon (CGMY for general Y, the hyperbolic Levy motion
+for t != 1). The density is recovered with the COS expansion of Fang & Oosterlee
+(2008) on a cumulant-based truncation range, integrated to a CDF on a fine grid,
+and inverted by interpolation.
+"""
+
+
+def _cumulants_from_cf(cf: Callable, h: float = 1e-3) -> tuple[float, float]:
+    """First two cumulants from central differences of the CF at the origin."""
+    phi_p, phi_m = cf(h), cf(-h)
+    c1 = float(np.imag(phi_p - phi_m) / (2.0 * h))
+    second_moment = -float(np.real(phi_p - 2.0 + phi_m) / h**2)
+    c2 = max(second_moment - c1**2, 1e-16)
+    return c1, c2
+
+
+def cos_cdf_table(
+    cf: Callable,
+    *,
+    n_terms: int = 4096,
+    n_grid: int = 8193,
+    width: float = 12.0,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Tabulate the CDF implied by a characteristic function on a regular grid.
+
+    Parameters
+    ----------
+    cf : Callable
+        Characteristic function ``u -> E[exp(iuX)]`` accepting numpy arrays.
+    n_terms : int, optional
+        Number of COS terms, by default 4096.
+    n_grid : int, optional
+        Number of grid points for the tabulated CDF, by default 8193.
+    width : float, optional
+        Half-width of the truncation range in standard deviations, by default 12.
+        The range is widened automatically if it does not capture the mass.
+
+    Returns
+    -------
+    tuple[np.ndarray, np.ndarray]
+        ``(x_grid, cdf)`` with ``cdf`` non-decreasing from 0 to 1.
+    """
+    c1, c2 = _cumulants_from_cf(cf)
+    std = np.sqrt(c2)
+
+    for _ in range(6):
+        a, b = c1 - width * std, c1 + width * std
+        span = b - a
+        k = np.arange(n_terms)
+        omega = k * np.pi / span
+        coeffs = (2.0 / span) * np.real(cf(omega) * np.exp(-1j * omega * a))
+        coeffs[0] *= 0.5
+
+        x = np.linspace(a, b, n_grid)
+        # CDF(x) = int_a^x density
+        #        = c_0 (x-a) + sum_{k>=1} c_k (span/(k pi)) sin(k pi (x-a)/span)
+        phase = np.outer(x - a, omega[1:])
+        sine_weights = coeffs[1:] * span / (k[1:] * np.pi)
+        cdf = coeffs[0] * (x - a) + np.sin(phase) @ sine_weights
+
+        total = cdf[-1]
+        edge_mass = max(abs(cdf[1] - cdf[0]), abs(cdf[-1] - cdf[-2])) / (x[1] - x[0])
+        if abs(total - 1.0) < 1e-6 and edge_mass * std < 1e-7:
+            break
+        width *= 1.5  # heavy tails: widen and retry
+
+    cdf = np.maximum.accumulate(np.clip(cdf, 0.0, None))
+    cdf /= cdf[-1]
+    return x, cdf
+
+
+def sample_from_cf(
+    cf: Callable,
+    size: int,
+    rng: np.random.Generator,
+    **table_kwargs,
+) -> np.ndarray:
+    """
+    Draw ``size`` samples of the law with characteristic function ``cf``.
+
+    Parameters
+    ----------
+    cf : Callable
+        Characteristic function accepting numpy arrays.
+    size : int
+        Number of samples.
+    rng : np.random.Generator
+        Random number generator used for the uniforms.
+    **table_kwargs
+        Forwarded to :func:`cos_cdf_table`.
+
+    Returns
+    -------
+    np.ndarray
+        Samples obtained by inverse transform of the tabulated CDF.
+    """
+    x, cdf = cos_cdf_table(cf, **table_kwargs)
+    u = rng.uniform(0.0, 1.0, size=size)
+    return np.interp(u, cdf, x)

{optpricing-2.4.0 → optpricing-2.6.0}/src/optpricing/models/bates.py

@@ -35,7 +35,7 @@ class BatesModel(BaseModel):
         "kappa": 2.0,
         "theta": 0.04,
         "rho": -0.7,
-        "vol_of_vol": 0.5,
+        "vol_of_vol": 0.3,
         "lambda": 0.5,
         "mu_j": -0.1,
         "sigma_j": 0.15,
@@ -78,7 +78,7 @@ class BatesModel(BaseModel):
         spot: float,
         r: float,
         q: float,
-        v0: float,
+        v0: float | None = None,
         **_: Any,
     ) -> CF:
         """
@@ -94,8 +94,9 @@ class BatesModel(BaseModel):
             The continuously compounded risk-free rate.
         q : float
             The continuously compounded dividend yield.
-        v0 : float
-            The initial variance of the asset's returns.
+        v0 : float | None, optional
+            The initial variance of the asset's returns. Defaults to the model's
+            ``v0`` parameter.
 
         Returns
         -------
@@ -103,6 +104,12 @@ class BatesModel(BaseModel):
             The characteristic function.
         """
         p = self.params
+        if v0 is None:
+            v0 = p.get("v0")
+            if v0 is None:
+                raise ValueError(
+                    f"{self.name}: 'v0' must be a model parameter or a pricing kwarg."
+                )
         kappa, theta, rho, vol_of_vol = (
             p["kappa"],
             p["theta"],