sppricer 0.2.1__py3-none-any.whl

sppricer/__init__.py

@@ -0,0 +1,35 @@
+"""sppricer: Monte Carlo pricing and risk for structured products."""
+
+from sppricer.analytics import bs_delta, bs_price, bs_vega
+from sppricer.engine import PricingResult, price_mc
+from sppricer.greeks import Greeks, bump_greeks
+from sppricer.market import Curve, Market, Underlying
+from sppricer.models import GBMModel, LocalVolModel, LocalVolSource, PathModel, simulate_gbm
+from sppricer.products import (
+    BarrierReverseConvertible,
+    EuropeanOption,
+    PhoenixAutocallable,
+    Product,
+)
+
+__all__ = [
+    "BarrierReverseConvertible",
+    "Curve",
+    "EuropeanOption",
+    "GBMModel",
+    "Greeks",
+    "LocalVolModel",
+    "LocalVolSource",
+    "Market",
+    "PathModel",
+    "PhoenixAutocallable",
+    "PricingResult",
+    "Product",
+    "Underlying",
+    "bs_delta",
+    "bs_price",
+    "bs_vega",
+    "bump_greeks",
+    "price_mc",
+    "simulate_gbm",
+]

sppricer/analytics.py

@@ -0,0 +1,43 @@
+"""Closed-form Black-Scholes formulas, used as benchmarks for the MC engine."""
+
+from __future__ import annotations
+
+import math
+
+
+def _norm_cdf(x: float) -> float:
+    return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0)))
+
+
+def _norm_pdf(x: float) -> float:
+    return math.exp(-0.5 * x * x) / math.sqrt(2.0 * math.pi)
+
+
+def _d1_d2(spot, strike, maturity, rate, vol, div_yield):
+    sqrt_t = math.sqrt(maturity)
+    d1 = (math.log(spot / strike) + (rate - div_yield + 0.5 * vol**2) * maturity) / (vol * sqrt_t)
+    return d1, d1 - vol * sqrt_t
+
+
+def bs_price(spot: float, strike: float, maturity: float, rate: float, vol: float,
+             div_yield: float = 0.0, is_call: bool = True) -> float:
+    d1, d2 = _d1_d2(spot, strike, maturity, rate, vol, div_yield)
+    fwd_s = spot * math.exp(-div_yield * maturity)
+    pv_k = strike * math.exp(-rate * maturity)
+    if is_call:
+        return fwd_s * _norm_cdf(d1) - pv_k * _norm_cdf(d2)
+    return pv_k * _norm_cdf(-d2) - fwd_s * _norm_cdf(-d1)
+
+
+def bs_delta(spot: float, strike: float, maturity: float, rate: float, vol: float,
+             div_yield: float = 0.0, is_call: bool = True) -> float:
+    d1, _ = _d1_d2(spot, strike, maturity, rate, vol, div_yield)
+    disc_q = math.exp(-div_yield * maturity)
+    return disc_q * _norm_cdf(d1) if is_call else disc_q * (_norm_cdf(d1) - 1.0)
+
+
+def bs_vega(spot: float, strike: float, maturity: float, rate: float, vol: float,
+            div_yield: float = 0.0) -> float:
+    """Vega per 1.00 change in vol (divide by 100 for per-vol-point)."""
+    d1, _ = _d1_d2(spot, strike, maturity, rate, vol, div_yield)
+    return spot * math.exp(-div_yield * maturity) * _norm_pdf(d1) * math.sqrt(maturity)

sppricer/engine.py

