radonlab 0.1.0__py3-none-any.whl

radonlab/__init__.py

@@ -0,0 +1,72 @@
+"""radonlab -- Monte Carlo Greeks for discontinuous payoffs.
+
+A small, dependency-light library for estimating option sensitivities when the
+payoff is discontinuous (digitals, barriers) and the textbook pathwise method
+breaks down.  It implements, tests and benchmarks the classic remedies side by
+side: the likelihood-ratio method, payoff smoothing, and Brownian-bridge
+conditional Monte Carlo, against finite-difference and pathwise baselines and
+closed-form Black-Scholes references.
+
+Quick start
+-----------
+>>> from radonlab import GeometricBrownianMotion, CashOrNothingCall, Greek
+>>> from radonlab import likelihood_ratio, analytics
+>>> model = GeometricBrownianMotion(S0=100, r=0.03, sigma=0.2, T=1.0)
+>>> payoff = CashOrNothingCall(strike=100)
+>>> est = likelihood_ratio(model, payoff, Greek.DELTA, n_paths=500_000)
+>>> ref = analytics.cash_or_nothing_call(100, 100, 0.03, 0.2, 1.0, greek="delta")
+>>> abs(est.value - ref) < 4 * est.std_error
+True
+"""
+
+from __future__ import annotations
+
+from . import analytics, asian, benchmark, merton
+from ._version import __version__
+from .estimators import (
+    conditional_mc,
+    finite_difference,
+    likelihood_ratio,
+    pathwise,
+    smoothing,
+    suggest_bandwidth,
+)
+from .models import GeometricBrownianMotion
+from .payoffs import (
+    AssetOrNothingCall,
+    CashOrNothingCall,
+    DownAndOutCall,
+    VanillaCall,
+    VanillaPut,
+)
+from .rng import NormalSampler
+from .types import Greek, GreekResult, MarketError
+
+__all__ = [
+    "__version__",
+    # model & rng
+    "GeometricBrownianMotion",
+    "NormalSampler",
+    # payoffs
+    "VanillaCall",
+    "VanillaPut",
+    "CashOrNothingCall",
+    "AssetOrNothingCall",
+    "DownAndOutCall",
+    # estimators
+    "likelihood_ratio",
+    "pathwise",
+    "finite_difference",
+    "smoothing",
+    "suggest_bandwidth",
+    "conditional_mc",
+    # types
+    "Greek",
+    "GreekResult",
+    "MarketError",
+    # modules
+    "analytics",
+    "benchmark",
+    "merton",
+    "asian",
+]

radonlab/_special.py

