quantark 0.2.5__tar.gz → 0.3.0__tar.gz

quantark-0.3.0/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/).
+During 0.x the public API may still change between minor versions.
+
+## [0.3.0] - 2026-07-20
+
+First release of the `quantark.execution` framework kernel and the
+`quantark.execution.greeks` scenario layer. The `test_snowball_quad_flat_identity_golden`
+failure predates this program and remains quarantined (reproduces on
+unmodified main). The spec §20 controlled-host performance gates in
+`docs/execution/README.md` are documented as release-preparation evidence
+and were not re-measured on the release host.
+
+### Added
+- **`quantark.execution.greeks` — greek bumps as scenario cells** (spec
+  2026-07-20): `TradeState` per-trade base, same-type `greek-bump/v1`
+  transformer with real spot/vol/rate/div/time mutation attribution,
+  `greek-value/v1` float runner, and assemblers mirroring
+  `EquityPosition.get_trade_risk` / `GreeksCalculator.
+  calculate_numerical_greeks` operation-for-operation (bitwise unit gate).
+- **`PricingSession.run_scenario_plans`** — many `(base, specs)` plans
+  packed through ONE bounded-window process pool (per-cell worker-spec
+  payloads; the portfolio × bumps shape), with a per-plan error boundary
+  under `collect_errors=True` (base-resolution/planning failures become
+  aligned typed `PricingFailure`s while other plans execute).
+- **`quantark.execution` — composable execution kernel** (framework contract
+  v1; spec `docs/superpowers/specs/2026-07-15-mc-pde-performance-generalization-design.md`).
+  `PricingSession` wraps every exported MC/PDE engine without changing direct
+  legacy behavior: adapter registry, resource budgets/leases, prepared-artifact
+  and session draw caches, reproducibility manifests and immutable diagnostics.
+  Capabilities: fixed-batch MC backends (serial/threads, bit-identical
+  reductions in canonical order), adaptive RQMC session mode (bitwise vs
+  direct across the 12 autocallable vol engines), PDE preparation artifacts
+  (grids, step coefficients, factorization packs; one-solve PV/event/grid
+  outputs across 18 prepared engines + FX LV), typed scenario execution with
+  verified mutation footprints, spawn-safe `WorkerSpec` process workers, a
+  Dask backend over the same plans, `price_many` grouping, and a
+  complete-payload scenario validator. Published artifacts: generated
+  [capability matrix](docs/execution/capability-matrix.md) (CI-fresh), policy
+  guide, legacy-internals rationale, reproducibility JSON Schemas (validated
+  against live payloads), and runnable migration examples. Adoption is
+  inventory-driven and honest: `temporary_legacy` rows remain, and no
+  universal framework support is claimed until the controlled-host gates pass.
+- **DCN (Digital Coupon Note)**: product + observation-schedule generator,
+  curve-aware MC engine with leg decomposition and event stats, two-surface
+  PDE engine with MC↔PDE cross-validation gates, LocalVol/Heston/QE/SLV DCN
+  MC engines sharing one payoff kernel, MLMC-style coupled timestep-ladder
+  Heston pair, SVI/cleaned-quote calibration layers with no-arbitrage and
+  repricing-residual reports, node-bump vega buckets and carry-invariant rate
+  bumps.
+- **Implied futures carry**: `IndexFuturesCurve` implied q(T), futures-tenor
+  delta/rhoq buckets, delta-one futures rhoq, portfolio aggregation and hedge
+  integration.
+- **Engine term-structure upgrade**: MC, PDE, and quadrature autocallable
+  engines consume full r/q/vol term structures with a cross-family term
+  agreement gate.
+- **Vol-model barrier exotics**: LV/Heston/SLV barrier MC pricers on a shared
+  monitoring core, LV 1D barrier PDE, Heston/SLV 2D barrier ADI solvers.
+- **Vol-model numerics program (phases 2–5)**: vectorized Lewis Heston
+  calibration (~21x), unified Heston/SLV ADI core, opt-in Krylov and TR-BDF2
+  Fokker–Planck marches, opt-in QE-M martingale correction, concentrated
+  (x,v) grids, degenerate v=0 Feller boundary, LV Rannacher start-up
+  (default on), opt-in QMC sampling for Heston/SLV/LV kernels.
+- **PDE event-stats API** on Snowball/Phoenix vol solvers with event
+  distributions surfaced through session outputs.
+
+### Changed
+- DCN MC engine performance: draw cache, batched threads, LV build hoist.
+- The legacy autocallable Dask batch loop (Snowball vanilla/KO-reset,
+  Phoenix) is consolidated into one shared reducer
+  (`autocallable_dask_batch`) with byte-preserved behavior, gated by frozen
+  bitwise goldens. The legacy `use_dask` route itself is unchanged and
+  preserved (see `docs/execution/internals-and-legacy.md` for the §17.3
+  removal preconditions).
+- Dev extras now include `dask[distributed]` and `jsonschema`.
+
+### Fixed
+- `PhoenixMCEngine` silently disabled its Dask parallel path on modern dask
+  (`from dask.compute import compute` no longer resolves); availability now
+  matches `SnowballMCEngine`, with a regression test.
+- Processes scenario backend: a parent whose `__main__` cannot be
+  re-imported by spawn children (stdin/heredoc scripts record
+  `__file__ = '<stdin>'`; deleted script files) now fails closed with a
+  typed `CapabilityError` before any worker is spawned, instead of every
+  child dying at bootstrap and surfacing as an opaque
+  `BrokenProcessPool` with zero completed cells.
+- Craig–Sneyd ADI corrector order restored (base `Y0` + implicit `-rU`),
+  QE sampler sign bug, and the 2026-07 PDE/QUAD audit fixes (13 findings)
+  are included via the programs above.
+
+## [0.2.5] - 2026-07-03
+
+### Fixed
+- 2026-07 PDE/QUAD audit: 13 numerical findings fixed (discrete-monitoring
+  boundary handling, Rannacher terminal off-by-one, BGK state resolution,
+  smoothed KI for Phoenix/KO-reset, shared theta damping schedule) with
+  solver-family consolidation and regression tests.
+
+## [0.2.4] - 2026-07-02
+
+### Added
+- Opt-in BGK continuous-KI mode for Snowball and Phoenix PDE solvers
+  (direction-aware shifted barrier, per-product flag).
+- `EquityPosition.get_trade_risk` (product + total, frozen one-loop) and
+  `AutocallableCashLeg.time_shift`; event streams selected by leg
+  requirements.
+
+### Fixed
+- Portfolio vega/rho/dividend-rho aligned with the canonical greek
+  convention; bump contexts freeze PDE critical points for grid steadiness.
+
+## [0.2.3] - 2026-07-01
+
+### Added
+- Cross-engine-consistent `ki_ever` / `ki_survive` event-stat fields.
+
+### Fixed
+- Theta advances by business day; quadrature event-stats recursion uses
+  smoothed barrier indicators.
+
+## [0.2.2] - 2026-07-01
+
+### Fixed
+- PDE numerical Greeks: freeze the base spatial domain for finite-difference
+  bump repricing so rho and dividend rho measure market sensitivity without
+  contamination from auto-grid/domain movement under bumped rate, dividend,
+  volatility, or time inputs.
+
+## [0.2.1] - 2026-06-30
+
+### Fixed
+- `PhoenixPDESolver`: apply a KO observation scheduled exactly at maturity.
+  The inherited grid builder stores the maturity KO in `_ko_terminal_record`
+  (intentionally kept out of `_ko_observation_indices`), but the Phoenix
+  `_solve` override looked the terminal KO up in `_ko_observation_indices`
+  and therefore dropped it — mispricing products with a terminal KO date by
+  several percent versus the quadrature and Monte Carlo engines. Terminal KO
+  is now applied after the terminal coupon/KI jumps (matching
+  `SnowballPDESolver._solve`), routed through `_apply_ko_jump_vector` so the
+  same-date coupon-at-KO payoff is preserved.
+
+## [0.1.2] - 2026-06-13
+
+### Added
+- Credit dual-measure framework: a recovery convention layer
+  (`quantark.asset.credit.conventions`, `STANDARD_RECOVERY=0.40`) that
+  separates the canonical shared-curve **hazard01** factor from the
+  recovery-converted **CS01** used by products and SIMM. Curve shocks stay
+  in hazard space; spread stresses convert through the recovery convention.
+- Single-name CDS **roll-down / as-of pricing** via effective and maturity
+  dates (seasoned and forward-start), with `schedule_asof` and a
+  total-return coupon cash ledger threaded through the dynamic-scenario and
+  backtest engines. SIMM buckets the remaining tenor. (Basket as-of is
+  deferred.)
+
+## [0.1.1] - 2026-06-11
+
+### Added
+- `SnowballQuadEngine`: explicit `ki_monitoring_mode` on `QuadParams`
+  (`KnockInMonitoringMode`). `EXACT_DISCRETE` (default) prices every KI
+  observation date exactly with adaptive spatial-grid refinement.
+  `BGK_APPROXIMATION` is an opt-in performance mode that replaces a dense
+  discrete KI schedule with continuous monitoring at a
+  Broadie-Glasserman-Kou shifted barrier; the engine validates approximately
+  regular spacing (median-band dispersion test), a constant resolved
+  barrier, full-horizon coverage, stable volatility, and a minimum schedule
+  density (`bgk_min_ki_observations`), raising `ValidationError` otherwise.
+  Converted pricing matches the equivalent shifted-continuous product
+  exactly (grid-aligned to the shifted barrier) while the valuation-time KI
+  state keeps contractual discrete semantics. A first-order residual bias
+  remains (a few bp of PV at daily spacing, growing with observation
+  spacing and drift).
+
+### Fixed
+- `SnowballQuadEngine`: dense discrete KI schedules now retain their explicit
+  observation dates instead of being delegated to continuous monitoring. The
+  engine adaptively refines its internal spatial grid to resolve short
+  diffusion intervals (accuracy-oriented default of 2.5 cells per interval
+  diffusion stddev; lower to 1.25 or opt into BGK for speed), avoiding the
+  material fair-KO-rate bias caused by the previous continuous-monitoring
+  approximation.
+
+## [0.1.0] - 2026-06-11
+
+### Added
+- First public release.
+- Equity derivatives: European/American/Asian vanilla options, barrier,
+  one-touch, digital, sharkfin, and autocallable products (snowball,
+  phoenix, KO-reset snowball, range accrual) with analytical, Monte
+  Carlo, PDE, quadrature, and tree engines.
+- Fixed income: fixed bonds, FRNs, bond options, bond forwards/futures,
+  convertible bonds, interest rate swaps.
+- Market data layer (`quantark.param`, `quantark.priceenv`), Greeks
+  calculators, portfolio VaR (parametric/historical/Monte Carlo),
+  ISDA SIMM v2.6, stress testing, multi-day scenario simulation, and a
+  hedging backtest framework.
+- Legacy flat-import compatibility shim (`asset`, `util`, …) with
+  `DeprecationWarning`; slated for removal in 1.0.