@@ -0,0 +1,51 @@
+"""Monte Carlo pricing engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from sppricer.market import Market
+from sppricer.models import GBMModel, PathModel, simulate_gbm
+from sppricer.products.base import Product
+
+
+@dataclass(frozen=True)
+class PricingResult:
+    price: float
+    std_error: float
+    n_paths: int
+
+    @property
+    def ci95(self) -> tuple[float, float]:
+        return self.price - 1.96 * self.std_error, self.price + 1.96 * self.std_error
+
+    def __str__(self) -> str:
+        lo, hi = self.ci95
+        return f"{self.price:.4f} ± {1.96 * self.std_error:.4f} (95% CI [{lo:.4f}, {hi:.4f}], {self.n_paths:,} paths)"
+
+
+def price_mc(product: Product, market: Market, n_paths: int = 100_000,
+             seed: int | None = None, antithetic: bool = True, model: PathModel | None = None) -> PricingResult:
+    """Price a product by Monte Carlo, under GBM unless another PathModel is given.
+
+    With antithetic sampling, each (Z, -Z) pair is averaged first so the
+    standard error reflects the true (reduced) variance of the estimator.
+
+    Barrier monitoring other than "european" uses a Brownian-bridge correction
+    that assumes flat GBM vol, so it raises under any other model.
+    """
+    if model is None:
+        paths = simulate_gbm(market, product.simulation_times, n_paths, seed, antithetic)
+    else:
+        monitoring = getattr(product, "barrier_monitoring", "european")
+        if monitoring != "european" and not isinstance(model, GBMModel):
+            raise ValueError(f"barrier_monitoring={monitoring!r} assumes flat-vol GBM between dates; "
+                             f"use 'european' with {type(model).__name__}")
+        paths = model.simulate(market, product.simulation_times, n_paths, seed, antithetic)
+    pv = product.discounted_payoff(paths, market)
+    if antithetic:
+        half = n_paths // 2
+        pv = 0.5 * (pv[:half] + pv[half:])
+    return PricingResult(float(pv.mean()), float(pv.std(ddof=1) / np.sqrt(len(pv))), n_paths)

sppricer/greeks.py

@@ -0,0 +1,58 @@
+"""Finite-difference Greeks with common random numbers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from sppricer.engine import price_mc
+from sppricer.market import Market
+from sppricer.models import PathModel
+from sppricer.products.base import Product
+
+
+@dataclass(frozen=True)
+class Greeks:
+    price: float
+    delta: np.ndarray   # per underlying, per 1 unit of spot
+    gamma: np.ndarray   # per underlying, per 1 unit of spot squared
+    vega: np.ndarray    # per underlying, per 1 vol point (0.01)
+    rho: float          # per 1 basis point
+
+
+def bump_greeks(product: Product, market: Market, n_paths: int = 100_000, seed: int = 0,
+                spot_bump: float = 0.01, vol_bump: float = 0.01,
+                rate_bump: float = 0.0001, model: PathModel | None = None) -> Greeks:
+    """Central-difference Greeks, reusing the same seed for every revaluation.
+
+    Common random numbers cancel most Monte Carlo noise between bumped prices.
+    Gamma of digital/barrier features is still noisy with bump-and-reprice;
+    see the roadmap (pathwise / likelihood-ratio estimators, payoff smoothing).
+
+    `model` is passed to price_mc. Vega bumps the underlyings' flat vols, so under
+    a model that ignores them (LocalVolModel) it is zero: bump the surface instead.
+    """
+    def pv(m: Market) -> float:
+        return price_mc(product, m, n_paths=n_paths, seed=seed, model=model).price
+
+    base = pv(market)
+    n = market.n_assets
+    delta, gamma, vega = np.zeros(n), np.zeros(n), np.zeros(n)
+
+    for i, u in enumerate(market.underlyings):
+        h = u.spot * spot_bump
+        up, dn = pv(market.with_spot(i, u.spot + h)), pv(market.with_spot(i, u.spot - h))
+        delta[i] = (up - dn) / (2 * h)
+        gamma[i] = (up - 2 * base + dn) / h**2
+
+        vol_dn = max(u.vol - vol_bump, 0.0)
+        v_up = pv(market.with_vol(i, u.vol + vol_bump))
+        v_dn = pv(market.with_vol(i, vol_dn))
+        vega[i] = (v_up - v_dn) / (u.vol + vol_bump - vol_dn) * 0.01
+
+    r_up = pv(market.with_rate(market.rate + rate_bump))
+    r_dn = pv(market.with_rate(market.rate - rate_bump))
+    rho = (r_up - r_dn) / 2
+
+    return Greeks(base, delta, gamma, vega, rho)

sppricer/market.py