@@ -0,0 +1,37 @@
+"""Numerical helpers.
+
+The normal CDF/PDF here are deliberately implemented on top of
+:func:`scipy.special.erfc`, which accepts complex arguments.  This lets the
+closed-form pricing functions in :mod:`radonlab.analytics` be evaluated at
+complex inputs, which in turn enables *complex-step differentiation* -- a
+machine-precision way to obtain reference Greeks that the test-suite checks the
+explicit analytic formulas against.
+
+Nothing in this module is specific to any payoff or model; it is pure math.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import special
+
+__all__ = ["norm_cdf", "norm_pdf", "SQRT_2PI", "SQRT_2"]
+
+SQRT_2PI: float = float(np.sqrt(2.0 * np.pi))
+SQRT_2: float = float(np.sqrt(2.0))
+
+
+def norm_cdf(x):
+    """Standard normal cumulative distribution function.
+
+    Works for real and complex ``x`` (element-wise for arrays).  The complex
+    branch is what makes complex-step differentiation of the pricing formulas
+    possible.
+    """
+    return 0.5 * special.erfc(-np.asarray(x) / SQRT_2)
+
+
+def norm_pdf(x):
+    """Standard normal probability density function (real or complex ``x``)."""
+    x = np.asarray(x)
+    return np.exp(-0.5 * x * x) / SQRT_2PI

radonlab/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

radonlab/analytics.py

@@ -0,0 +1,190 @@
+"""Closed-form Black-Scholes / Black-Scholes-Merton analytics.
+
+These functions are the *ground truth* the Monte Carlo estimators are validated
+against.  Everything is derived under a geometric Brownian motion with constant
+risk-free rate ``r``, continuous dividend yield ``q`` and volatility ``sigma``:
+
+    S_T = S_0 * exp((r - q - 0.5 * sigma**2) * T + sigma * sqrt(T) * Z),
+    Z ~ N(0, 1).
+
+The explicit Greek formulas are checked against complex-step differentiation of
+the corresponding price formulas in the test-suite, so any algebra error is
+caught automatically.
+
+References
+----------
+- Black, F. and Scholes, M. (1973). The Pricing of Options and Corporate
+  Liabilities. Journal of Political Economy.
+- Reiner, E. and Rubinstein, M. (1991). Breaking Down the Barriers. Risk.
+- Haug, E. G. (2007). The Complete Guide to Option Pricing Formulas, 2nd ed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ._special import norm_cdf, norm_pdf
+
+__all__ = [
+    "d1_d2",
+    "vanilla_call",
+    "vanilla_put",
+    "cash_or_nothing_call",
+    "asset_or_nothing_call",
+    "down_and_out_call",
+    "down_and_in_call",
+]
+
+
+def d1_d2(S, K, r, sigma, T, q=0.0):
+    """Return the Black-Scholes ``d1`` and ``d2`` terms."""
+    S = (
+        np.asarray(S, dtype=complex)
+        if np.iscomplexobj(S)
+        else np.asarray(S, dtype=float)
+    )
+    vol_t = sigma * np.sqrt(T)
+    d1 = (np.log(S / K) + (r - q + 0.5 * sigma * sigma) * T) / vol_t
+    d2 = d1 - vol_t
+    return d1, d2
+
+
+# --------------------------------------------------------------------------- #
+# Vanilla European call/put
+# --------------------------------------------------------------------------- #
+def vanilla_call(S, K, r, sigma, T, q=0.0, greek="price"):
+    """Price or Greek of a European call.
+
+    ``greek`` is one of ``price``, ``delta``, ``gamma``, ``vega``, ``theta``,
+    ``rho``.
+    """
+    d1, d2 = d1_d2(S, K, r, sigma, T, q)
+    disc_r = np.exp(-r * T)
+    disc_q = np.exp(-q * T)
+    sqrt_t = np.sqrt(T)
+
+    if greek == "price":
+        return S * disc_q * norm_cdf(d1) - K * disc_r * norm_cdf(d2)
+    if greek == "delta":
+        return disc_q * norm_cdf(d1)
+    if greek == "gamma":
+        return disc_q * norm_pdf(d1) / (S * sigma * sqrt_t)
+    if greek == "vega":
+        return S * disc_q * norm_pdf(d1) * sqrt_t
+    if greek == "rho":
+        return K * T * disc_r * norm_cdf(d2)
+    if greek == "theta":
+        term1 = -S * disc_q * norm_pdf(d1) * sigma / (2 * sqrt_t)
+        term2 = q * S * disc_q * norm_cdf(d1)
+        term3 = -r * K * disc_r * norm_cdf(d2)
+        return term1 + term2 + term3
+    raise ValueError(f"Unknown greek {greek!r}.")
+
+
+def vanilla_put(S, K, r, sigma, T, q=0.0, greek="price"):
+    """Price or Greek of a European put (via put-call parity relations)."""
+    d1, d2 = d1_d2(S, K, r, sigma, T, q)
+    disc_r = np.exp(-r * T)
+    disc_q = np.exp(-q * T)
+    sqrt_t = np.sqrt(T)
+
+    if greek == "price":
+        return K * disc_r * norm_cdf(-d2) - S * disc_q * norm_cdf(-d1)
+    if greek == "delta":
+        return disc_q * (norm_cdf(d1) - 1.0)
+    if greek == "gamma":
+        return disc_q * norm_pdf(d1) / (S * sigma * sqrt_t)
+    if greek == "vega":
+        return S * disc_q * norm_pdf(d1) * sqrt_t
+    if greek == "rho":
+        return -K * T * disc_r * norm_cdf(-d2)
+    if greek == "theta":
+        term1 = -S * disc_q * norm_pdf(d1) * sigma / (2 * sqrt_t)
+        term2 = -q * S * disc_q * norm_cdf(-d1)
+        term3 = r * K * disc_r * norm_cdf(-d2)
+        return term1 + term2 + term3
+    raise ValueError(f"Unknown greek {greek!r}.")
+
+
+# --------------------------------------------------------------------------- #
+# Cash-or-nothing digital call: pays `cash` if S_T > K
+# --------------------------------------------------------------------------- #
+def cash_or_nothing_call(S, K, r, sigma, T, q=0.0, cash=1.0, greek="price"):
+    """Price or Greek of a cash-or-nothing digital call.
+
+    This is the canonical *discontinuous* payoff for which naive pathwise
+    differentiation fails and the likelihood-ratio / smoothing / conditional
+    Monte Carlo methods earn their keep.
+    """
+    d1, d2 = d1_d2(S, K, r, sigma, T, q)
+    disc_r = np.exp(-r * T)
+    vol_t = sigma * np.sqrt(T)
+
+    if greek == "price":
+        return cash * disc_r * norm_cdf(d2)
+    if greek == "delta":
+        return cash * disc_r * norm_pdf(d2) / (S * vol_t)
+    if greek == "gamma":
+        return (
+            -cash * disc_r * norm_pdf(d2) * (d2 + vol_t) / (S * S * sigma * sigma * T)
+        )
+    if greek == "vega":
+        # d(N(d2))/dsigma = n(d2) * d(d2)/dsigma, d2 = d1 - vol_t
+        dd2_dsigma = -d1 / sigma
+        return cash * disc_r * norm_pdf(d2) * dd2_dsigma
+    if greek == "rho":
+        # d/dr [ e^{-rT} N(d2) ]; d(d2)/dr = sqrt(T)/sigma
+        return cash * disc_r * (-T * norm_cdf(d2) + norm_pdf(d2) * np.sqrt(T) / sigma)
+    raise ValueError(f"Unknown greek {greek!r}.")
+
+
+# --------------------------------------------------------------------------- #
+# Asset-or-nothing digital call: pays S_T if S_T > K
+# --------------------------------------------------------------------------- #
+def asset_or_nothing_call(S, K, r, sigma, T, q=0.0, greek="price"):
+    """Price or Greek of an asset-or-nothing digital call."""
+    d1, d2 = d1_d2(S, K, r, sigma, T, q)
+    disc_q = np.exp(-q * T)
+    vol_t = sigma * np.sqrt(T)
+
+    if greek == "price":
+        return S * disc_q * norm_cdf(d1)
+    if greek == "delta":
+        return disc_q * (norm_cdf(d1) + norm_pdf(d1) / vol_t)
+    if greek == "vega":
+        dd1_dsigma = -d2 / sigma
+        return S * disc_q * norm_pdf(d1) * dd1_dsigma
+    raise ValueError(f"Unknown greek {greek!r}.")
+
+
+# --------------------------------------------------------------------------- #
+# Continuously-monitored down-and-out / down-and-in call, B <= K, no rebate
+# --------------------------------------------------------------------------- #
+def _barrier_lambda(r, q, sigma):
+    return (r - q + 0.5 * sigma * sigma) / (sigma * sigma)
+
+
+def down_and_in_call(S, K, B, r, sigma, T, q=0.0, greek="price"):
+    """Continuously-monitored down-and-in call price (requires ``B <= K``)."""
+    if greek != "price":
+        raise ValueError("Only 'price' is provided in closed form for barriers.")
+    lam = _barrier_lambda(r, q, sigma)
+    vol_t = sigma * np.sqrt(T)
+    disc_r = np.exp(-r * T)
+    disc_q = np.exp(-q * T)
+    y = np.log(B * B / (S * K)) / vol_t + lam * vol_t
+    return S * disc_q * (B / S) ** (2 * lam) * norm_cdf(y) - K * disc_r * (B / S) ** (
+        2 * lam - 2
+    ) * norm_cdf(y - vol_t)
+
+
+def down_and_out_call(S, K, B, r, sigma, T, q=0.0, greek="price"):
+    """Continuously-monitored down-and-out call price (requires ``B <= K``).
+
+    Uses the in-out parity ``C_do = C_vanilla - C_di``.
+    """
+    if greek != "price":
+        raise ValueError("Only 'price' is provided in closed form for barriers.")
+    vanilla = vanilla_call(S, K, r, sigma, T, q, greek="price")
+    knock_in = down_and_in_call(S, K, B, r, sigma, T, q, greek="price")
+    return vanilla - knock_in

