Docs

Author: lsbardel

.github/copilot-instructions.md

@@ -12,6 +12,7 @@ applyTo: '/**'
 
 * Always run `make lint` after code changes — runs taplo, isort, black, ruff, and mypy
 * Never edit `readme.md` directly — it is generated from `docs/index.md` via `make docs`
+* To install all dependencies (including all optional extras) run `make install-dev` — runs `uv sync --all-extras`
 * To run all tests use `make test` — runs all tests in the `tests/` directory using pytest
 * To run a specific test file, use `uv run pytest tests/path/to/test_file.py`
 
@@ -28,6 +29,7 @@ applyTo: '/**'
 * Documentation is built using [mkdocs](https://www.mkdocs.org/) and stored in the `docs/` directory. The documentation source files are written in markdown format.
 * Do not use em dashes (—) in documentation files or docstrings. Use colons, parentheses, or restructure the sentence instead.
 * Math in documentation and docstrings uses `$...$` for inline and `$$...$$` or `\begin{equation}...\end{equation}` for block equations. Do not use `.. math::` or `:math:` (RST syntax).
+* Glossary entries in `docs/glossary.md` must be kept in alphabetical order.
 * To rebuild doc examples run `uv run ./dev/build-examples` — runs all scripts in `docs/examples/` and writes their output to `docs/examples_output/`
 
 ## Package structure

app/volatility_surface.py

@@ -1,6 +1,6 @@
 import marimo
 
-__generated_with = "0.20.4"
+__generated_with = "0.22.0"
 app = marimo.App(width="medium")
 
 
@@ -42,58 +42,47 @@ def _(mo):
     return
 
 
+@app.cell
+def _():
+    kwargs = dict()
+    return
+
+
 @app.cell
 def _(mo):
+    asset = mo.ui.dropdown(["btc", "eth", "sol"], value="btc", label="asset")
     inverse = mo.ui.checkbox(value=True, label="Inverse options")
-    inverse
-    return (inverse,)
+    mo.hstack([asset, inverse])
+    return asset, inverse
 
 
 @app.cell
-async def _(inverse):
+async def _(asset, inverse):
     import pandas as pd
     from quantflow.data.deribit import Deribit
 
     async with Deribit() as cli:
-        loader = await cli.volatility_surface_loader("eth", exclude_open_interest=0, inverse=inverse.value)
+        loader = await cli.volatility_surface_loader(
+            asset.value,
+            inverse=inverse.value,
+            use_perp=not inverse.value
+        )
 
     # build the volatility surface
     surface = loader.surface()
     # calculate black implied volatilities
     surface.bs()
     # disable outliers
     surface.disable_outliers()
-    # display inputs - only options with converged implied volatility
-    surface_inputs = surface.inputs(converged=True)
-    pd.DataFrame([i.model_dump() for i in surface_inputs.inputs])
-    return (surface,)
-
-
-@app.cell(hide_code=True)
-def _(mo):
-    mo.md(r"""
-    ##Volatility Surface
-    """)
-    return
-
-
-@app.cell
-def _(surface):
     surface.plot3d()
-    return
-
-
-@app.cell(hide_code=True)
-def _(mo):
-    mo.md(r"""
-    ## Term Structure
-    """)
-    return
+    return pd, surface
 
 
 @app.cell
-def _(surface):
-    surface.term_structure()
+def _(pd, surface):
+    # display inputs - only options with converged implied volatility
+    surface_inputs = surface.inputs(converged=True)
+    pd.DataFrame([i.model_dump() for i in surface_inputs.inputs])
     return
 
 

docs/api/index.md

@@ -1,3 +1,71 @@
-# API
+# API Reference
 
-Here's the reference or code API, the classes, functions, parameters, attributes, and all the quantflow parts you can use in your applications.
+Complete reference for all public classes, functions, and parameters in the quantflow library.
+
+## Modules
+
+### [Data](data/index.md)
+
+Clients for fetching market data from external sources. Requires the optional `data` extra:
+
+```
+pip install quantflow[data]
+```
+
+| Module | Description |
+|---|---|
+| [Deribit](data/deribit.md) | Crypto options and futures from the Deribit exchange |
+| [Financial Modeling Prep](data/fmp.md) | Equity prices, profiles, and sector data |
+| [FRED](data/fred.md) | US macroeconomic time series from the St. Louis Fed |
+| [Federal Reserve](data/fed.md) | Federal Reserve H.15 interest rate data |
+
+### [Options](options/index.md)
+
+Option pricing, volatility surface construction, and model calibration.
+
+| Module | Description |
+|---|---|
+| [Black-Scholes](options/black.md) | Black-76 pricing formula and implied volatility inversion |
+| [Pricer](options/pricer.md) | Model-based option pricer supporting any stochastic process |
+| [Volatility Surface](options/vol_surface.md) | Build and serialise implied volatility surfaces from market data |
+| [Calibration](options/calibration.md) | Calibrate Heston and Heston-jump-diffusion models to a surface |
+| [Deep IV Factor Model](options/divfm.md) | Neural-network option pricing via the DIVFM architecture |
+
+### [Stochastic Processes](sp/index.md)
+
+Continuous-time stochastic processes used as underlying models for option pricing and simulation.
+
+| Module | Description |
+|---|---|
+| [Weiner Process](sp/weiner.md) | Geometric Brownian motion (constant volatility) |
+| [Heston Model](sp/heston.md) | Stochastic volatility with optional jump component (HestonJ) |
+| [Jump Diffusion](sp/jump_diffusion.md) | Compound Poisson jump processes |
+| [CIR Process](sp/cir.md) | Cox-Ingersoll-Ross mean-reverting process |
+| [Ornstein-Uhlenbeck](sp/ou.md) | Ornstein-Uhlenbeck mean-reverting process |
+| [Poisson Process](sp/poisson.md) | Homogeneous Poisson process |
+| [Compound Poisson](sp/compound_poisson.md) | Poisson arrivals with a jump-size distribution |
+| [Doubly Stochastic Poisson](sp/dsp.md) | Poisson process with stochastic intensity |
+
+### [Technical Analysis](ta/index.md)
+
+Time series filters and indicators for financial data.
+
+| Module | Description |
+|---|---|
+| [EWMA](ta/ewma.md) | Exponentially weighted moving average |
+| [Kalman Filter](ta/kalman.md) | Kalman filter for state estimation |
+| [Supersmoother](ta/supersmoother.md) | Ehlers two-pole supersmoother filter |
+| [OHLC](ta/ohlc.md) | OHLC bar utilities and resampling |
+| [Paths](ta/paths.md) | Simulated path containers and statistics |
+
+### [Utilities](utils/index.md)
+
+Low-level building blocks used throughout the library.
+
+| Module | Description |
+|---|---|
+| [Distributions](utils/distributions.md) | Jump-size distributions (Normal, DoubleExponential) |
+| [Marginal 1D](utils/marginal1d.md) | Marginal distribution via characteristic function inversion |
+| [Bins](utils/bins.md) | Histogram binning helpers |
+| [Numbers](utils/numbers.md) | Decimal and float numeric utilities |
+| [Types](utils/types.md) | Shared type aliases |

docs/api/options/vol_surface.md

@@ -31,10 +31,12 @@
 
 ::: quantflow.options.surface.OptionSelection
 
-::: quantflow.options.inputs.OptionType
+::: quantflow.options.surface.surface_from_inputs
 
 ## Vol Surface Inputs
 
+::: quantflow.options.inputs.OptionType
+
 ::: quantflow.options.inputs.VolSurfaceInputs
 
 ::: quantflow.options.inputs.VolSurfaceInput

docs/api/sp/copula.md

@@ -0,0 +1,10 @@
+# Copulas
+
+::: quantflow.sp.copula.Copula
+
+
+::: quantflow.sp.copula.IndependentCopula
+
+
+::: quantflow.sp.copula.FrankCopula
+

docs/assets/heston_calibrated_smile.png

@@ -0,0 +1,33 @@
+import json
+
+from quantflow.options.calibration import HestonCalibration
+from quantflow.options.pricer import OptionPricer
+from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
+from quantflow.sp.heston import Heston
+
+# Load a saved volatility surface snapshot and build the surface
+with open("quantflow_tests/volsurface.json") as fp:
+    surface: VolSurface = surface_from_inputs(VolSurfaceInputs(**json.load(fp)))
+
+surface.bs()
+surface.disable_outliers()
+
+# Create a Heston pricer with initial parameters
+pricer = OptionPricer(model=Heston.create(vol=0.5, kappa=1, sigma=0.8, rho=0))
+
+# Set up the calibration, dropping the first (very short) maturity and high-vol wings
+calibration = HestonCalibration(
+    pricer=pricer,
+    vol_surface=surface.trim(len(surface.maturities) - 1),
+    moneyness_weight=1.0,
+).remove_implied_above(quantile=0.95)
+
+result = calibration.fit()
+print(result.message)
+params = calibration.get_params()
+model = calibration.model
+print(f"vol:   {model.variance_process.rate**0.5:.4f}")
+print(f"theta: {model.variance_process.theta**0.5:.4f}")
+print(f"kappa: {model.variance_process.kappa:.4f}")
+print(f"sigma: {model.variance_process.sigma:.4f}")
+print(f"rho:   {model.rho:.4f}")

docs/assets/hestonj_calibrated_smile.png

@@ -0,0 +1,35 @@
+import json
+from pathlib import Path
+
+from quantflow.options.calibration import HestonCalibration
+from quantflow.options.pricer import OptionPricer
+from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
+from quantflow.sp.heston import Heston
+
+# Load a saved volatility surface snapshot and build the surface
+with open("quantflow_tests/volsurface.json") as fp:
+    surface: VolSurface = surface_from_inputs(VolSurfaceInputs(**json.load(fp)))
+
+surface.bs()
+surface.disable_outliers()
+
+# Create a Heston pricer and calibrate
+pricer = OptionPricer(model=Heston.create(vol=0.5, kappa=1, sigma=0.8, rho=0))
+calibration = HestonCalibration(
+    pricer=pricer,
+    vol_surface=surface.trim(len(surface.maturities) - 1),
+    moneyness_weight=1.0,
+).remove_implied_above(quantile=0.95)
+calibration.fit()
+
+# Plot the calibrated smile for the second maturity and save as PNG
+fig = calibration.plot(index=1, max_moneyness_ttm=1.5, support=101)
+fig.update_layout(
+    xaxis_title="Moneyness / sqrt(T)",
+    yaxis_title="Implied Volatility",
+    title="Heston Calibrated Smile — Maturity 2",
+)
+
+out_path = Path("docs/assets/heston_calibrated_smile.png")
+fig.write_image(str(out_path), width=900, height=500)
+print(f"saved {out_path}")

docs/examples/vol_surface_heston_calibration.py

@@ -0,0 +1,46 @@
+import json
+
+from quantflow.options.calibration import HestonJCalibration
+from quantflow.options.pricer import OptionPricer
+from quantflow.options.surface import VolSurface, VolSurfaceInputs, surface_from_inputs
+from quantflow.sp.heston import HestonJ
+from quantflow.utils.distributions import DoubleExponential
+
+# Load a saved volatility surface snapshot and build the surface
+with open("quantflow_tests/volsurface.json") as fp:
+    surface: VolSurface = surface_from_inputs(VolSurfaceInputs(**json.load(fp)))
+
+surface.bs()
+surface.disable_outliers()
+
+# Create a HestonJ pricer with initial parameters
+pricer = OptionPricer(
+    model=HestonJ.create(
+        DoubleExponential,
+        vol=0.5,
+        kappa=2,
+        rho=-0.2,
+        sigma=0.8,
+        jump_fraction=0.3,
+        jump_asymmetry=0.2,
+    )
+)
+
+# Set up the calibration, dropping the first (very short) maturity and high-vol wings
+calibration = HestonJCalibration(
+    pricer=pricer,
+    vol_surface=surface.trim(len(surface.maturities) - 1),
+    moneyness_weight=1.0,
+).remove_implied_above(quantile=0.95)
+
+result = calibration.fit()
+print(result.message)
+model = calibration.model
+print(f"vol:            {model.variance_process.rate**0.5:.4f}")
+print(f"theta:          {model.variance_process.theta**0.5:.4f}")
+print(f"kappa:          {model.variance_process.kappa:.4f}")
+print(f"sigma:          {model.variance_process.sigma:.4f}")
+print(f"rho:            {model.rho:.4f}")
+print(f"jump intensity: {model.jumps.intensity:.4f}")
+print(f"jump variance:  {model.jumps.jumps.variance():.6f}")
+print(f"jump asymmetry: {model.jumps.jumps.asymmetry():.4f}")