@@ -0,0 +1,122 @@
+"""Market data containers: underlyings, rates (flat or curves), and correlation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Protocol
+
+import numpy as np
+
+
+class Curve(Protocol):
+    """A forward and discount term structure, e.g. one implied from an option chain.
+
+    forward(T) is the forward price of the asset for delivery at T (so forward(0)
+    is its spot); discount(T) is the zero-coupon discount factor to T.
+    """
+
+    def forward(self, T): ...
+
+    def discount(self, T): ...
+
+
+@dataclass(frozen=True)
+class Underlying:
+    """A single underlying with flat volatility and continuous dividend yield."""
+
+    name: str
+    spot: float
+    vol: float
+    div_yield: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.spot <= 0:
+            raise ValueError(f"{self.name}: spot must be positive")
+        if self.vol < 0:
+            raise ValueError(f"{self.name}: vol must be non-negative")
+
+
+@dataclass(frozen=True, eq=False)
+class Market:
+    """Market snapshot: underlyings, flat continuously compounded rate, correlation.
+
+    Term structure (optional): `curves` gives one Curve per underlying, and the
+    asset then grows like its forward, S0 * F(t) / F(0), instead of at r - q; S0
+    stays the underlying's spot, so spot bumps work as before. `discount_curve`
+    replaces exp(-rate * t) in `discount`. With either set, `rate` and
+    `div_yield` no longer enter prices, so `bump_greeks` reports rho = 0.
+    """
+
+    underlyings: tuple[Underlying, ...]
+    rate: float
+    correlation: np.ndarray | None = None
+    curves: tuple[Curve, ...] | None = None
+    discount_curve: Curve | None = None
+
+    def __post_init__(self) -> None:
+        n = len(self.underlyings)
+        if n == 0:
+            raise ValueError("at least one underlying is required")
+        corr = np.eye(n) if self.correlation is None else np.asarray(self.correlation, dtype=float)
+        if corr.shape != (n, n):
+            raise ValueError(f"correlation must be {n}x{n}, got {corr.shape}")
+        if not np.allclose(corr, corr.T) or not np.allclose(np.diag(corr), 1.0):
+            raise ValueError("correlation must be symmetric with unit diagonal")
+        try:
+            np.linalg.cholesky(corr)
+        except np.linalg.LinAlgError as exc:
+            raise ValueError("correlation matrix is not positive definite") from exc
+        if self.curves is not None:
+            if len(self.curves) != n:
+                raise ValueError(f"need one curve per underlying ({n}), got {len(self.curves)}")
+            object.__setattr__(self, "curves", tuple(self.curves))
+        object.__setattr__(self, "underlyings", tuple(self.underlyings))
+        object.__setattr__(self, "correlation", corr)
+
+    @classmethod
+    def single(cls, spot: float, vol: float, rate: float, div_yield: float = 0.0,
+               name: str = "S") -> Market:
+        return cls((Underlying(name, spot, vol, div_yield),), rate)
+
+    @property
+    def n_assets(self) -> int:
+        return len(self.underlyings)
+
+    @property
+    def spots(self) -> np.ndarray:
+        return np.array([u.spot for u in self.underlyings])
+
+    @property
+    def vols(self) -> np.ndarray:
+        return np.array([u.vol for u in self.underlyings])
+
+    @property
+    def div_yields(self) -> np.ndarray:
+        return np.array([u.div_yield for u in self.underlyings])
+
+    def discount(self, t: float | np.ndarray) -> float | np.ndarray:
+        if self.discount_curve is not None:
+            return self.discount_curve.discount(np.asarray(t, dtype=float))
+        return np.exp(-self.rate * np.asarray(t))
+
+    def log_growth(self, t: np.ndarray) -> np.ndarray:
+        """ln E[S(t)] / S(0) per asset, shape (len(t), n_assets): ln F(t)/F(0) or (r - q) t."""
+        t = np.asarray(t, dtype=float)
+        if self.curves is None:
+            return (self.rate - self.div_yields)[None, :] * t[:, None]
+        return np.stack([np.log(c.forward(t) / c.forward(0.0)) for c in self.curves], axis=1)
+
+    # Bump helpers (used for finite-difference Greeks)
+    def _with_underlying(self, i: int, **changes: float) -> Market:
+        unds = list(self.underlyings)
+        unds[i] = replace(unds[i], **changes)
+        return replace(self, underlyings=tuple(unds))
+
+    def with_spot(self, i: int, spot: float) -> Market:
+        return self._with_underlying(i, spot=spot)
+
+    def with_vol(self, i: int, vol: float) -> Market:
+        return self._with_underlying(i, vol=vol)
+
+    def with_rate(self, rate: float) -> Market:
+        return replace(self, rate=rate)

sppricer/models.py

@@ -0,0 +1,176 @@
+"""Path simulation models: GBM (exact, on product dates) and Dupire local vol (log-Euler)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import numpy as np
+
+from sppricer.market import Curve, Market
+
+
+def _check(times, n_paths: int, antithetic: bool) -> np.ndarray:
+    times = np.asarray(times, dtype=float)
+    if times.ndim != 1 or len(times) == 0:
+        raise ValueError("times must be a non-empty 1-D array")
+    if times[0] <= 0 or np.any(np.diff(times) <= 0):
+        raise ValueError("times must be positive and strictly increasing")
+    if antithetic and n_paths % 2:
+        raise ValueError("n_paths must be even when antithetic=True")
+    return times
+
+
+def simulate_gbm(market: Market, times: np.ndarray, n_paths: int,
+                 seed: int | None = None, antithetic: bool = True) -> np.ndarray:
+    """Simulate correlated geometric Brownian motion at the given times.
+
+    The log-Euler step is exact for GBM, so paths are only generated on the
+    dates the payoff needs (e.g. discrete observation dates). With market.curves
+    set, the drift over each step is ln F(t2) - ln F(t1) - vol^2 dt / 2.
+
+    Returns an array of shape (n_paths, n_times, n_assets). With antithetic=True
+    the first half of the paths uses Z and the second half uses -Z.
+    """
+    times = _check(times, n_paths, antithetic)
+
+    rng = np.random.default_rng(seed)
+    n_draw = n_paths // 2 if antithetic else n_paths
+    z = rng.standard_normal((n_draw, len(times), market.n_assets))
+    if antithetic:
+        z = np.concatenate([z, -z], axis=0)
+
+    chol = np.linalg.cholesky(market.correlation)
+    z = z @ chol.T
+
+    dt = np.diff(np.concatenate([[0.0], times]))[None, :, None]
+    vol = market.vols[None, None, :]
+    if market.curves is None:
+        drift = (market.rate - market.div_yields[None, None, :] - 0.5 * vol**2) * dt
+    else:
+        drift = np.diff(market.log_growth(np.concatenate([[0.0], times])), axis=0)[None] - 0.5 * vol**2 * dt
+    shocks = vol * np.sqrt(dt) * z
+    log_paths = np.log(market.spots)[None, None, :] + np.cumsum(drift + shocks, axis=1)
+    return np.exp(log_paths)
+
+
+class PathModel(Protocol):
+    """Anything that simulates paths at the product's dates for price_mc.
+
+    Must return shape (n_paths, len(times), n_assets) in the antithetic layout
+    (first half Z, second half -Z), which the engine's standard error relies on.
+    """
+
+    def simulate(self, market: Market, times: np.ndarray, n_paths: int,
+                 seed: int | None = None, antithetic: bool = True) -> np.ndarray: ...
+
+
+@dataclass(frozen=True)
+class GBMModel:
+    """Flat-vol GBM, the default model: exactly simulate_gbm."""
+
+    def simulate(self, market: Market, times: np.ndarray, n_paths: int,
+                 seed: int | None = None, antithetic: bool = True) -> np.ndarray:
+        return simulate_gbm(market, times, n_paths, seed, antithetic)
+
+
+class LocalVolSource(Protocol):
+    """A Dupire local-vol surface for one asset and the forward curve it was built on.
+
+    local_vol(K, T) takes absolute strikes (an array) and a time in years and
+    returns the local vol at each; it must be finite on the strikes paths reach
+    (clamp or extrapolate in the surface, not here).
+    """
+
+    curve: Curve
+
+    def local_vol(self, K, T): ...
+
+
+@dataclass(frozen=True)
+class LocalVolModel:
+    """Dupire (1994) local volatility, one surface per asset, simulated by log-Euler.
+
+    The grid is every multiple of dt up to the last product date, plus the product
+    dates; a date already on the dt grid adds no step, so it does not shift the
+    random stream (common random numbers survive a schedule change). Over a step
+    [t0, t1] each asset moves by
+
+        d ln S = ln F(t1) - ln F(t0) - sigma^2 dt / 2 + sigma sqrt(dt) Z,
+        sigma  = local_vol(S(t0), (t0 + t1) / 2),
+
+    with F the surface's forward curve, so the asset grows like its forward (the
+    surface's curve, not market.rate; match market.discount_curve to it). Z is
+    correlated with the market's Cholesky factor, in the antithetic layout.
+    Euler bias is O(dt): halve dt to check it.
+    """
+
+    surfaces: tuple[LocalVolSource, ...]
+    dt: float = 1 / 252
+    n_strikes: int = 401  # strikes per step at which local vol is evaluated, then interpolated in ln K
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "surfaces", tuple(self.surfaces))
+        if not self.dt > 0:
+            raise ValueError("dt must be positive")
+
+    def grid(self, times: np.ndarray) -> np.ndarray:
+        """Simulation grid, starting at 0: multiples of dt below the last date, plus the dates."""
+        times = np.asarray(times, dtype=float)
+        base = self.dt * np.arange(1, int(np.ceil(times[-1] / self.dt - 1e-9)))
+        base = base[np.abs(base[:, None] - times[None, :]).min(axis=1) > 1e-9]
+        return np.concatenate([[0.0], np.sort(np.concatenate([base, times]))])
+
+    def simulate(self, market: Market, times: np.ndarray, n_paths: int,
+                 seed: int | None = None, antithetic: bool = True) -> np.ndarray:
+        """Paths sampled at `times`, shape (n_paths, n_times, n_assets), like simulate_gbm."""
+        return self._run(market, times, n_paths, seed, antithetic, keep_grid=False)[1]
+
+    def simulate_grid(self, market: Market, times: np.ndarray, n_paths: int,
+                      seed: int | None = None, antithetic: bool = True) -> tuple[np.ndarray, np.ndarray]:
+        """(grid, paths on the whole grid), e.g. for barrier monitoring on every step.
+
+        Same random numbers as simulate. Memory is n_paths * len(grid) * n_assets floats.
+        """
+        return self._run(market, times, n_paths, seed, antithetic, keep_grid=True)
+
+    def _run(self, market, times, n_paths, seed, antithetic, keep_grid):
+        times = _check(times, n_paths, antithetic)
+        if len(self.surfaces) != market.n_assets:
+            raise ValueError(f"{len(self.surfaces)} surfaces for {market.n_assets} assets")
+        grid = self.grid(times)
+        sample = np.searchsorted(grid, times)
+        ln_f = np.stack([np.log(s.curve.forward(grid)) for s in self.surfaces], axis=1)
+        chol = np.linalg.cholesky(market.correlation)
+        rng = np.random.default_rng(seed)
+        n_draw = n_paths // 2 if antithetic else n_paths
+
+        log_s = np.tile(np.log(market.spots), (n_paths, 1))
+        out = np.empty((n_paths, len(grid) if keep_grid else len(times), market.n_assets))
+        if keep_grid:
+            out[:, 0] = market.spots
+        j = 0
+        for i in range(1, len(grid)):
+            t0, t1 = grid[i - 1], grid[i]
+            z = rng.standard_normal((n_draw, market.n_assets))
+            z = (np.concatenate([z, -z]) if antithetic else z) @ chol.T
+            sigma = np.column_stack([self._sigma(s, log_s[:, a], 0.5 * (t0 + t1))
+                                     for a, s in enumerate(self.surfaces)])
+            log_s += ln_f[i] - ln_f[i - 1] - 0.5 * sigma**2 * (t1 - t0) + sigma * np.sqrt(t1 - t0) * z
+            if keep_grid:
+                out[:, i] = np.exp(log_s)
+            elif i == sample[j]:
+                out[:, j] = np.exp(log_s)
+                j += 1
+        return grid, out
+
+    def _sigma(self, surface: LocalVolSource, log_s: np.ndarray, t: float) -> np.ndarray:
+        # ponytail: local vol evaluated at n_strikes points spanning today's paths and interpolated
+        # linearly in ln K, not per path; raise n_strikes if a surface has sharp features.
+        lo, hi = float(log_s.min()), float(log_s.max())
+        k = np.linspace(lo, hi, self.n_strikes) if hi > lo else np.array([lo])
+        lv = np.asarray(surface.local_vol(np.exp(k), t), dtype=float) * np.ones_like(k)
+        if not np.all(np.isfinite(lv)):
+            raise ValueError(f"local vol is not finite at t={t:.4f} for strikes the paths reach; "
+                             "clamp or extrapolate the surface (e.g. floor/cap)")
+        return np.interp(log_s, k, lv)