radonlab/asian.py

@@ -0,0 +1,155 @@
+"""Path-dependent Greeks: the geometric Asian digital.
+
+The payoff ``1{A > K}`` depends on the geometric average
+``A = (prod_i S_{t_i})^{1/m}`` of the price at ``m`` monitoring dates, so it is
+both path-dependent and discontinuous. Naive pathwise differentiation fails for
+the same reason it fails on a European digital.
+
+Because ``ln A`` is Gaussian under geometric Brownian motion, this payoff has a
+closed-form price and delta, which we use as ground truth. The estimator is the
+likelihood-ratio / Malliavin weight for the law of ``A``:
+
+    delta = e^{-rT} E[ 1{A > K} * G / (v_A * S0) ],
+    G = ln A - E[ln A],  v_A = Var(ln A).
+
+The weight ``G/(v_A S0)`` is the score of the (Gaussian) law of ``ln A`` with
+respect to the spot; it coincides with the Malliavin integration-by-parts weight
+projected onto ``A``. Crucially ``G`` is built from the entire simulated path,
+which is what makes this a genuinely path-dependent estimator rather than a
+terminal one.
+
+References
+----------
+- Fournie, E., Lasry, J.-M., Lebuchoux, J., Lions, P.-L. and Touzi, N. (1999).
+  Applications of Malliavin calculus to Monte Carlo methods in finance.
+  Finance and Stochastics 3(4), 391-412.
+- Glasserman, P. (2003). Monte Carlo Methods in Financial Engineering, ch. 7.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._special import norm_cdf, norm_pdf
+from .estimators.base import make_result
+from .types import Greek, GreekResult
+
+__all__ = [
+    "GeometricAsianDigital",
+    "geometric_asian_digital_closed_form",
+    "geometric_asian_digital_delta_lrm",
+    "geometric_asian_digital_delta_pathwise",
+]
+
+
+@dataclass(frozen=True)
+class GeometricAsianDigital:
+    """Discretely-monitored geometric Asian cash-or-nothing call under GBM.
+
+    Monitoring dates are ``t_i = i * T / m`` for ``i = 1..m``.
+    """
+
+    S0: float
+    K: float
+    r: float
+    sigma: float
+    T: float
+    m: int
+    q: float = 0.0
+    cash: float = 1.0
+
+    def __post_init__(self) -> None:
+        if self.S0 <= 0 or self.sigma <= 0 or self.T <= 0:
+            raise ValueError("S0, sigma, T must be positive.")
+        if self.m < 1:
+            raise ValueError("m must be at least 1.")
+
+    @property
+    def times(self) -> np.ndarray:
+        return np.arange(1, self.m + 1) * (self.T / self.m)
+
+    @property
+    def _mean_var(self):
+        """Mean and variance of ln A."""
+        t = self.times
+        mean = math.log(self.S0) + (self.r - self.q - 0.5 * self.sigma**2) * t.mean()
+        cov_sum = np.minimum.outer(t, t).sum()
+        var = (self.sigma**2 / self.m**2) * cov_sum
+        return float(mean), float(var)
+
+    @property
+    def discount(self) -> float:
+        return math.exp(-self.r * self.T)
+
+    def sample(self, n: int, rng: np.random.Generator) -> np.ndarray:
+        """Sample ``n`` geometric averages ``A``."""
+        dt = self.T / self.m
+        incr = rng.standard_normal((n, self.m)) * math.sqrt(dt)
+        w = np.cumsum(incr, axis=1)  # Brownian motion at monitoring dates
+        t = self.times
+        log_s = (
+            math.log(self.S0)
+            + (self.r - self.q - 0.5 * self.sigma**2) * t
+            + self.sigma * w
+        )
+        log_a = log_s.mean(axis=1)
+        return np.exp(log_a)
+
+
+def geometric_asian_digital_closed_form(
+    opt: GeometricAsianDigital, greek: str = "price"
+) -> float:
+    """Closed-form price or delta of the geometric Asian digital."""
+    mean, var = opt._mean_var
+    sd = math.sqrt(var)
+    d = (mean - math.log(opt.K)) / sd
+    if greek == "price":
+        return opt.cash * opt.discount * norm_cdf(d)
+    if greek == "delta":
+        # d(mean)/dS0 = 1/S0, so d(d)/dS0 = 1/(S0 sd).
+        return opt.cash * opt.discount * norm_pdf(d) / (opt.S0 * sd)
+    raise ValueError("greek must be 'price' or 'delta'.")
+
+
+def geometric_asian_digital_delta_lrm(
+    opt: GeometricAsianDigital, n_paths: int = 1_000_000, seed: int = 0
+) -> GreekResult:
+    """Likelihood-ratio / Malliavin delta of the geometric Asian digital.
+
+    Unbiased for the discontinuous payoff, using a weight built from the whole
+    path.
+    """
+    rng = np.random.default_rng(seed)
+    mean, var = opt._mean_var
+    a = opt.sample(n_paths, rng)
+    g = np.log(a) - mean  # centered Gaussian, a path functional
+    weight = g / (var * opt.S0)
+    payoff = opt.cash * (a > opt.K).astype(float)
+    contrib = opt.discount * payoff * weight
+    return make_result(
+        contrib,
+        greek=Greek.DELTA,
+        method="geometric-asian-lrm",
+        runtime_s=None,
+        n_paths=n_paths,
+    )
+
+
+def geometric_asian_digital_delta_pathwise(
+    opt: GeometricAsianDigital, n_paths: int = 1_000_000, seed: int = 0
+) -> GreekResult:
+    """Naive pathwise delta, retained to show it collapses to zero (biased)."""
+    rng = np.random.default_rng(seed)
+    a = opt.sample(n_paths, rng)
+    # d/dA of 1{A>K} is zero almost everywhere.
+    contrib = np.zeros_like(a)
+    return make_result(
+        contrib,
+        greek=Greek.DELTA,
+        method="geometric-asian-pathwise",
+        runtime_s=None,
+        n_paths=n_paths,
+    )

radonlab/benchmark.py

@@ -0,0 +1,88 @@
+"""Benchmark harness.
+
+Runs a set of estimators for the same Greek and tabulates their point estimate,
+standard error, absolute error against a known analytic reference, the number of
+standard errors that error represents, and runtime.  This is what turns the
+library from "some estimators" into "here is *which one to use and why*".
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from .models import GeometricBrownianMotion
+from .payoffs import TerminalPayoff
+from .rng import NormalSampler
+from .types import Greek, GreekResult, MarketError
+
+try:  # pandas is optional; the harness degrades to a list of dicts without it.
+    import pandas as _pd
+
+    _HAS_PANDAS = True
+except Exception:  # pragma: no cover
+    _HAS_PANDAS = False
+
+
+def _record(result: GreekResult, reference: float, bias_z: float) -> dict[str, object]:
+    err = MarketError(result, reference)
+    # A method is flagged biased if its estimate sits many standard errors from
+    # the reference, or if it reports zero variance yet is plainly wrong (the
+    # degenerate pathwise-on-a-digital case).
+    biased = err.z_score > bias_z or (result.std_error == 0.0 and err.abs_error > 1e-8)
+    return {
+        "method": result.method,
+        "greek": str(result.greek),
+        "value": result.value,
+        "std_error": result.std_error,
+        "abs_error": err.abs_error,
+        "rel_error": err.rel_error,
+        "z_score": err.z_score,
+        "biased": biased,
+        "n_paths": result.n_paths,
+        "runtime_s": result.runtime_s,
+    }
+
+
+def benchmark_terminal(
+    model: GeometricBrownianMotion,
+    payoff: TerminalPayoff,
+    greek: Greek,
+    reference: float,
+    estimators: dict[str, Callable[..., GreekResult]],
+    n_paths: int = 200_000,
+    seed: int = 0,
+    sampler_kwargs: dict | None = None,
+    bias_z: float = 6.0,
+):
+    """Run each estimator once and compare against ``reference``.
+
+    ``estimators`` maps a display label to a callable
+    ``fn(model, payoff, greek, n_paths=..., sampler=...) -> GreekResult``.
+    Each estimator gets an independent sampler spawned from the same seed so the
+    comparison is fair and reproducible.
+
+    Results are ranked by *standard error* (the estimator's inherent noise, the
+    metric that actually matters), with any biased estimator sorted last and
+    flagged, rather than by the single-run absolute error, which is itself a
+    noisy draw.
+
+    Returns a :class:`pandas.DataFrame` if pandas is installed, else a list of
+    dicts.
+    """
+    sampler_kwargs = dict(sampler_kwargs or {})
+    parent = NormalSampler(seed=seed, **sampler_kwargs)
+
+    records: list[dict[str, object]] = []
+    for _label, fn in estimators.items():
+        result = fn(model, payoff, greek, n_paths=n_paths, sampler=parent.spawn())
+        records.append(_record(result, reference, bias_z))
+
+    def _key(r: dict[str, object]):
+        # Unbiased first, then lowest standard error.
+        return (bool(r["biased"]), float(r["std_error"]))
+
+    if _HAS_PANDAS:
+        df = _pd.DataFrame.from_records(records)
+        df = df.sort_values(["biased", "std_error"]).reset_index(drop=True)
+        return df
+    return sorted(records, key=_key)