{quantark-0.2.5 → quantark-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantark
-Version: 0.2.5
+Version: 0.3.0
 Summary: Modular derivatives pricing and risk library: options, autocallables, bonds, VaR, SIMM
 Project-URL: Homepage, https://github.com/deiiiiii93/quantark
 Project-URL: Repository, https://github.com/deiiiiii93/quantark
@@ -34,6 +34,8 @@ Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: scipy>=1.10.0
 Requires-Dist: seaborn>=0.12.0
 Provides-Extra: dev
+Requires-Dist: dask[distributed]>=2024.1.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown

quantark-0.3.0/docs/execution/README.md

@@ -0,0 +1,82 @@
+# QuantArk execution framework
+
+`quantark.execution` is the composable execution kernel for QuantArk's MC and
+PDE engines: one immutable plan per request, explicit resource budgets,
+deterministic reproduction manifests, and session-level batch / adaptive /
+prepared-artifact / scenario execution — while every direct legacy call keeps
+its exact historical behavior (framework contract v1, no deprecations).
+
+```python
+from quantark.execution import PricingSession
+
+with PricingSession() as session:
+    pv = session.price(engine, product, pricing_env)   # == engine.price(...)
+```
+
+Spec of record:
+`docs/superpowers/specs/2026-07-15-mc-pde-performance-generalization-design.md`.
+
+## Documents
+
+- [Capability matrix](capability-matrix.md) — generated per-engine
+  batch/adaptive/prepared adoption states with rationales
+  (`python -m quantark.execution.capability_matrix`; CI-enforced freshness).
+- [Policy guide](policy-guide.md) — precedence, environment variables,
+  budgets, backend × capability matrix.
+- [Internals and legacy duplicates](internals-and-legacy.md) — what is
+  unified, what deliberately remains duplicated and under which removal
+  preconditions (spec §17.3).
+- [Reproducibility schemas](schemas/) — JSON Schemas for the WorkerSpec,
+  scenario-cell, manifest, and normalized-economics payloads, validated
+  against live payloads in CI.
+- Migration examples — `example/execution_session_demo.py` and
+  `example/execution_scenarios_demo.py` (runnable; exercised by
+  `test/execution/test_examples.py`).
+
+## Performance snapshots
+
+Dev-machine (Apple Silicon, macOS) measurements from the Phase 6 exit rerun,
+2026-07-18, via `test/execution/benchmark_phase{2,4,5}.py`. These are
+**documentation, not gate passes** — the spec §20 release gates run on the
+controlled host with production-sized workloads (see the pre-tag checklist
+below).
+
+- **Fixed-batch MC** (DCN, 2^17 paths, 16 batches, cold draws): session
+  threads 2.29x @4 workers (PASS vs the 1.5x dev floor); 2.13x @8 workers —
+  host-limited (the direct legacy `num_workers=8` path is no faster on this
+  machine; ≥2.5x@8 needs the controlled host). Framework adds no threading
+  overhead vs engine-internal threads (worst ratio 1.04). CRN draw reuse
+  2.04x (PASS vs 2x). Serial overhead −0.2%.
+- **PDE prepared artifacts** (CRN x10 LV-snowball, 58 ms solves): session
+  1.29x vs uncached direct — march-dominated small fixture; the ≥2x gate is
+  sized for production grids on the controlled host. Warm-session single
+  European dispatch overhead: −9.7% (session faster) at a 0.8 ms solve.
+- **Scenario processes** (9-cell surface-shock menu, 4096 paths, 4 spawn
+  workers): median 1.63x vs serial with **194/194 normalized fields
+  matching in every rep**; tiny cells put spawn+import fixed costs and the
+  heaviest cell on the critical path — the ≥2.5x gate runs on >10s serial
+  grids on the controlled host.
+
+## Before tagging v0.3.0
+
+This phase produces **release-preparation evidence only** — pushing a tag IS
+publishing (`.github/workflows/release.yml` is tag-triggered), so the
+version is pinned at `0.3.0rc1` until every prerequisite below is met
+(Codex code-gate 2026-07-18: a final version must not exist while gates are
+open). Outstanding hard prerequisites before any `v0.3.0` tag:
+
+0. **Finalize the version**: flip `0.3.0rc1` → `0.3.0` in `pyproject.toml`
+   and `quantark/__init__.py` only after items 1–3 pass.
+
+1. **Controlled-host performance gates** (spec §20): ≥2x fixed-batch MC at 4
+   workers on >10s serial workloads, ≥2x PDE CRN-sweep production gate, and
+   ≥2.5x scenario/process gate — measured on the controlled multi-core host,
+   not this dev machine (dev snapshots below are documentation, not gate
+   passes).
+2. **Full-suite green**: resolve or explicitly quarantine (with written
+   rationale) the pre-existing
+   `test_snowball_quad_flat_identity_golden` failure — it predates the
+   execution-framework program and reproduces on unmodified main, but a tag
+   must not ship a red suite silently.
+3. **Wheel-artifact compatibility**: the otc-price-adapter suite green
+   against the installed candidate wheel at the tagged commit.

quantark-0.3.0/example/mo_volmodels/README.md

@@ -0,0 +1,104 @@
+# MO Options Vol-Model Calibration Suite
+
+A hands-on, staged example that calibrates **Dupire Local Volatility**, **Heston**, and
+**Heston Stochastic-Local Volatility (SLV)** to real **CSI 1000 index option (MO / 中证1000股指期权,
+underlying `000852.SH`)** market data pulled via AKShare, and renders the whole study as a
+self-contained HTML lecture.
+
+The models are European index options — no early exercise — which is exactly the clean setting
+Dupire / Heston / SLV assume.
+
+## The interpreter split (important)
+
+Two Python environments are involved and **no single interpreter has both** libraries:
+
+| Stage | Interpreter | Why |
+|-------|-------------|-----|
+| `01` fetch | `/opt/anaconda3/bin/python` | has `akshare`, no `quantark` |
+| `02`–`09` | `.venv/bin/python` | has `quantark`, no `akshare` |
+
+Stage 01 is the only script that touches the network; it writes a JSON **snapshot** that stages
+02–09 replay **offline**. A committed synthetic `mo_snapshot_sample.json` (arbitrage-free by
+construction) drives the automated tests and lets 02–09 run with no network at all.
+
+## Running it
+
+```bash
+# 1) live fetch — AKShare interpreter (optional; the sample snapshot works offline)
+/opt/anaconda3/bin/python example/mo_volmodels/01_fetch_mo_snapshot.py
+
+# 2-9) replay the snapshot — quantark .venv
+.venv/bin/python example/mo_volmodels/02_build_iv_surface.py  --snapshot latest
+.venv/bin/python example/mo_volmodels/03_dupire_localvol.py   --tag latest --vol-floor 0.05
+.venv/bin/python example/mo_volmodels/04_heston_calibration.py --tag latest
+.venv/bin/python example/mo_volmodels/05_slv_calibration.py    --tag latest --vol-floor 0.05
+.venv/bin/python example/mo_volmodels/07_barrier_exotic.py     --tag latest --vol-floor 0.05
+.venv/bin/python example/mo_volmodels/08_snowball_exotic.py    --tag latest --vol-floor 0.05
+.venv/bin/python example/mo_volmodels/09_delta_hedging.py      --tag latest --vol-floor 0.05
+.venv/bin/python example/mo_volmodels/06_lecture.py           --tag latest
+```
+
+Open the result: **`data/mo_volmodels_lecture_latest.html`**.
+
+Every artifact is keyed by a `--tag` (`latest` for live data, `sample` for the deterministic
+fixture) so the test pipeline and the live pipeline never clobber each other's files.
+
+## Stages
+
+| Script | Does |
+|--------|------|
+| `01_fetch_mo_snapshot.py` | AKShare MO chain + CSI 1000 spot → `data/mo_snapshot_*.json` |
+| `02_build_iv_surface.py`  | **put-call parity** → r(T)/forward/carry; **OTM filter**; call-equivalent Black-IV inversion → `GridVolSurface` |
+| `03_dupire_localvol.py`   | Dupire σ_LV(K,T); reprice via local-vol PDE; RMSE + surface plot |
+| `04_heston_calibration.py`| calibrate (v0,κ,θ,σ,ρ); Feller check; smile-fit plot + RMSE |
+| `05_slv_calibration.py`   | Fokker-Planck leverage surface L(S,t); reprice via SLV PDE + plot |
+| `07_barrier_exotic.py`    | up-and-out call priced **MC and PDE** under BSM/LV/Heston/SLV → model-divergence table + bar chart |
+| `08_snowball_exotic.py`   | 2Y principal-excluded standard Snowball priced **MC and PDE** under BSM/LV/Heston QE/SLV plus standalone SLV QE MC → autocallable model-divergence table + bar chart |
+| `09_delta_hedging.py`     | ATM European call delta-neutral hedge demo under BSM flat vol/LV/Heston/SLV → hedge inventory, turnover, residual PnL + chart |
+| `06_lecture.py`           | weave everything into the HTML lecture + comparison CSV |
+| `_mo_common.py`           | shared helpers (snapshot IO, parity, OTM filter, IV inversion, env build, leverage, plots) |
+
+Stage 07 exercises the standalone barrier engines added to `quantark`
+(`quantark/volmodels/barrier.py` + the `*BarrierMCEngine` / `*BarrierPDESolver` classes under
+`quantark/asset/equity/engine/`), which price a single-barrier option under Local Vol, Heston,
+and SLV by both Monte Carlo and 2-D ADI PDE. Run it after stage 05:
+`.venv/bin/python example/mo_volmodels/07_barrier_exotic.py --tag latest --vol-floor 0.05`.
+
+Stage 08 exercises the Snowball vol-model engines under the same MO surface with a 2Y,
+principal-excluded standard Snowball. It reports BSM, Local Vol, Heston QE, and SLV with
+MC/PDE cross-checks where available, plus the standalone SLV QE MC engine for the
+QE-specific stochastic-local-vol path scheme:
+`.venv/bin/python example/mo_volmodels/08_snowball_exotic.py --tag latest --vol-floor 0.05`.
+
+Stage 09 isolates hedging behavior. It adds a BSM flat-vol baseline, then holds the
+calibrated LV surface, Heston parameters, and SLV leverage surface fixed while walking
+the same deterministic spot path for an ATM European call and rebalancing to delta
+neutral under each model:
+`.venv/bin/python example/mo_volmodels/09_delta_hedging.py --tag latest --vol-floor 0.05`.
+
+## What the real data teaches
+
+- **Negative basis.** The MO forward sits well below spot and falls with maturity; the parity
+  regression recovers a large implied carry `q` (10–20%) — not dividends, but the CSI 1000 futures
+  discount driven by structured-product hedging flows.
+- **Raw quotes are not arbitrage-free.** Building Dupire directly hits butterfly-arbitrage
+  rejections at the wings/short end. The exact path *stops* (no fabricated local vol); the pipeline
+  opts into a small `--vol-floor`. A desk would arbitrage-free the smile (SVI/SABR) first.
+- **Parameter identification.** The Heston smile only weakly pins κ vs σ with few maturities — we
+  regularize (cap κ, Feller penalty) rather than overfit.
+- **Objective ↔ numerics coupling.** An unconstrained Heston is deeply Feller-violated, and that
+  same extreme σ makes the ADI PDE mis-price by ~2 vol-pts. A Feller-aware calibration keeps both
+  the fit and the PDE trustworthy.
+- **Which model for which product.** SLV does *not* out-reprice vanillas vs analytic Heston (the SLV
+  PDE has an inherent discretization bias). SLV's value is smile-consistent *dynamics* for **exotics**
+  (barriers, autocallables, forward-vol); the leverage surface is the reusable deliverable.
+
+## Tests
+
+```bash
+.venv/bin/python -m pytest test/mo_volmodels/ -v
+```
+
+All tests run on the deterministic `sample` snapshot (offline). See
+`docs/superpowers/specs/2026-07-06-mo-volmodels-calibration-suite-design.md` and the matching
+plan for the design rationale, and `quantark/volmodels/` for the model kernels.

{quantark-0.2.5 → quantark-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quantark"
-version = "0.2.5"
+version = "0.3.0"
 description = "Modular derivatives pricing and risk library: options, autocallables, bonds, VaR, SIMM"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -42,7 +42,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=7.0.0", "pytest-xdist>=3.0.0"]
+dev = ["pytest>=7.0.0", "pytest-xdist>=3.0.0", "dask[distributed]>=2024.1.0", "jsonschema>=4.0"]
 
 [project.urls]
 Homepage = "https://github.com/deiiiiii93/quantark"

{quantark-0.2.5 → quantark-0.3.0}/quantark/__init__.py

@@ -1,3 +1,3 @@
 """QuantArk: professional financial derivatives pricing library."""
 
-__version__ = "0.2.5"
+__version__ = "0.3.0"

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/__init__.py

@@ -3,6 +3,12 @@ Pricing engines for equity derivatives.
 """
 
 from .base_engine import BaseEngine
+from .capabilities import (
+    EngineCapability,
+    VolDynamicsType,
+    get_engine_capability,
+    validate_engine_capability,
+)
 from .analytical import (
     BlackScholesEngine,
     BarrierAnalyticalEngine,
@@ -15,6 +21,12 @@ from .pde_engine import PDEEngine
 from .mc import (
     EuropeanMCEngine,
     AmericanOptionMCEngine,
+    DCNMCEngine,
+    LocalVolDCNMCEngine,
+    CoupledCoarseHestonDCNMCEngine,
+    HestonDCNMCEngine,
+    QEDCNMCEngine,
+    coupled_heston_ladder_pair,
     SnowballMCEngine,
     PhoenixMCEngine,
     DigitalOptionMCEngine,
@@ -23,6 +35,16 @@ from .mc import (
     LocalVolMCEngine,
     HestonMCEngine,
     HestonSLVMCEngine,
+    LocalVolSnowballMCEngine,
+    HestonSnowballMCEngine,
+    QESnowballMCEngine,
+    HestonSLVSnowballMCEngine,
+    HestonSLVQESnowballMCEngine,
+    LocalVolPhoenixMCEngine,
+    HestonPhoenixMCEngine,
+    QEPhoenixMCEngine,
+    HestonSLVPhoenixMCEngine,
+    HestonSLVQEPhoenixMCEngine,
 )
 from .pde import (
     BasePDESolver,
@@ -37,6 +59,12 @@ from .pde import (
     LocalVolPDESolver,
     HestonPDESolver,
     HestonSLVPDESolver,
+    LocalVolSnowballPDESolver,
+    HestonSnowballPDESolver,
+    HestonSLVSnowballPDESolver,
+    LocalVolPhoenixPDESolver,
+    HestonPhoenixPDESolver,
+    HestonSLVPhoenixPDESolver,
     TimeGrid,
     SpatialGrid,
 )
@@ -52,6 +80,10 @@ from .quad import (
 __all__ = [
     # Base
     "BaseEngine",
+    "EngineCapability",
+    "VolDynamicsType",
+    "get_engine_capability",
+    "validate_engine_capability",
     # Analytical
     "BlackScholesEngine",
     "BarrierAnalyticalEngine",
@@ -62,6 +94,12 @@ __all__ = [
     # Monte Carlo
     "EuropeanMCEngine",
     "AmericanOptionMCEngine",
+    "DCNMCEngine",
+    "LocalVolDCNMCEngine",
+    "CoupledCoarseHestonDCNMCEngine",
+    "HestonDCNMCEngine",
+    "QEDCNMCEngine",
+    "coupled_heston_ladder_pair",
     "SnowballMCEngine",
     "PhoenixMCEngine",
     "DigitalOptionMCEngine",
@@ -70,6 +108,16 @@ __all__ = [
     "LocalVolMCEngine",
     "HestonMCEngine",
     "HestonSLVMCEngine",
+    "LocalVolSnowballMCEngine",
+    "HestonSnowballMCEngine",
+    "QESnowballMCEngine",
+    "HestonSLVSnowballMCEngine",
+    "HestonSLVQESnowballMCEngine",
+    "LocalVolPhoenixMCEngine",
+    "HestonPhoenixMCEngine",
+    "QEPhoenixMCEngine",
+    "HestonSLVPhoenixMCEngine",
+    "HestonSLVQEPhoenixMCEngine",
     # Unified PDE Engine
     "PDEEngine",
     # PDE Solvers
@@ -85,6 +133,12 @@ __all__ = [
     "LocalVolPDESolver",
     "HestonPDESolver",
     "HestonSLVPDESolver",
+    "LocalVolSnowballPDESolver",
+    "HestonSnowballPDESolver",
+    "HestonSLVSnowballPDESolver",
+    "LocalVolPhoenixPDESolver",
+    "HestonPhoenixPDESolver",
+    "HestonSLVPhoenixPDESolver",
     # Grid utilities
     "TimeGrid",
     "SpatialGrid",

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/accumulator_analytical_engine.py

@@ -354,8 +354,6 @@ class AccumulatorAnalyticalEngine(BaseEngine):
             raise ValidationError(
                 f"Maturity too long for analytical accumulator pricing: {maturity}"
             )
-        if div < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {div}")
         if abs(rate) > 1.0:
             raise ValidationError(f"Risk-free rate outside reasonable bounds: {rate}")
 

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/black_scholes_engine.py

@@ -154,8 +154,6 @@ class BlackScholesEngine(BaseEngine):
             raise ValidationError(
                 f"Volatility too high for numerical stability: {sigma}"
             )
-        if q < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {q}")
 
         # Check for extreme parameter combinations
         if abs(r) > 1.0:

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/deltaone_engine.py

@@ -267,6 +267,13 @@ class DeltaOneEngine(BaseEngine):
             greeks["vega"] = 0.0
             greeks["theta"] = 0.0  # Market price is fixed
             greeks["rho"] = 0.0  # Market price independent of model rate
+            # Dividend rho at the carry implied by the observed mark:
+            # q_impl = r - ln(F_mkt/S)/T (basis folded into carry), so
+            # dF/dq = -S*T*exp((r - q_impl)*T) = -T*F_mkt. Per 1% q change.
+            implied_q = r - math.log(product.market_price / S) / T
+            greeks["dividend_rho"] = (
+                -S * T * math.exp((r - implied_q) * T) * 0.01
+            )
             return greeks
         
         # Theoretical Greeks
@@ -299,7 +306,11 @@ class DeltaOneEngine(BaseEngine):
         # Rho: derivative with respect to rate
         # dF/dr = S*T*exp((r-q)*T)
         greeks["rho"] = S * T * math.exp(carry_cost)
-        
+
+        # Dividend rho: dF/dq = -S*T*exp((r-q)*T); basis term is q-independent.
+        # Per 1% q change; negative for long futures (higher carry lowers F).
+        greeks["dividend_rho"] = -S * T * math.exp(carry_cost) * 0.01
+
         return greeks
     
     def get_forward_price(

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/digital_option_engine.py

@@ -176,8 +176,6 @@ class DigitalOptionAnalyticalEngine(BaseEngine):
             raise ValidationError(
                 f"Volatility {sigma} outside supported range [{self.MIN_VOL}, {self.MAX_VOL}]"
             )
-        if q < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {q}")
         if abs(r) > 1.0:
             raise ValidationError(f"Risk-free rate outside reasonable bounds: {r}")
         if T > self.MAX_MATURITY:

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/double_barrier_option_engine.py

@@ -474,8 +474,6 @@ class DoubleBarrierOptionAnalyticalEngine(BaseEngine):
         if abs(r) > 1.0:
             raise ValidationError(f"Risk-free rate outside reasonable bounds: {r}")
 
-        if q < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {q}")
 
     def __repr__(self):
         return "DoubleBarrierOptionAnalyticalEngine()"

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/double_sharkfin_option_analytical_engine.py

@@ -499,8 +499,6 @@ class DoubleSharkfinOptionAnalyticalEngine(BaseEngine):
             raise ValidationError(
                 f"Maturity too long for analytical double sharkfin pricing: {maturity}"
             )
-        if div < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {div}")
         if abs(rate) > 1.0:
             raise ValidationError(f"Risk-free rate outside reasonable bounds: {rate}")
 

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/range_accrual_analytical_engine.py

@@ -272,8 +272,6 @@ class RangeAccrualAnalyticalEngine(BaseEngine):
             raise ValidationError(f"Spot price must be positive, got {S}")
         if T < 0:
             raise ValidationError(f"Time to maturity must be non-negative, got {T}")
-        if q < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {q}")
         if abs(r) > 1.0:
             raise ValidationError(
                 f"Risk-free rate outside reasonable bounds: {r}"

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/analytical/single_sharkfin_option_analytical_engine.py

@@ -220,8 +220,6 @@ class SingleSharkfinOptionAnalyticalEngine(BaseEngine):
             raise ValidationError(
                 f"Maturity too long for analytical sharkfin pricing: {maturity}"
             )
-        if div < 0:
-            raise ValidationError(f"Dividend yield must be non-negative, got {div}")
         if abs(rate) > 1.0:
             raise ValidationError(f"Risk-free rate outside reasonable bounds: {rate}")
 

{quantark-0.2.5 → quantark-0.3.0}/quantark/asset/equity/engine/base_engine.py

@@ -64,6 +64,19 @@ class BaseEngine(ABC):
         """
         return self
 
+    def execute(self, request, context):
+        """Route a framework ``PricingRequest`` through the execution kernel.
+
+        Non-abstract compatibility entry point (execution-framework spec
+        section 5.4). Existing subclasses need no change; the kernel resolves
+        a capability adapter for this engine and falls back to the serial
+        LegacyPriceAdapter. Direct ``price``/``price_detailed`` calls are
+        unaffected.
+        """
+        from quantark.execution.kernel import ExecutionKernel
+
+        return ExecutionKernel.dispatch(self, request, context)
+
     def price_with_events(
         self,
         product: BaseEquityProduct,