sppricer/products/__init__.py

@@ -0,0 +1,6 @@
+from sppricer.products.autocallable import PhoenixAutocallable
+from sppricer.products.base import Product
+from sppricer.products.reverse_convertible import BarrierReverseConvertible
+from sppricer.products.vanilla import EuropeanOption
+
+__all__ = ["BarrierReverseConvertible", "EuropeanOption", "PhoenixAutocallable", "Product"]

sppricer/products/autocallable.py

@@ -0,0 +1,91 @@
+"""Phoenix autocallable on a worst-of basket."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from sppricer.market import Market
+from sppricer.products.base import (
+    Product,
+    knock_in_probability,
+    validate_monitoring,
+    validate_schedule,
+    worst_performance,
+)
+
+
+@dataclass(frozen=True)
+class PhoenixAutocallable(Product):
+    """Worst-of Phoenix autocallable with optional memory coupon.
+
+    On each observation date t_i (while the note is alive), with W = worst-of
+    performance S_t / S_0:
+      * Coupon: if W >= coupon_barrier, pay notional * coupon_rate
+        (plus any missed coupons if memory=True).
+      * Autocall (from first_autocall_index, before maturity): if
+        W >= autocall_barrier, repay notional and terminate.
+      * Maturity: with barrier_monitoring="european", repay notional if
+        W >= protection_barrier, otherwise notional * W. With "continuous" or
+        "daily", the protection barrier is a knock-in watched over the whole
+        life: if any asset touched it and W < 1, repay notional * W.
+
+    Barriers are expressed as fractions of the initial level (0.7 = 70%).
+    coupon_rate is per observation period (e.g. 0.02 for 2% per quarter).
+    """
+
+    initial_levels: tuple[float, ...]
+    observation_times: tuple[float, ...]
+    coupon_rate: float
+    coupon_barrier: float = 0.70
+    autocall_barrier: float = 1.00
+    protection_barrier: float = 0.60
+    memory: bool = True
+    first_autocall_index: int = 0
+    notional: float = 100.0
+    barrier_monitoring: str = "european"
+
+    def __post_init__(self) -> None:
+        validate_schedule(self.observation_times)
+        validate_monitoring(self.barrier_monitoring)
+        for name in ("coupon_barrier", "autocall_barrier", "protection_barrier"):
+            if getattr(self, name) < 0:
+                raise ValueError(f"{name} must be non-negative")
+        if not 0 <= self.first_autocall_index < len(self.observation_times):
+            raise ValueError("first_autocall_index out of range")
+
+    @property
+    def simulation_times(self) -> np.ndarray:
+        return np.asarray(self.observation_times, dtype=float)
+
+    def discounted_payoff(self, paths: np.ndarray, market: Market) -> np.ndarray:
+        worst = worst_performance(paths, self.initial_levels)
+        n_paths, n_obs = worst.shape
+        alive = np.ones(n_paths, dtype=bool)
+        missed = np.zeros(n_paths, dtype=int)
+        pv = np.zeros(n_paths)
+
+        for i, t in enumerate(self.simulation_times):
+            df = market.discount(t)
+            w = worst[:, i]
+
+            pays_coupon = alive & (w >= self.coupon_barrier)
+            n_coupons = missed + 1 if self.memory else 1
+            pv += np.where(pays_coupon, self.notional * self.coupon_rate * n_coupons, 0.0) * df
+            missed = np.where(alive & ~pays_coupon, missed + 1, 0)
+
+            if i == n_obs - 1:
+                if self.barrier_monitoring == "european":
+                    redemption = np.where(w >= self.protection_barrier, self.notional, self.notional * w)
+                else:
+                    p_ki = knock_in_probability(paths, self.simulation_times, self.initial_levels,
+                                                self.protection_barrier, market, self.barrier_monitoring)
+                    redemption = self.notional * (1.0 - p_ki * np.maximum(1.0 - w, 0.0))
+                pv += np.where(alive, redemption, 0.0) * df
+            elif i >= self.first_autocall_index:
+                called = alive & (w >= self.autocall_barrier)
+                pv += np.where(called, self.notional, 0.0) * df
+                alive &= ~called
+
+        return pv

sppricer/products/base.py

@@ -0,0 +1,79 @@
+"""Product interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from sppricer.market import Market
+
+
+class Product(ABC):
+    """A product defines which dates to simulate and how to value each path.
+
+    `discounted_payoff` receives paths of shape (n_paths, n_times, n_assets),
+    sampled at `simulation_times`, and returns the present value per path.
+    """
+
+    @property
+    @abstractmethod
+    def simulation_times(self) -> np.ndarray: ...
+
+    @abstractmethod
+    def discounted_payoff(self, paths: np.ndarray, market: Market) -> np.ndarray: ...
+
+
+def validate_schedule(times: tuple[float, ...]) -> np.ndarray:
+    arr = np.asarray(times, dtype=float)
+    if arr.ndim != 1 or len(arr) == 0:
+        raise ValueError("schedule must be a non-empty sequence of times")
+    if arr[0] <= 0 or np.any(np.diff(arr) <= 0):
+        raise ValueError("schedule must be positive and strictly increasing")
+    return arr
+
+
+BARRIER_MONITORING = ("european", "continuous", "daily")
+
+# Broadie-Glasserman-Kou: a barrier monitored every dt behaves like a continuous
+# barrier shifted away from spot by exp(-beta * vol * sqrt(dt)), beta = -zeta(1/2)/sqrt(2*pi).
+_BGK_BETA = 0.5826
+
+
+def validate_monitoring(monitoring: str) -> None:
+    if monitoring not in BARRIER_MONITORING:
+        raise ValueError(f"barrier_monitoring must be one of {BARRIER_MONITORING}, got {monitoring!r}")
+
+
+def knock_in_probability(paths: np.ndarray, times: np.ndarray, initial_levels: tuple[float, ...],
+                         barrier: float, market: Market, monitoring: str) -> np.ndarray:
+    """Probability, per path, that any asset touched the down barrier over [0, times[-1]].
+
+    Uses the Brownian-bridge crossing probability between simulated dates,
+    exp(-2 * a * b / (vol^2 * dt)) with a, b the log-distances above the barrier,
+    so paths only need the product's observation dates. "daily" applies the
+    Broadie-Glasserman-Kou shift to match daily closing-price monitoring.
+    """
+    vols = market.vols
+    levels = np.asarray(initial_levels, dtype=float) * barrier
+    if monitoring == "daily":
+        levels = levels * np.exp(-_BGK_BETA * vols * np.sqrt(1 / 252))
+    with np.errstate(divide="ignore"):
+        log_b = np.log(levels)
+    start = np.broadcast_to(np.log(market.spots), (paths.shape[0], 1, paths.shape[2]))
+    dist = np.concatenate([start, np.log(paths)], axis=1) - log_b
+    a, b = np.clip(dist[:, :-1], 0, None), np.clip(dist[:, 1:], 0, None)
+    var = vols**2 * np.diff(np.concatenate([[0.0], times]))[:, None]
+    p_cross = np.exp(-2 * a * b / np.maximum(var, 1e-300))
+    # ponytail: assets' bridges treated as independent given endpoints; slightly overstates
+    # knock-in for positively correlated baskets on coarse grids. Refine the grid if it matters.
+    return 1.0 - np.prod(1.0 - p_cross, axis=(1, 2))
+
+
+def worst_performance(paths: np.ndarray, initial_levels: tuple[float, ...]) -> np.ndarray:
+    """Worst-of performance S_t / S_0 across assets, shape (n_paths, n_times)."""
+    if paths.shape[2] != len(initial_levels):
+        raise ValueError(
+            f"product has {len(initial_levels)} initial levels but market has {paths.shape[2]} assets"
+        )
+    return (paths / np.asarray(initial_levels, dtype=float)).min(axis=2)