radonlab/estimators/__init__.py

@@ -0,0 +1,16 @@
+"""Greek estimators for terminal and path-dependent payoffs."""
+
+from .conditional_mc import conditional_mc
+from .finite_difference import finite_difference
+from .likelihood_ratio import likelihood_ratio
+from .pathwise import pathwise
+from .smoothing import smoothing, suggest_bandwidth
+
+__all__ = [
+    "conditional_mc",
+    "finite_difference",
+    "likelihood_ratio",
+    "pathwise",
+    "smoothing",
+    "suggest_bandwidth",
+]

radonlab/estimators/base.py

@@ -0,0 +1,57 @@
+"""Shared estimator machinery."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import numpy as np
+
+from ..types import Greek, GreekResult
+
+
+def mc_mean_se(samples: np.ndarray) -> tuple[float, float]:
+    """Monte Carlo mean and standard error of the mean.
+
+    Uses the sample standard deviation with ``ddof=1``.  For antithetic draws
+    this slightly overstates the true error (the pairs are negatively
+    correlated), which is the conservative direction.
+    """
+    samples = np.asarray(samples, dtype=float)
+    n = samples.size
+    mean = float(samples.mean())
+    if n < 2:
+        return mean, float("inf")
+    se = float(samples.std(ddof=1) / np.sqrt(n))
+    return mean, se
+
+
+@contextmanager
+def _timer() -> Iterator[list]:
+    box: list = [None]
+    start = time.perf_counter()
+    try:
+        yield box
+    finally:
+        box[0] = time.perf_counter() - start
+
+
+def make_result(
+    samples: np.ndarray,
+    greek: Greek,
+    method: str,
+    runtime_s: float | None = None,
+    **extra,
+) -> GreekResult:
+    """Build a :class:`GreekResult` from per-path contribution ``samples``."""
+    mean, se = mc_mean_se(samples)
+    return GreekResult(
+        value=mean,
+        std_error=se,
+        greek=greek,
+        method=method,
+        n_paths=int(np.asarray(samples).size),
+        runtime_s=runtime_s,
+        extra=dict(extra),
+    )