sppricer 0.2.1__tar.gz

sppricer-0.2.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,144 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sppricer"
+version = "0.2.1"
+description = "Monte Carlo pricing and risk for structured products (autocallables, reverse convertibles)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["numpy>=1.24"]
+
+[project.urls]
+Repository = "https://github.com/hossainyousuf751/sp-pricer"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov>=4", "ruff>=0.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: README-scale runs (seconds to minutes); run with -m slow"]
+addopts = "-m 'not slow'"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]

sppricer-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sppricer-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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)