sppricer/products/reverse_convertible.py

@@ -0,0 +1,61 @@
+"""Barrier reverse convertible on a worst-of basket."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from sppricer.market import Market
+from sppricer.products.base import (
+    Product,
+    knock_in_probability,
+    validate_monitoring,
+    validate_schedule,
+    worst_performance,
+)
+
+
+@dataclass(frozen=True)
+class BarrierReverseConvertible(Product):
+    """Guaranteed coupons plus a short down-and-in put at maturity.
+
+    Coupons of notional * coupon_rate are paid on every coupon date. At
+    maturity the investor receives notional, unless the put has knocked in
+    and worst-of performance W is below 1, in which case they get notional * W.
+
+    barrier_monitoring:
+      * "european": knocked in if W < knock_in_barrier at maturity only.
+      * "continuous" / "daily": knocked in if any asset touched the barrier at
+        any time (daily closes for "daily"), via a Brownian-bridge correction
+        on the coupon-date grid.
+    """
+
+    initial_levels: tuple[float, ...]
+    coupon_times: tuple[float, ...]
+    coupon_rate: float
+    knock_in_barrier: float = 0.60
+    notional: float = 100.0
+    barrier_monitoring: str = "european"
+
+    def __post_init__(self) -> None:
+        validate_schedule(self.coupon_times)
+        validate_monitoring(self.barrier_monitoring)
+
+    @property
+    def simulation_times(self) -> np.ndarray:
+        if self.barrier_monitoring == "european":
+            return np.array([self.coupon_times[-1]])
+        return np.asarray(self.coupon_times, dtype=float)
+
+    def discounted_payoff(self, paths: np.ndarray, market: Market) -> np.ndarray:
+        times = np.asarray(self.coupon_times, dtype=float)
+        coupons_pv = self.notional * self.coupon_rate * np.sum(market.discount(times))
+        w = worst_performance(paths, self.initial_levels)[:, -1]
+        if self.barrier_monitoring == "european":
+            redemption = np.where(w >= self.knock_in_barrier, self.notional, self.notional * w)
+        else:
+            p_ki = knock_in_probability(paths, self.simulation_times, self.initial_levels,
+                                        self.knock_in_barrier, market, self.barrier_monitoring)
+            redemption = self.notional * (1.0 - p_ki * np.maximum(1.0 - w, 0.0))
+        return coupons_pv + redemption * market.discount(times[-1])

sppricer/products/vanilla.py

@@ -0,0 +1,27 @@
+"""European vanilla options (benchmark product for engine validation)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from sppricer.market import Market
+from sppricer.products.base import Product
+
+
+@dataclass(frozen=True)
+class EuropeanOption(Product):
+    strike: float
+    maturity: float
+    is_call: bool = True
+    asset_index: int = 0
+
+    @property
+    def simulation_times(self) -> np.ndarray:
+        return np.array([self.maturity])
+
+    def discounted_payoff(self, paths: np.ndarray, market: Market) -> np.ndarray:
+        s_t = paths[:, -1, self.asset_index]
+        intrinsic = s_t - self.strike if self.is_call else self.strike - s_t
+        return np.maximum(intrinsic, 0.0) * market.discount(self.maturity)

