QuantArk — Financial Derivatives Pricing & Risk Library
A modular, professional-grade Python library for pricing and risk management of financial derivatives.
Overview
QuantArk spans five asset classes (equity, bond, rate, FX, credit) and a full risk-and-capital stack, all built on a clean, modular architecture that separates concerns across composable layers:
- Products: Define instrument specifications (options, swaps, bonds, CDS, etc.)
- Processes: Stochastic models (Black-Scholes-Merton, Heston, Local Vol, SLV, Garman-Kohlhagen, hazard-rate)
- Engines: Pricing algorithms (Analytical, Monte Carlo, PDE, Quadrature, Tree)
- Parameters: Market data (spot prices, volatility surfaces incl. SABR / Vanna-Volga, rate curves, dividends)
- PriceEnv: Unified pricing environment bundling all market data
- RiskMeasures: Greeks calculation (both analytical and numerical)
- Risk & Capital: VaR, stress testing, dynamic scenarios, hedging backtests, and regulatory capital (ISDA SIMM, SA-CCR, SA-CVA)
Features
Current Implementation
Equity derivatives
- Vanilla: European and American options (analytical BS93/BS02/BAW, MC LSM, PDE)
- Asian, Digital, Barrier, Double-Barrier, One-Touch, Double-One-Touch options
- Autocallables: Snowball, Phoenix, KO-Reset Snowball (MC, PDE, Quad engines)
- Structured: Range Accrual, Accumulator, Single/Double Sharkfin
- Total Return Swaps: single-asset, multi-asset, and dual-currency, with realized-cashflow accounting
- Delta-One: spot instruments and futures
Stochastic models & engines
- Processes: Black-Scholes-Merton (continuous dividend yield), Heston, Local Vol (Dupire), Stochastic Local Vol (SLV)
- Engines: Analytical (closed-form), Monte Carlo (QMC — Sobol, Brownian bridge, randomized QMC, antithetic/control-variate variance reduction), PDE (finite-difference, banded solvers), Quadrature, Tree
- Shared MC layer (
quantark/montecarlo/): reusable QMC path generation across equity and FX
Fixed income
- Bonds: fixed-rate coupon bonds, FRNs, convertible bonds, bond forwards, bond futures, bond options
- Interest rate: swaps (IRS), FRAs, caps/floors, swaptions — with DV01 / key-rate risk
FX derivatives
- Garman-Kohlhagen vanilla, digital, and quanto (vanilla / digital) options with two-curve discounting
- Path-dependent / exotic: barrier, one-touch, sharkfin, range accrual (domestic / quanto / foreign), target-redemption forwards & notes (TARF / TARN)
- Smile models: SABR (Hagan) and Vanna-Volga, plus an FX-Heston analytical engine
- Delta-one: spot / forward / swap products
Credit derivatives
- CDS and basket CDS priced off a hazard-rate curve (model-agnostic engine), with hazard01 / CS01 sensitivities
Risk, scenario & regulatory capital
- Portfolio VaR: Historical (full revaluation), Parametric (variance-covariance with Greeks/DV01), and Monte Carlo — with risk-factor attribution and a backtesting framework
- Stress testing: scenario-based shocks across all asset classes
- Dynamic scenarios: multi-day path simulation
- Hedging backtests: delta / DV01 / convexity-neutral strategies (equity / FI / FX)
- ISDA SIMM v2.6: initial margin with CRIF, calibration, and dashboard
- SA-CCR: Basel counterparty EAD (RC + PFE)
- SA-CVA: Basel (MAR50) SBA CVA capital
- Portfolios: equity, fixed income, FX, and credit position tracking — one position object feeds the entire risk stack
Intraday pricing
- Timestamp valuation (
quantark.intraday): timezone-aware valuation instants on a trading-session calendar with a sub-day variance profile, confirmed and assumed (provisional) fixings, and a structured result that separates the contingent claim, pending receivables and paid cash - Routes for digitals, barriers/one-touches and autocallables through QUAD V2, PDE, MC and admissible closed forms, each reporting its numerical status (PDE resolution, MC sampling error); point and desk-bump Greeks, a declared-step intraday theta, roll-through-events scenarios, spot curves and batch aggregation
- Evidence: an independent Gaussian-transition reference gates every route on a one-day-to-one-second
time-to-fixing ladder; see
quantark/intraday/README.mdand the generated intraday capability matrix
Cross-cutting
- Greeks: analytical (closed-form) and numerical (finite-difference) — Delta, Gamma, Vega, Theta, Rho, DV01
- Robust error handling: professional exception hierarchy
- Numerical stability: shared
quantark.util.numericaltoolkit (protected math, tolerance-aware comparisons), careful boundary checking and validation
Key Design Principles
- Modularity: Each component is independent and reusable
- Extensibility: Easy to add new products, processes, and engines
- Type Safety: Extensive use of dataclasses and type hints
- Validation: Input validation at every level
- Professional Exception Handling: Custom exception hierarchy for different error types
Installation
pip install quantark
From source / latest development version:
pip install git+https://github.com/deiiiiii93/quantark
Version numbers. This README and the CHANGELOG name behaviour changes by the milestones 0.6.0 to 0.10.0 (for example "the 0.7.0 base-family mask"). Those were internal milestones that were never published; they all ship in 0.5.5, the first release after 0.5.0. The next release after 0.5.5 is 0.11.0 (unified event statistics), numbered past those milestone labels so that no version is reused.
Optional accelerator (Numba): pip install "quantark[accel]" compiles the Monte Carlo QE
kernels and the PDE mesh builder. Results are bit-identical with or without it; a cold PDE
solve is faster with it.
For development (editable install with test tooling):
git clone https://github.com/deiiiiii93/quantark && cd quantark
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
Migration note: imports use the quantark.* namespace
(from quantark.util.enum import OptionType). The historical flat
top-level packages (asset, util, param, …) still work through a
compatibility shim that aliases them to the same modules and emits a
DeprecationWarning — migrate existing code to quantark.* at your
convenience.
Quick Start
from quantark.asset.equity.product.option import EuropeanVanillaOption
from datetime import datetime
from quantark.asset.equity.engine.analytical import BlackScholesEngine
from quantark.asset.equity.riskmeasures import GreeksCalculator
from quantark.param import SpotQuote, FlatVolSurface, FlatRateCurve, ContinuousDividendYield
from quantark.priceenv import PricingEnvironment
from quantark.util.enum import OptionType
# Set up market data
spot = SpotQuote(spot=100.0)
vol = FlatVolSurface(volatility=0.20) # 20% vol
rate = FlatRateCurve(rate=0.05) # 5% risk-free rate
div = ContinuousDividendYield(div_yield=0.02) # 2% dividend yield
pricing_env = PricingEnvironment(
spot_quote=spot,
vol_surface=vol,
rate_curve=rate,
div_yield=div,
valuation_date=datetime(2024, 1, 1),
)
# Create a European call option
call_option = EuropeanVanillaOption(
strike=100.0,
maturity=1.0, # 1 year
option_type=OptionType.CALL
)
# Price the option
engine = BlackScholesEngine()
price = engine.price(call_option, pricing_env)
print(f"Call Price: ${price:.6f}")
# Calculate Greeks
greeks_calc = GreeksCalculator()
analytical_greeks = greeks_calc.calculate_analytical_greeks(
call_option, pricing_env, price
)
print(f"Delta: {analytical_greeks['delta']:.6f}")
print(f"Gamma: {analytical_greeks['gamma']:.6f}")
print(f"Vega: {analytical_greeks['vega']:.6f}")
print(f"Theta: {analytical_greeks['theta']:.6f} (per day)")
print(f"Rho: {analytical_greeks['rho']:.6f}")
FX Options
from datetime import datetime
from quantark.asset.fx.engine.analytical import GarmanKohlhagenEngine
from quantark.asset.fx.product import CurrencyPair
from quantark.asset.fx.product.option import FxVanillaOption
from quantark.param import SpotQuote, FlatVolSurface, FlatRateCurve
from quantark.priceenv import FxPricingEnvironment
from quantark.util.enum import OptionType
fx_env = FxPricingEnvironment(
valuation_date=datetime(2026, 6, 12),
spot_quote=SpotQuote(spot=1.20), # EUR/USD
domestic_curve=FlatRateCurve(rate=0.05), # USD
foreign_curve=FlatRateCurve(rate=0.03), # EUR
vol_surface=FlatVolSurface(volatility=0.10),
)
option = FxVanillaOption(
currency_pair=CurrencyPair("EUR", "USD"),
strike=1.25,
option_type=OptionType.CALL,
maturity=1.0,
notional_foreign=1_000_000.0, # 1m EUR
)
engine = GarmanKohlhagenEngine()
print(f"Price: {engine.price(option, fx_env):,.2f} USD")
print(f"Delta: {engine.calculate_greeks(option, fx_env)['delta']:,.2f} EUR")
See example/asset/fx/fx_vanilla_option_demo.py, example/asset/fx/fx_digital_option_demo.py,
example/asset/fx/fx_quanto_option_demo.py, and example/asset/fx/fx_deltaone_demo.py for
digitals, quantos, and delta-one products.
For portfolio Value-at-Risk (parametric, historical, and Monte Carlo engines
with risk-factor attribution), see the runnable demos:
example/var/parametric_var_demo.py, example/var/portfolio_var_demo.py, and
example/var/var_backtest_demo.py.
Batch-Friendly Engine Params
For QUAD batch pricing, you can use named presets, factory helpers, or YAML/JSON
configs instead of tuning many individual parameters. PDE has no profile tier:
PDEParams is small enough to write out, and PDEParams.from_config reads the
same field names from a mapping, YAML, or JSON.
from quantark.asset.equity.engine.pde import GridConfig
from quantark.asset.equity.param import PDEParams, make_quad_params
quad_params = make_quad_params(profile="barrier_sensitive")
pde_params = PDEParams(accuracy="standard")
pde_barrier = PDEParams(grid=GridConfig(points=600, steps_per_day=6.0))
pde_loaded = PDEParams.from_config({"accuracy": "high", "grid": {"time_steps": 800}})
Quad presets accept either preset names or explicit config objects; see the docstrings in quantark/asset/equity/param/ for the full schema.
PDE parameters (0.8.0)
Every 1D PDE route (PDEEngine and its solvers, the local-vol vanilla and barrier
solvers, DCN) is configured by one PDEParams, keyword arguments only:
| Field | When to change it | What happens |
|---|---|---|
accuracy |
A faster preview or a finer answer. | Selects the GridConfig preset: fast (200 pts, 4/day), standard (400, 4/day), high (800, 8/day). |
grid |
Override one preset field. | Each non-None GridConfig field replaces that preset value; the rest inherit. |
stepper |
A different time weighting or damping schedule, or you are writing a stepper. | None is the built-in CrankNicolson() (below). A custom stepper runs on every 1D route. |
operator |
You are writing an operator (an exponentially fitted stencil, say). | None is the built-in CentralDifference(): the central-difference tridiagonal with upwind rows on zero-diffusion steps. |
readout |
You are writing a readout. | None is the built-in StandardReadout(): linear price interpolation, delta and gamma from the local cubic. |
event_projection |
Validating the event treatment. | None is "cell_average" on every core route: the autocallables, the barrier / double-barrier / one-touch / double-one-touch discrete observations, and the DCN's daily dates. "nodal" assigns whole nodes (the 0.7.0 base-family mask). Continuous monitoring and a valuation-date observation stay nodal either way. |
cache_enabled |
Memory pressure, or a fresh solve every call. | The same numbers to round-off: a cached run shares one factorization across intervals whose dt differ by an ULP. |
CrankNicolson (quantark.asset.equity.engine.pde.core.components) carries the
scheme's settings:
| Setting | When to change it | What happens |
|---|---|---|
theta (0.5) |
Ringing that damping does not cure, or a more diffusive scheme. | 0.5 is Crank-Nicolson (second order), 1.0 backward Euler (first order). |
event_theta (1.0) |
Studying damping strength after events. | The weight on the event-damped steps after each interior event. |
damping (None) |
See "Damping" below. | "half_step": each damped interval is split in two; both halves take event_theta below an event and 1.0 at the terminal node; "full_step": whole damped steps. None is the route's form. |
terminal_damping_steps (None) |
Checking the payoff kink's smoothing. | Damped intervals off the payoff; None is the route's count, 0 disables. |
event_damping_steps (None) |
Studying damping strength after events. | Damped intervals below each interior event node; None is the route's count, 0 disables. |
The route defaults (DAMPING_DEFAULTS, form, terminal count, event count):
| Route | Default |
|---|---|
| Core, product without continuous knock-in | half-step, 1, 1 |
| Core, product with continuous knock-in | full-step, 1, 2 |
| 2D (Heston, SLV) | full-step, 1, 2 |
Every 1D route is a core route, DCN and the local-vol vanilla and barrier included (0.10.0 removed their own rows).
The class is read from the contract alone (continuous_knock_in), never from the spot or
the knocked-in state, so a spot bump cannot change it. A count means intervals of the
form in force: CrankNicolson(event_damping_steps=2) with no form gives two halved
intervals on every core solve without continuous knock-in, where 0.7.0 gave two whole
steps; under continuous knock-in it keeps its 0.7.0 meaning. damping="full_step" with
explicit counts restores the old meaning everywhere; on its own it takes the route's counts,
(full_step, 1, 1) on the core, which 0.7.0 never used. The 0.7.0 schedule is pde_070 below.
A CrankNicolson subclass is a custom stepper, used as given: set all three fields.
from quantark.asset.equity.engine.pde.core.components import CrankNicolson
pde_euler = PDEParams(stepper=CrankNicolson(theta=1.0))
pde_070 = PDEParams(stepper=CrankNicolson(damping="full_step", terminal_damping_steps=1, event_damping_steps=2))
pde_loaded = PDEParams.from_config({"accuracy": "high", "stepper": {"terminal_damping_steps": 0}})
Damping: when to change it. Time error at standard against each case's own limit
(pv unless stated; spec docs/superpowers/specs/2026-10-01-pde-1d-numerical-policy-design.md §4.2):
| Case | Full-step (1, 2) | Two intervals halved | Half-step (1, 1), the default | Undamped |
|---|---|---|---|---|
| European | −8.8e-7 | −8.8e-7 | −3.0e-7 | +2.8e-7 |
| Barrier, monthly | +3.6e-5 | +1.8e-5 | +7.4e-6 | −3.1e-6 |
| Snowball, monthly discrete KI | +9.5e-5 | +4.8e-5 | +2.3e-5 | −2.2e-6 |
| Snowball, daily KI | +3.0e-3 | +1.5e-3 | +6.3e-4 | +4.3e-5 |
| Snowball, daily KI, spot 86: delta | +1.1e-3 | +5.3e-4 | +1.5e-4 | −2.1e-4 |
| Snowball, daily KI, spot 86: gamma | −5.6e-4 | −2.2e-4 | +1.5e-4 | −1.2e-3 |
Undamped Crank-Nicolson has the smallest pv error and the worst gamma next to a barrier. Under discrete knock-in the half-step default cuts the pv time error three to eight times on the Phoenix and KO-reset too (flat market, daily KI: Phoenix +3.7e-3 → +7.4e-4, KO-reset +1.9e-3 → +3.9e-4) and on the local-vol Snowball and Phoenix (calm surface, daily KI: +9.6e-3 → +2.0e-3). It costs one extra step per event and one at the terminal node: daily KI goes from 1,008 to 1,260 steps. Where it is worse, and stays the default:
- gamma one point above a daily knock-in barrier on the local-vol calm surface at
standard (Snowball 3.7e-4 → 1.5e-3, Phoenix 1.8e-4 → 1.6e-3); pv improves seven times
and delta eleven to thirteen times in the same cells, and the Snowball's gamma is better
from 8 steps per day. Raise
steps_per_dayif that gamma matters; - delta and gamma on the local-vol crash surface at spot 102.5%, under a coupon barrier at 102.9% and a KO barrier at 103% (1.7e-5 to 4.9e-5 and 4.6e-5); pv improves six times.
The local-vol Phoenix takes the half-step default with the core, but no certification study covers it: it is not a certified route.
Products with continuous knock-in keep full-step: there the first-passage correction
needs sigma * sqrt(dt) larger than a cell, and half-step moved seven of nine resolved
cases away from an exact reference. On a continuous-knock-in product, refine points
together with steps_per_day: time-only refinement drifts (Snowball ordinary
96.46045, 96.46211, 96.46310, 96.46417 at 8, 16, 32, 64 steps per day). The correction
carries an error of its own that joint refinement does not remove: about 5e-4 contracts in
pv on the certified cases, 9e-3 on a three-month Snowball, 1.3e-2 at 8% volatility one
point above the barrier.
Projection. A discrete observation of the barrier family enters each dual cell at the record's exact level instead of overwriting whole nodes. Monthly observations, flat market, against exact-GBM Monte Carlo (spec §4.6):
| Product | Nodal mask (0.7.0), 400 points | Dual-cell projection, 400 points |
|---|---|---|
| Up-and-out call, K 100, B 130 | −0.81%, −21 SE | −0.05%, −1.2 SE |
| Down-and-in put, K 100, B 85 | +0.22%, +8.8 SE | +0.05%, +2.2 SE (the far-field row; fixed in 0.8.0) |
| Double knock-out call, K 100, (80, 120) | +1.89%, +34 SE | +0.01%, +0.2 SE |
| One-touch up 115 | +0.03%, +1.5 SE (+0.9% at 200 points) | −0.02%, −0.9 SE |
| Double one-touch (85, 115) | −0.45%, −28 SE | −0.02%, −1.1 SE |
Greeks, largest error at 400 points over 93 knock-out and touch cells against an exact recursion:
| First observation in | Quantity | Nodal (0.7.0) | Projection | Projection and half-step (0.8.0) |
|---|---|---|---|---|
| 1 month | pv | 4.1e-2 | 1.5e-4 | 1.7e-4 |
| grid delta / gamma | 1.7e-3 / 2.2e-4 | 1.8e-5 / 1.9e-6 | 9.8e-6 / 1.7e-6 | |
| 5 days | pv | 5.3e-2 | 3.2e-4 | 2.1e-4 |
| grid delta / gamma | 1.9e-3 / 8.3e-4 | 1.8e-4 / 7.2e-5 | 4.9e-5 / 2.2e-5 | |
| 1 day | pv | 4.5e-2 | 7.9e-3 | 1.1e-3 |
| grid delta / gamma | 9.4e-3 / 9.7e-3 | 3.4e-3 / 9.1e-3 | 8.5e-4 / 1.8e-3 |
GridConfig fields: points, steps_per_day (a density per business day of the
pricing environment: PricingEnvironment.bus_days_in_year, carried on
GridRequest.day_count) or time_steps (a total budget over the horizon; exactly one
time basis is in force), eps_crit, num_std, bounds, max_points, max_steps.
A 244-day environment gives a one-year Snowball 972 steps where a 252-day one gives
1,008.
max_steps (12,000) caps the delivered step count, half-step nodes included. A grid over
it raises ValidationError naming the count it needs and both fixes, raise
GridConfig(max_steps=...) or lower steps_per_day; it is never scaled down. A
five-year high Snowball asks 10,080 and fits; on a 252-day environment the default cap
holds a little under six years at high and twelve at standard (half-step nodes count),
and a six-year monthly Snowball at high raises where 0.7.0 scaled it.
Since 0.10.0 every 1D route honours every field. The local-vol vanilla and barrier
solvers, DCNPDEEngine and LocalVolDCNPDEEngine march on the shared core with the
shared presets, the cell-average projection, the core's damping rows, the shared domain
rule and the built-in readout, and take a custom stepper, operator or readout like any
other 1D solver. quantark.asset.equity.engine.pde.route_applicability.ROUTE_RULES keeps
one row, the 2D Heston / SLV autocallables': they damp in whole steps, and an explicit
damping="half_step" raises ValidationError there. What the shared presets mean on
the moved routes:
- The local-vol vanilla and continuously monitored barrier take the core's time density,
not 0.9.0's step budget (200 at
fastandstandard, 400 athigh).GridConfig(time_steps=200)restores thestandardbudget at a cost (price units at spot 100) of at most 1.4e-5 on a vanilla and 3.4e-5 on a continuous barrier, but up to 5.4e-4 monthly, 4.3e-3 weekly and 2.6e-2 daily. - A daily monitored barrier at
standard(4 steps per day) carries about 1e-3 of time error: +9.3e-4 / +2.1e-4 / +1.1e-5 at 4 / 8 / 16 steps per day on a constant local-vol surface. UseGridConfig(steps_per_day=8.0)where that matters. - The DCN takes the shared presets (200 / 400 / 800 points, 4 / 4 / 8 steps per day) in
place of its own table: at most 0.38 / 0.35 / 0.10 bp of notional against an exact
recursion on 24 cells, where 0.9.0's engine was off by up to 5.2 / 7.2 / 7.7 bp and did
not converge in the point count.
DCNPDEResult.num_time_stepsis the delivered step count. - An explicit
boundsbelongs well beyond a barrier: a far-field row is a constant, and next to a barrier a constant is wrong (by −0.09 to −0.13 on the autocallables' row and 0.1 to 3.3 on the single barrier's).
docs/engine_param_guide.md gives the measurements behind these numbers.
What will this solve do? explain(product, pricing_env) on PDEEngine and every
1D solver returns the resolved plan from the same preparation price runs,
without marching: route, every setting with its source and applicability, space, time,
events, scheme, outputs, identities, and per-operation terminal outcomes. An excerpt of
str(SnowballPDESolver(PDEParams()).explain(snowball, env)) for a one-year monthly
snowball with continuous knock-in in a flat environment:
[route]
solver SnowballPDESolver
adapter SnowballAdapter
samples scalar
solve_state (('ki_barrier', 85.0), ('ki_continuous', True), ('knocked_in', False), ('reverse', False))
[time]
basis steps_per_day
value 4.0
day_count 252
requested_steps 1008
actual_steps 1008
mandatory_nodes 11
[scheme]
stepper CrankNicolson
resolved {'theta': 0.5, 'event_theta': 1.0, 'terminal_damping_steps': 1, 'event_damping_steps': 2, 'damping': 'full_step'}
terminal_damped_steps 1
event_damped_steps 22
theta_counts {0.5: 985, 1.0: 23}
zero_diffusion_steps 0
[outputs]
groups ({'name': 'value', 'surfaces': ('alive', 'ki'), 'columns': 2, 'backend': 'banded', 'retention': 'full'},)
readout final column
Names removed in 0.8.0:
| Removed | Replacement |
|---|---|
GridConfig(day_count=...) (raises ValidationError) |
PricingEnvironment(bus_days_in_year=...): the grid day is the environment's business days |
TimeLayout.fill_scaled, .cap_exceeded; the same keys in explain and on LifeSurfaceSolution |
none: a grid over max_steps raises |
groups.VALUE_NO_ZERO_DIFFUSION_OVERRIDE |
groups.VALUE (Phoenix now takes θ = 1 on zero-diffusion steps) |
The names removed in 0.6.0, 0.7.0 and 0.10.0 (among them GridLayerMixin, the local-vol
and DCN preset tables and resolve_config(profiles=)) are listed in CHANGELOG.md. How the solvers share
one core, and how to write a custom component, is in docs/pde-core.md.
PDE event statistics (0.9.0)
The 1D Snowball, Phoenix and KO-reset solvers (and their local-vol variants) march the statistics in the price's own groups, so the cashflows add up to the price:
from quantark.asset.equity.engine.pde import SnowballPDESolver, HestonSnowballPDESolver
stats = SnowballPDESolver(PDEParams()).calculate_event_stats(snowball, env)
# pv = Σ knock-out cash + Σ coupon cash + the marched maturity leg, to round-off
assert abs(stats.reconciliation_error) <= 1e-10
stats.provenance # StatisticsProvenance(statistics_model='flat_vol_1d', price_model='flat_vol_1d')
# 2D Heston / SLV solvers have no native statistics: they raise StatisticsRefused unless asked
# for the flat-vol 1D surrogate, whose provenance names both models
heston = HestonSnowballPDESolver(heston_params, params=PDEParams(), statistics="flat_vol_surrogate")
Field semantics (the knock-in fields, the Phoenix memory and EXPIRY coupon cash, the
KO-reset maturity buckets, the valuation-date rules) are in
quantark/asset/equity/engine/docs/autocallable_event_stats_api.md.
Accrual time (unreleased)
An autocallable's cash depends on its accrual terms only. Each knock-out, coupon and knock-in
record carries an AccrualPeriod derived when the product is built: a numeric schedule accrues
its quoted fraction (k/12 is 1/12 per period), a dated one the contract's day count from
initial_date. Ageing or re-timing an observation never moves the cash.
from quantark.asset.equity.product.option.snowball_config import AccrualConfig
from quantark.util.enum import AccrualEndType
AccrualConfig(accrual_end=AccrualEndType.SETTLEMENT) # accrue to the payment date, not the fixing
AccrualConfig(accrual_calendar=cal, accrual_bus_days_in_year=244) # required for a BUSINESS_DAYS accrual
A dated contract with annualized cash needs initial_date. After changing a built product's
accrual terms or schedules, call product.validate() to derive its periods again.
Cash-leg folding (unreleased)
Cash legs on an autocallable position normally price on the event route: one
price_with_events solve per bump, the legs valued on its event distribution. With
cash_leg_folding set, the legs are folded into the product's own payoff instead (cash on each
knock-out record and maturity branch), so one plain solve prices product and legs together.
Snowball, Phoenix and KO-reset fold on PDE (1D, local vol, Heston/SLV 2D), Monte Carlo (incl.
its vol-model subclasses), QUAD v1 and QUAD V2; DCN folds on its MC and PDE engines.
from quantark.asset.equity.riskmeasures import GreeksCalculator
from quantark.cashleg import FoldMode
from quantark.portfolio import EquityPosition
pos = EquityPosition(product=snowball, engine=engine, quantity=1, cash_legs=legs,
entry_price=0.0, underlying="CSI500", entry_timestamp=valuation_date,
cash_leg_folding=FoldMode.TOTAL) # or FoldMode.DRILLDOWN
risk = pos.get_trade_risk(env, GreeksCalculator())
risk.total # trade greeks; DRILLDOWN adds risk.product, risk.leg_pvs, risk.leg_greeks
None(default) keeps the event route exactly; a position without legs ignores the flag.TOTALreports trade totals only — 1.75–4× faster than the event route on QUAD and PDE (example/case_studies/engine_benchmarks/cash_leg_folding_benchmark.py), about even on MC (one simulation either way).DRILLDOWNalso reports the product and each leg: per bump one plain solve, one folded solve with all legs and one per event-dependent leg — slower than the event route, which values every leg from one solve. It is refused where two solves may not share a discretization (MC RQMC / Dask, QUAD v1auto_converge).- Folding is exact: a leg's cash per event comes from its own
value()probed on unit event distributions.DeterministicLeg,AccrualLeg,FixedPayoffLeg(knock-out / maturity triggers) andAutocallableCashLeg(knock-out / maturity basis) fold. - These refuse instead of approximating — price them on the event route: an
AT_KItrigger or a COUPON-basis leg (CapabilityError); a REBASED KO-reset; QUAD V2 withevent_phase="after"or a terminated lifecycle state; the Heston conditional-moment / SLV control MC routes on a product with a terminal settlement lag; and a KO-reset handed to the 2D Heston Snowball PDE, which marches one knock-out schedule (its cash cannot bind). - The execution kernel takes the same switch:
TradeState(..., fold_mode=FoldMode.TOTAL).
Andreasen–Huge local vol (unreleased, opt-in)
build_dupire_local_vol evaluates Dupire only at the quoted maturities and interpolates in
between, so its surface does not reprice its own input: on the 2024-02-08 CSI1000 fixture the
production LV PDE overprices the 8-day quotes by about +19 vol points and the 316-day quotes by
+1.5. build_andreasen_huge_local_vol takes the same arguments and reprices every quote
(Andreasen & Huge, "Volatility interpolation", 2011): one implicit forward-Dupire step per
expiry, calibrated exactly, with the local vol read as Dupire on the resulting price surface.
from quantark.volmodels.localvol import (
AndreasenHugeConfig, build_andreasen_huge_local_vol, calibrate_andreasen_huge,
)
lv = build_andreasen_huge_local_vol(env.vol_surface, spot=env.spot, rate_curve=env.rate_curve,
div_yield=env.get_div_yield) # a LocalVolSurface
engine = LocalVolPDESolver(params=params, local_vol_surface=lv) # any LV engine (MC: sub-daily steps early)
ah = calibrate_andreasen_huge(env.vol_surface, env.spot, env.rate_curve, env.get_div_yield)
ah.report # per expiry and side: worst implied-vol error, quotes fitted / excluded
ah.local_vol(spot_grid, t) # lazy reference local vol at any t; ah.to_local_vol_surface() samples it
- Exact by default: a quote not repriced to 1e-10 in implied vol raises
NumericalError. Quotes with no usable vega (far wings of short, thin-tailed smiles) can be excluded with the opt-inAndreasenHugeConfig(max_abs_d=4.0); exclusions are counted inreport. - Rates and dividends may be term structures; engines see the local vol through forward moneyness, so their own curve forward reproduces the calibrated law.
- On the fixture all 198 quotes reprice within 0.043 vol points on
LocalVolPDESolver(docs/research/dupire_andreasen_huge/README.md). - Risk:
VolModelRiskCalculator(local_vol_construction=LocalVolConstruction.ANDREASEN_HUGE)makes market vega bump the quotes and recalibrate AH (and model risk run on AH); a prebuilt AH surface already works with model risk's local-vol bump. The default stays Dupire.
Continuous-KI bridge refinement (unreleased, opt-in)
The snowball / phoenix / KO-reset MC engines monitor a continuous knock-in on one node per
business day, with a Brownian-bridge crossing probability between nodes. Under local or
stochastic vol that one-day bridge is biased, and substeps_per_interval does not help: it
refines the SDE, not the bridge interval. Near-KI two-week trades are off by +4 to −7 bp of
notional (local vol, against the LV PDE) and +2.4 (Heston), +4.2 (SLV) against a bridge-free
MC reference.
engine = LocalVolSnowballMCEngine(params, local_vol_surface=lv,
ki_bridge_nodes_per_day=16, # bridge on 16 nodes per business day
max_sde_step_days=1.0) # no SDE step longer than one business day
ki_bridge_nodes_per_day(every snowball / phoenix MC engine, BSM included) multiplies the continuous-KI node density; at 16 the near-KI cells land within 2 bp of the reference. Cost: about 6–8× on two-week trades, about 16× on one-year trades (steps scale with the nodes).max_sde_step_days(LV / Heston / SLV snowball and phoenix) splits only the contractual intervals longer than the cap: a one-month contract observed only at maturity moves from +105 bp (one Euler step) to −2 bp at a one-day cap. PSEUDO with the plain estimator only; quasi-random methods, RQMC conditioning,one_step_survivalandrichardson_pair_pricerefuse a cap.- Defaults are unchanged bit for bit. Evidence and the rejected alternatives (barrier-local
bridge variance, front-loaded grids):
docs/research/mc_ki_bridge_refinement/README.md.
Curve construction (unreleased)
Rate and carry term structures built from market instruments, with the interpolation and
extrapolation chosen per curve. Guide: docs/curve-construction.md. Demo:
python example/param/curve_construction_demo.py (writes example/output/curve_construction_report.html).
from quantark.param import (BootstrapConfig, CurveInterpolation, DepositQuote, SwapQuote, BondQuote,
FuturesQuote, bootstrap_discount_curve, bootstrap_projection_curve,
build_carry_curve, reprice_quotes)
from quantark.param.index import SHIBOR_3M
from quantark.util.enum import PaymentFrequency
quotes = [DepositQuote(rate=0.019, tenor_years=0.25), DepositQuote(rate=0.0205, tenor_years=0.5),
SwapQuote(fixed_rate=0.022, index=SHIBOR_3M, tenor_years=1.0),
SwapQuote(fixed_rate=0.0262, index=SHIBOR_3M, tenor_years=3.0),
BondQuote(coupon_rate=0.03, clean_price=100.9, payment_frequency=PaymentFrequency.SEMI_ANNUAL, tenor_years=5.0)]
cfg = BootstrapConfig(interpolation=CurveInterpolation.MONOTONE_CONVEX) # LINEAR_ZERO, LOG_LINEAR_DF (default),
discount = bootstrap_discount_curve(quotes, cfg) # CUBIC_ZERO, LOG_CUBIC_DF, MONOTONE_CONVEX
assert max(abs(r) for r in reprice_quotes(quotes, discount)) < 1e-12 # round trip
projection = bootstrap_projection_curve(quotes[:4], discount_curve=ois_curve, config=cfg) # dual-curve
carry = build_carry_curve(spot, FuturesQuote.from_index_futures_curve(futures), discount) # futures / option pairs
q = carry.to_dividend_yield(discount) # live view q(T) = r(T) − B(T)/T for any PricingEnvironment
ZeroCurve is a RateCurve and CarryImpliedDividendYield a DividendYield, so every pricing engine,
TradingClockRateCurve, the key-rate buckets and the risk stack take them unchanged: stress applicators
(equity, FX, credit), FX VaR revaluation, SA-CVA IR delta and as-of roll-down, PnL-explain bucketing and
execution fingerprints dispatch on the pillar-curve protocol (pillars + with_pillars,
quantark.param.rrf.is_pillar_curve) instead of the InterpolatedRateCurve class, so a bumped or stressed
ZeroCurve keeps its interpolation, extrapolation and clock anchor. Quotes are numeric (tenor_years) or dated (dates plus a
valuation_date, calendar ACT/365F), never mixed; dated swaps and bonds are built as the repo's own
InterestRateSwap / FixedBond, so bootstrapped curves reprice through IRSDiscountEngine and
BondDiscountEngine by construction, and a QuantLib cross-check (PiecewiseLogLinearDiscount,
PiecewiseLinearZero) agrees within 1e-10 when QuantLib is installed.
Engine change: every floating projection (IRS, FRN, FRA, cap/floor, swaption fallback) is now the simple forward
(P(t_a)/P(t_b) − 1)/dcf over the index window in the leg's own day count, via simple_forward_rate; the old
continuously-compounded shortcut is gone. See the guide for the size of the move per index type.
RQMC Target Std Scaling (MC Benchmarking)
Randomized QMC uses a target standard error for adaptive batching. For large notionals, prefer relative scaling to avoid overly strict absolute tolerances:
from quantark.asset.equity.param import MCParams
mc_params = MCParams(
num_paths=100000,
rqmc_target_std=1e-4, # 1 bp relative
rqmc_target_std_mode="relative_notional",
rqmc_paths_mode="total",
)
Running the Demo
A comprehensive demonstration is provided:
python example/asset/equity/options/european_option_demo.py
The demo showcases:
- European Call option pricing and Greeks
- European Put option pricing and Greeks
- Put-Call Parity verification
- Comparison between analytical and numerical Greeks
FX portfolio across the full risk stack
python example/asset/fx/fx_portfolio_risk_demo.py # one FX book through all four risk modules
python example/asset/fx/fx_stress_test_demo.py # FX stress testing (spot/vol/two-rate shocks)
python example/asset/fx/fx_var_demo.py # FX VaR (parametric / historical / Monte Carlo)
python example/asset/fx/fx_dynamic_scenario_demo.py # multi-day FX path simulation
python example/asset/fx/fx_backtest_demo.py # FX delta-neutral hedging backtest
Project Structure
All library code lives under the quantark/ package (canonical quantark.* imports).
quantark/
├── asset/ # Asset classes
│ ├── equity/
│ │ ├── engine/ # analytical/, mc/, pde/, quad/ (+ base, event_stats)
│ │ ├── process/ # bsm/ (Heston / LocalVol / SLV live in volmodels/)
│ │ ├── product/ # option/ (vanilla, exotics, autocallables), deltaone/, swap/ (TRS)
│ │ ├── lifecycle/ # shared autocallable lifecycle core
│ │ ├── param/ # engine parameters & profiles
│ │ ├── analysis/, report/, riskmeasures/
│ ├── bond/ # coupon bonds, FRNs, convertibles, forwards, futures, options
│ │ └── engine/ # analytical/, discount/, pde/, tree/, convertible/
│ ├── rate/ # IRS, FRA, cap/floor, swaption
│ ├── fx/ # Garman-Kohlhagen + exotics (barrier, sharkfin, range accrual, TARF/TARN)
│ │ └── engine/ # analytical/ (incl. Vanna-Volga, FX-Heston), mc/, pde/
│ └── credit/ # CDS, basket CDS (hazard-curve engine)
├── volmodels/ # Heston, Local Vol (Dupire), SLV kernels + Black-Scholes / curves
├── montecarlo/ # Shared QMC layer (Sobol, Brownian bridge, RQMC, variance reduction)
├── param/ # Market data: quote/, rrf/, div/, vol/ (incl. sabr/, vannavolga/)
├── priceenv/ # Pricing environments (equity & FX)
├── intraday/ # Timestamp valuation: sessions, variance profiles, provisional fixings, routes, Greeks
├── execution/ # PricingSession kernel: capability matrix, determinism policy, batch / scenarios
├── portfolio/ # Position tracking: equity/, fi/, fx/, credit/
├── var/ # Value-at-Risk (historical / parametric / monte_carlo) + backtest/
├── stresstest/ # Scenario-based stress testing (all asset classes)
├── dynamicscenario/ # Multi-day scenario simulation
├── backtest/ # Hedging-strategy backtesting (delta / DV01 / convexity-neutral)
├── simm/ # ISDA SIMM v2.6 initial margin (engines, crif, calibration, dashboard)
├── saccr/ # Basel SA-CCR counterparty EAD (RC + PFE)
├── sacva/ # Basel SA-CVA (MAR50) CVA capital
├── cashleg/ # Deterministic cash-flow legs for structured products
├── rfq/ # Request-for-quote service & registry
└── util/ # enum/, numerical/, calendar, market-data adapters, exceptions
example/ # how-to demos mirroring the package tree + case_studies/ (see example/README.md)
test/ # Unit-test suite
Exception Hierarchy
QuantArk uses a professional exception hierarchy:
QuantArkException: Base exceptionValidationError: Invalid input parametersNumericalError: Numerical instability/convergence issuesMarketDataError: Missing or invalid market dataPricingError: General pricing failures
Numerical Stability
The Black-Scholes engine includes extensive checks for numerical stability:
- Input parameter validation (spot, strike, volatility, rates)
- Overflow protection in exponential calculations
- Boundary condition handling (near expiry, deep ITM/OTM)
- Sanity checks on computed prices vs intrinsic values
- Extreme parameter detection and rejection
Roadmap
Delivered
- American options (analytical and numerical methods)
- Asian, barrier, digital, one-touch, and double-barrier options
- Autocallables (Snowball, Phoenix, KO-Reset) and structured products (range accrual, accumulator, sharkfin)
- Monte Carlo, PDE, Quadrature, and Tree engines
- Heston, Local Volatility (Dupire), and Stochastic Local Vol models
- FX derivatives (vanilla, exotic, TARF/TARN) with SABR & Vanna-Volga smiles
- Credit derivatives (single-name and basket CDS)
- Fixed income instruments (bonds, swaps, FRAs, caps/floors, swaptions)
- Portfolio VaR, stress testing, dynamic scenarios, and hedging backtests
- Regulatory capital: ISDA SIMM v2.6, SA-CCR, SA-CVA
In progress / planned
- Multi-asset and hybrid derivatives
- Unified calibration framework
- Full XVA suite (FVA, MVA, KVA)
- Performance optimization (Cython, GPU)
- Real-time risk metrics & market data integration
- Portfolio optimization
- Cloud deployment support
Contributing
Contributions are welcome! Please follow these guidelines:
- Follow the existing code structure and style
- Add comprehensive docstrings
- Include unit tests for new features
- Validate inputs and handle edge cases
- Add professional error handling
Disclaimer
QuantArk is provided for research and educational purposes. It is not investment advice, and no warranty is made as to the correctness of any price, risk figure, or model output. Validate independently before any production or trading use. See the LICENSE file for the full terms.
License
Apache License 2.0 — see LICENSE and NOTICE.
Acknowledgments
QuantArk builds on decades of published quantitative-finance research. In particular:
- Black-Scholes-Merton option-pricing model — Fischer Black, Myron Scholes, and Robert Merton
- American options — Barone-Adesi & Whaley quadratic approximation; Bjerksund & Stensland (1993/2002); Longstaff & Schwartz least-squares Monte Carlo
- Stochastic & local volatility — Steven Heston (1993); Bruno Dupire local-volatility construction; stochastic-local-vol (SLV) calibration
- FX volatility smiles — Patrick Hagan et al. (SABR); the Vanna-Volga market approach
- Credit — standard ISDA hazard-rate / reduced-form CDS pricing conventions
- Regulatory capital — ISDA SIMM v2.6, and the Basel Committee's SA-CCR and SA-CVA (MAR50) standards
- Numerical methods — Sobol sequences, Brownian-bridge and randomized-QMC variance reduction, and finite-difference PDE schemes from standard computational-finance texts
- Greeks formulas from standard derivatives textbooks
- Design patterns inspired by QuantLib and similar professional libraries
Metadata
Release files for quantark 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| quantark-0.11.0.tar.gz | 2.8 MB | With provenance | Details for quantark-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| quantark-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for quantark-0.11.0-py3-none-any.whl |
Total release size: 6.0 MB
Release files / quantark-0.11.0.tar.gz
| Download URL | quantark-0.11.0.tar.gz |
|---|---|
| Size | 2.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1000b8e939eaec96846bbeb68d105776d52194980615d1698b3b92ad398338b
|
|
BLAKE2b-256 checksum How to use checksums |
247181e2ad44f533beb333313a713f257a66ccd0f923977feda5f43d99156f81
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / quantark-0.11.0-py3-none-any.whl
| Download URL | quantark-0.11.0-py3-none-any.whl |
|---|---|
| Size | 3.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28edf621c04786d87d77139a82a95f79b27156d485f0fd79ee2e9d36668672ee
|
|
BLAKE2b-256 checksum How to use checksums |
9d8f3c8faa73e1b2889ba8f63eaff40a21244ca61053b250f0e33f666234862a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for quantark 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for quantark-0.11.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.