sppricer-0.2.1.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: sppricer
+Version: 0.2.1
+Summary: Monte Carlo pricing and risk for structured products (autocallables, reverse convertibles)
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hossainyousuf751/sp-pricer
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# sppricer
+
+![tests](https://github.com/hossainyousuf751/sp-pricer/actions/workflows/ci.yml/badge.svg)
+
+Monte Carlo pricing and risk for retail structured products: worst-of Phoenix
+autocallables and barrier reverse convertibles. The goal is a transparent,
+tested engine that answers a practical question: **what is a structured note
+actually worth compared with its issue price?**
+
+## Quickstart
+
+```bash
+pip install sppricer                       # from PyPI
+pip install -e ".[dev]"                    # or, from a clone, for development
+pytest
+python examples/price_worst_of_phoenix.py
+```
+
+```python
+import numpy as np
+from sppricer import Market, Underlying, PhoenixAutocallable, price_mc, bump_greeks
+
+market = Market(
+    (Underlying("STOCK_A", 100.0, 0.25, 0.02), Underlying("STOCK_B", 50.0, 0.30, 0.015)),
+    rate=0.04,
+    correlation=np.array([[1.0, 0.6], [0.6, 1.0]]),
+)
+note = PhoenixAutocallable(
+    initial_levels=(100.0, 50.0),
+    observation_times=tuple(0.25 * k for k in range(1, 13)),
+    coupon_rate=0.02, coupon_barrier=0.70, autocall_barrier=1.00,
+    protection_barrier=0.60, memory=True, first_autocall_index=3,
+)
+print(price_mc(note, market, n_paths=400_000, seed=42))
+```
+
+Example output (3-year, quarterly, 8% p.a. memory coupon, 60% European protection):
+
+| Metric | Value |
+|---|---|
+| Fair value per 100 notional | 93.88 ± 0.07 (95% CI) |
+| Implied issuer margin | ~6.1 |
+| Fair value, barrier on daily closes | 90.58 ± 0.06 |
+| Vega per vol point (A / B) | −0.44 / −0.54 |
+
+The investor is short volatility and short gamma, which is the defining risk of
+these products: the coupon is compensation for the down-and-in put the investor sells.
+
+## Barrier monitoring
+
+Both structured products take `barrier_monitoring`:
+
+- `"european"` (default): barrier checked at maturity only.
+- `"continuous"`: knock-in if any asset ever touches the barrier.
+- `"daily"`: knock-in on daily closes, which is what most term sheets specify.
+
+Paths are still simulated only on observation dates. The chance of crossing
+between them comes from the Brownian-bridge formula, and `"daily"` adds the
+Broadie-Glasserman-Kou barrier shift. The tests check this against a brute-force
+daily simulation using the same random paths. Daily monitoring takes about 3.3
+points off the example note, so a maturity-only barrier noticeably overstates its value.
+
+## Local volatility and term structure (v0.2, M6)
+
+Every product here is short a down-and-in put, so its value depends on the put skew, which flat
+vol ignores. `price_mc(product, market, model=...)` takes any `PathModel`: `GBMModel` (the default,
+identical numbers) or `LocalVolModel`, a Dupire (1994) local-vol simulation.
+
+```python
+from sppricer import LocalVolModel, price_mc
+
+model = LocalVolModel([surface_a, surface_b], dt=1 / 252)  # any objects with local_vol(K, T) and .curve
+price_mc(note, market, n_paths=200_000, seed=42, model=model)
+```
+
+- **No dependency on a surface library.** A surface is anything with `local_vol(K, T)` (absolute
+  strike, years) and a `curve` with `forward(T)` / `discount(T)` (the `LocalVolSource` protocol).
+  [quant-stack](https://github.com/hossainyousuf751/quant-stack) wires in volsurface's SSVI surfaces.
+- **Scheme.** Log-Euler on a grid of every dt plus every observation date. Each step drifts by
+  ln F(t+dt) − ln F(t) − ½σ²dt, so the asset tracks its forward curve, with σ = local vol at the
+  current spot and the step's mid-time. Correlation uses the market's Cholesky factor, and
+  antithetic sampling is kept, so standard errors and common random numbers work as before.
+  The bias is O(dt): the tests check that it shrinks when dt halves.
+- **Term structure.** `Market(..., curves=(...), discount_curve=...)` replaces the flat rate and
+  dividend yield by forward and discount curves. GBM then drifts along each asset's forward, and
+  products discount with `market.discount`.
+- **Barriers.** Daily or continuous monitoring uses a Brownian-bridge correction that assumes
+  flat GBM vol between dates, so `price_mc` raises under local vol. With local vol, use
+  `"european"` monitoring, or `LocalVolModel.simulate_grid` to monitor on every step.
+
+## Design
+
+| Module | Responsibility |
+|---|---|
+| `market.py` | Immutable market snapshot: spots, flat vols, dividend yields, rate (or forward/discount curves), correlation (validated PSD) |
+| `models.py` | Correlated GBM via Cholesky, exact log-step on observation dates only, antithetic variates; Dupire local vol (log-Euler) behind the same `PathModel` interface |
+| `products/` | Each product declares its simulation dates and a vectorized `discounted_payoff(paths, market)` |
+| `engine.py` | MC pricing with correct standard errors under antithetic sampling |
+| `greeks.py` | Central-difference Greeks with common random numbers |
+| `analytics.py` | Black-Scholes closed forms used as benchmarks |
+
+Adding a product means implementing two methods; the engine and Greeks work unchanged.
+
+## Validation
+
+The test suite checks the engine against cases with known answers:
+
+- European call/put prices converge to Black-Scholes within 4 standard errors.
+- Put-call parity holds; antithetic sampling reduces standard error.
+- Bump-and-reprice delta and vega match Black-Scholes analytics.
+- Limit cases: unreachable barriers give a zero-coupon bond; zero barriers give an immediate
+  call; full downside with no coupons gives the discounted forward; a zero-barrier BRC gives a coupon bond.
+- Monotonicity: memory coupons are worth more; worst-of is cheaper than single-asset;
+  european > daily > continuous barrier monitoring.
+- The daily-monitoring Brownian-bridge estimator matches brute-force daily simulation
+  (single asset and basket) within 4 standard errors.
+
+## Roadmap
+
+Done: M1 core engine, M2 Greeks, M4 continuous barriers, M6 local vol and curves, T1 tooling.
+Next: issuer funding spread, variance reduction. Full plan with acceptance criteria in [ROADMAP.md](https://github.com/hossainyousuf751/sp-pricer/blob/main/ROADMAP.md); how to
+contribute in [CONTRIBUTING.md](https://github.com/hossainyousuf751/sp-pricer/blob/main/CONTRIBUTING.md).
+
+## Limitations
+
+Under the default flat volatility, the skew is ignored, which understates the value of the
+short down-and-in put. Fair values are therefore biased upward relative to a skew-aware model.
+`LocalVolModel` removes that bias given a surface. Under local vol, `bump_greeks` vega is zero,
+so bump the surface instead. Barrier monitoring must be European.
+Dividends are continuous yields, and there is no issuer credit spread (funding
+discounting), which matters materially for real notes. For baskets, the
+Brownian-bridge correction treats each asset's path between observation dates as
+independent, which slightly overstates knock-in on coarse grids (about 0.03 on the test basket).
+
+## Part of quant-stack
+
+sp-pricer is one of five independent libraries linked in
+[quant-stack](https://github.com/hossainyousuf751/quant-stack). There, volsurface surfaces drive
+`LocalVolModel` (study S1, skew and the autocallable), and risk-lab revalues sp-pricer notes for
+VaR. sp-pricer itself depends only on numpy.
+
+## Disclaimer
+
+Educational project. All examples use synthetic or publicly available term sheets.

sppricer-0.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+sppricer/__init__.py,sha256=NjxY4kNNpPDouCWQZaFIMUZRYWgYz2Sk41MT2LQZYX0,870
+sppricer/analytics.py,sha256=Tcyj5cL95N-qZAg9zaiWEaVcU5g8Q9How7Uc6XH9Mt8,1694
+sppricer/engine.py,sha256=A1LygGPChJj0X0DS9xY9sYUlaJBT9z5h61Kz0Dn2Wfs,2035
+sppricer/greeks.py,sha256=wZDFeY8pw46HcD2GnQcnwxcRr7VNuGXS8zRJyBqcQPk,2222
+sppricer/market.py,sha256=qlasMQWdrKMvxJwH-tarBDLLX8g6NAkkPy0HHQF_uXc,4589
+sppricer/models.py,sha256=-pEi4uQEW1q21YYIdIRhiFHLFnDCAUvkywto6Dq6icc,7978
+sppricer/products/__init__.py,sha256=jUXHD3epbnJPidrKKOghdFgVMGGZLxkccRdEj9MV_Bk,328
+sppricer/products/autocallable.py,sha256=ynGbVg0AMStvKrutL0bc6yx5jj_7SeH-GBkuZDVJxC4,3690
+sppricer/products/base.py,sha256=JHKVgeSNEqYqi7fYr_LvZPty7Kah5-n84VjljQMvPVc,3307
+sppricer/products/reverse_convertible.py,sha256=qtdiLtLLkIQDKQAiHuv3G_Cn8e1HUYrEsrF8rePu6r4,2342
+sppricer/products/vanilla.py,sha256=GuHfjQTHg_d2Oe7_ABfPmqo09cRhlDjokfxnlyfhNLs,771
+sppricer-0.2.1.dist-info/licenses/LICENSE,sha256=OAV_RTERHYKJrtHIxvr_VWUiM6k-1PKksx8ezi9wMmY,1079
+sppricer-0.2.1.dist-info/METADATA,sha256=WRMxdroOtKnrayp6KCm_gXAaLYBxONSC2ae1R9yQyAw,7776
+sppricer-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sppricer-0.2.1.dist-info/top_level.txt,sha256=QclH6L3OcpB_bbB68y6q6XuEIsFMQcDYLIFcyZPtJWY,9
+sppricer-0.2.1.dist-info/RECORD,,

sppricer-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sppricer-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousuf Hossain Shafeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sppricer-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+sppricer