quantflow 0.6.0__tar.gz → 0.6.2__tar.gz

{quantflow-0.6.0 → quantflow-0.6.2}/.github/copilot-instructions.md

@@ -12,6 +12,8 @@ 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 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`
 
 ## Docker
 
@@ -24,4 +26,6 @@ applyTo: '/**'
 
 * The documentation for quantflow is available at `https://quantflow.quantmid.com`
 * 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).
+* To rebuild doc examples run `uv run ./dev/build-examples` — runs all scripts in `docs/examples/` and writes their output to `docs/examples_output/`

{quantflow-0.6.0 → quantflow-0.6.2}/.gitignore

@@ -37,3 +37,4 @@ _build
 
 # builds
 app/docs
+docs/examples_output

{quantflow-0.6.0 → quantflow-0.6.2}/.vscode/launch.json

@@ -14,7 +14,7 @@
             "args": [
                 "-x",
                 "-vvv",
-                "quantflow_tests/test_options.py",
+                "quantflow_tests/test_options_pricer.py",
             ]
         },
     ]

{quantflow-0.6.0 → quantflow-0.6.2}/Makefile

@@ -27,6 +27,7 @@ marimo:				## Run marimo for editing notebooks
 .PHONY: docs
 docs:				## build documentation
 	@cp docs/index.md readme.md
+	@uv run ./dev/build-examples
 	@uv run mkdocs build
 
 .PHONY: docs-serve
@@ -46,3 +47,7 @@ tests:				## Unit tests
 .PHONY: outdated
 outdated:			## Show outdated packages
 	uv tree --outdated
+
+.PHONY: upgrade
+upgrade:			## Upgrade dependencies
+	uv lock --upgrade

{quantflow-0.6.0 → quantflow-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantflow
-Version: 0.6.0
+Version: 0.6.2
 Summary: quantitative analysis
 Project-URL: Homepage, https://github.com/quantmind/quantflow
 Project-URL: Repository, https://github.com/quantmind/quantflow
@@ -9,7 +9,7 @@ Author-email: Luca Sbardella <luca@quantmind.com>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
 Requires-Python: <3.15,>=3.11
-Requires-Dist: ccy>=1.7.1
+Requires-Dist: ccy>=2.0.0
 Requires-Dist: polars[pandas,pyarrow]>=1.11.0
 Requires-Dist: pydantic>=2.0.2
 Requires-Dist: python-dotenv>=1.0.1
@@ -17,7 +17,7 @@ Requires-Dist: scipy>=1.14.1
 Requires-Dist: statsmodels<0.15.0,>=0.14.6
 Provides-Extra: ai
 Requires-Dist: asciichartpy>=1.5.25; extra == 'ai'
-Requires-Dist: ccy[holidays]>=1.7.1; extra == 'ai'
+Requires-Dist: ccy[holidays]>=2.0.0; extra == 'ai'
 Requires-Dist: google-genai>=1.61.0; extra == 'ai'
 Requires-Dist: mcp>=1.26.0; extra == 'ai'
 Requires-Dist: openai>=2.16.0; extra == 'ai'

quantflow-0.6.2/app/volatility_surface.py

@@ -0,0 +1,106 @@
+import marimo
+
+__generated_with = "0.20.4"
+app = marimo.App(width="medium")
+
+
+@app.cell
+def _():
+    import marimo as mo
+    from app.utils import nav_menu
+    nav_menu()
+    return (mo,)
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    # Volatility Surface
+
+    In this notebook we illustrate the use of the Volatility Surface tool in the library. We use [deribit](https://docs.deribit.com/) options on ETHUSD as example.
+
+    The library provide a [VolSurfaceLoader](api/options/vol_surface/#quantflow.options.surface.VolSurfaceLoader) for Deribit:
+
+    ```python
+    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)
+
+    # 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
+
+
+@app.cell
+def _(mo):
+    inverse = mo.ui.checkbox(value=True, label="Inverse options")
+    inverse
+    return (inverse,)
+
+
+@app.cell
+async def _(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)
+
+    # 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
+
+
+@app.cell
+def _(surface):
+    surface.term_structure()
+    return
+
+
+@app.cell
+def _():
+    return
+
+
+if __name__ == "__main__":
+    app.run()

quantflow-0.6.2/dev/build-examples

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+"""Run all example scripts in docs/examples/ and capture their stdout to .out files."""
+import subprocess
+import sys
+from pathlib import Path
+
+out_dir = Path("docs/examples_output")
+out_dir.mkdir(exist_ok=True)
+
+examples = sorted(Path("docs/examples").glob("*.py"))
+failed = []
+
+for script in examples:
+    out_file = out_dir / script.with_suffix(".out").name
+    print(f"running {script} -> {out_file}")
+    result = subprocess.run(
+        [sys.executable, str(script)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(f"FAILED: {script}\n{result.stderr}", file=sys.stderr)
+        failed.append(script)
+    else:
+        out_file.write_text(result.stdout)
+
+if failed:
+    sys.exit(1)

{quantflow-0.6.0 → quantflow-0.6.2}/dev/quantflow.dockerfile

@@ -14,6 +14,8 @@ RUN uv sync --frozen --no-install-project --extra ai --extra book --extra docs -
 COPY mkdocs.yml ./
 COPY docs/ ./docs/
 COPY quantflow/ ./quantflow/
+COPY dev/build-examples ./dev/build-examples
+RUN uv run ./dev/build-examples
 RUN uv run mkdocs build
 
 # Stage 2: Runtime stage

{quantflow-0.6.0 → quantflow-0.6.2}/docs/api/data/deribit.md

@@ -9,3 +9,4 @@ from quantflow.data.deribit import Deribit
 ```
 
 ::: quantflow.data.deribit.Deribit
+

{quantflow-0.6.0 → quantflow-0.6.2}/docs/api/data/index.md

@@ -1,7 +1,7 @@
 # Data fetching
 
 
-The :mod:`quantflow.data` module provides classes and functions for fetching data from various sources.
+The `quantflow.data` module provides classes and functions for fetching data from various sources.
 To use the module the package must be installed with the optional `data` extra.
 ```
 pip install quantflow[data]

quantflow-0.6.2/docs/api/options/black.md

@@ -0,0 +1,25 @@
+# Black Pricing
+
+Here we define the log strike `k` as
+$$
+  k = \log{\frac{K}{F}}
+$$
+
+where $K$ is the strike price and $F$ is the forward price of the underlying asset.
+We also refers to this log-strike as `moneyness`, since it is zero for at-the-money (ATM) options,
+negative for in-the-money (ITM) call options, and positive for out-of-the-money (OTM) call options.
+
+
+::: quantflow.options.bs.black_price
+
+::: quantflow.options.bs.black_call
+
+::: quantflow.options.bs.black_vega
+
+::: quantflow.options.bs.BlackSensitivities
+
+::: quantflow.options.bs.implied_black_volatility
+
+::: quantflow.options.bs.ImpliedVols
+
+::: quantflow.options.bs.ImpliedVol

quantflow-0.6.2/docs/api/options/index.md

@@ -0,0 +1,52 @@
+# Options
+
+The `options` module provides classes and functions for pricing and calibrating options.
+
+## Volatility Surface
+
+The central class is [VolSurface][quantflow.options.surface.VolSurface], which represents
+the implied volatility surface for an asset across all strikes and maturities. It holds:
+
+- a [SpotPrice][quantflow.options.surface.SpotPrice] for the underlying asset
+- a sorted tuple of [VolCrossSection][quantflow.options.surface.VolCrossSection] objects, one per maturity
+
+Each [VolCrossSection][quantflow.options.surface.VolCrossSection] contains the forward price
+at that maturity and a tuple of [Strike][quantflow.options.surface.Strike] objects.
+Each [Strike][quantflow.options.surface.Strike] holds a call and/or put as an
+[OptionPrices][quantflow.options.surface.OptionPrices], which in turn pairs a bid and ask
+[OptionPrice][quantflow.options.surface.OptionPrice].
+
+A surface is typically constructed via [VolSurfaceLoader][quantflow.options.surface.VolSurfaceLoader],
+which accepts price inputs incrementally and builds the surface through its `surface()` method.
+The lower-level [GenericVolSurfaceLoader][quantflow.options.surface.GenericVolSurfaceLoader]
+provides the same functionality with a user-defined security type.
+
+## Price Classes
+
+| Class | Description |
+|---|---|
+| [Price][quantflow.options.surface.Price] | Base bid/ask price for any security |
+| [SpotPrice][quantflow.options.surface.SpotPrice] | Spot bid/ask price of an underlying asset |
+| [FwdPrice][quantflow.options.surface.FwdPrice] | Forward bid/ask price at a specific maturity |
+| [OptionPrice][quantflow.options.surface.OptionPrice] | Single-sided option price with implied volatility and convergence flag |
+| [OptionPrices][quantflow.options.surface.OptionPrices] | Paired bid and ask [OptionPrice][quantflow.options.surface.OptionPrice] for a given strike and option type |
+
+## Input Classes
+
+The input classes are plain data containers used to serialize and deserialize volatility surface data,
+for example when storing or transmitting a snapshot of the surface.
+
+| Class | Description |
+|---|---|
+| [VolSurfaceInputs][quantflow.options.inputs.VolSurfaceInputs] | Top-level container: asset name, reference date, and a list of inputs |
+| [VolSurfaceInput][quantflow.options.inputs.VolSurfaceInput] | Base input with bid, ask, open interest and volume |
+| [SpotInput][quantflow.options.inputs.SpotInput] | Input for a spot price |
+| [ForwardInput][quantflow.options.inputs.ForwardInput] | Input for a forward price with maturity |
+| [OptionInput][quantflow.options.inputs.OptionInput] | Input for an option with strike, maturity, type, and optional implied vols |
+
+A [VolSurface][quantflow.options.surface.VolSurface] can be round-tripped via:
+
+```python
+inputs = surface.inputs()          # VolSurface -> VolSurfaceInputs
+surface = surface_from_inputs(inputs)  # VolSurfaceInputs -> VolSurface
+```

{quantflow-0.6.0 → quantflow-0.6.2}/docs/api/options/pricer.md

@@ -7,3 +7,5 @@ different stochastic volatility models.
 ::: quantflow.options.pricer.OptionPricer
 
 ::: quantflow.options.pricer.MaturityPricer
+
+::: quantflow.options.pricer.ModelOptionPrice

{quantflow-0.6.0 → quantflow-0.6.2}/docs/api/options/vol_surface.md

@@ -9,10 +9,32 @@
 
 ::: quantflow.options.surface.VolSurfaceLoader
 
+::: quantflow.options.surface.VolCrossSectionLoader
+
+## Bid/Ask Prices
+
+::: quantflow.options.surface.Price
+
+::: quantflow.options.surface.SpotPrice
+
+::: quantflow.options.surface.FwdPrice
+
+::: quantflow.options.surface.Strike
+
+::: quantflow.options.surface.OptionArrays
+
+::: quantflow.options.surface.OptionMetadata
+
 ::: quantflow.options.surface.OptionPrice
 
+::: quantflow.options.surface.OptionPrices
+
 ::: quantflow.options.surface.OptionSelection
 
+::: quantflow.options.inputs.OptionType
+
+## Vol Surface Inputs
+
 ::: quantflow.options.inputs.VolSurfaceInputs
 
 ::: quantflow.options.inputs.VolSurfaceInput

quantflow-0.6.2/docs/api/sp/dsp.md

@@ -0,0 +1,3 @@
+# Doubly Stochastic Poisson process
+
+::: quantflow.sp.dsp.DSP

quantflow-0.6.2/docs/api/utils/index.md

@@ -0,0 +1,3 @@
+# Utilities
+
+This section contains utility functions and classes that are used throughout the library. They are not meant to be used directly by the user, but they can be useful for advanced users who want to extend the library or understand its inner workings.

quantflow-0.6.2/docs/api/utils/numbers.md

@@ -0,0 +1,4 @@
+# Numbers
+
+
+::: quantflow.utils.numbers.DecimalNumber

quantflow-0.6.2/docs/api/utils/types.md

@@ -0,0 +1,6 @@
+# Types
+
+
+::: quantflow.utils.types.FloatArray
+
+::: quantflow.utils.types.FloatArrayLike

quantflow-0.6.2/docs/bibliography.md

@@ -0,0 +1,43 @@
+# Bibliography
+
+---
+
+### carr_madan
+
+Peter Carr, Dilip Madan
+
+[Option Valuation Using the Fast Fourier Transform](https://doi.org/10.1002/(SICI)1097-0261(199904)2:1<61::AID-FUT4>3.0.CO;2-4)
+
+Journal of Computational Finance, 2(4):61-73, 1999
+
+---
+
+### carr_wu
+
+Peter Carr, Liuren Wu
+
+[Time-Changed Lévy Processes and Option Pricing](https://doi.org/10.1016/S0304-405X(03)00171-5)
+
+Journal of Financial Economics, 71(1):113-141, 2004
+
+---
+
+### chourdakis
+
+Kyriakos Chourdakis
+
+[Option Pricing Using the Fractional FFT](https://doi.org/10.21314/JCF.2005.102)
+
+Journal of Computational Finance, 8(2):1-18, 2005
+
+---
+
+### molnar
+
+Peter Molnar
+
+[Volatility modeling and forecasting: utilization of realized volatility, implied volatility and the highest and lowest price of the day](https://drive.google.com/file/d/1zCU1OZyrKQLpxaypPv9U5UPbReBDXcMf/view)
+
+Master's thesis, University of Economics in Prague, 2020
+
+---

quantflow-0.6.2/docs/examples/heston_volatility_pricer.py

@@ -0,0 +1,25 @@
+from quantflow.options.inputs import OptionType
+from quantflow.options.pricer import OptionPricer
+from quantflow.sp.heston import HestonJ
+from quantflow.utils.distributions import DoubleExponential
+
+pricer = OptionPricer(
+    model=HestonJ.create(
+        DoubleExponential,
+        vol=0.5,
+        kappa=2,
+        rho=-0.2,
+        sigma=0.8,
+        jump_fraction=0.5,
+        jump_asymmetry=0.2,
+    )
+)
+
+# Price an ATM call option at time to maturity 1.0
+price = pricer.price(
+    option_type=OptionType.call,
+    strike=100.0,
+    forward=100.0,
+    ttm=1.0,
+)
+print(price.model_dump_json(indent=2))

quantflow-0.6.2/docs/examples/weiner_volatility_pricer.py

@@ -0,0 +1,19 @@
+from quantflow.options.inputs import OptionType
+from quantflow.options.pricer import OptionPricer
+from quantflow.sp.weiner import WeinerProcess
+from quantflow.utils.distributions import DoubleExponential
+
+# Weiner process with constant volatility
+# This produces the same sensitivities as the Black-Scholes model
+pricer = OptionPricer(
+    model=WeinerProcess(sigma=0.3)
+)
+
+# Price an ATM call option at time to maturity 1.0
+price = pricer.price(
+    option_type=OptionType.call,
+    strike=100.0,
+    forward=100.0,
+    ttm=1.0,
+)
+print(price.model_dump_json(indent=2))

{quantflow-0.6.0/notebooks → quantflow-0.6.2/docs}/theory/characteristic.md

@@ -1,24 +1,12 @@
----
-jupytext:
-  text_representation:
-    extension: .md
-    format_name: myst
-    format_version: 0.13
-    jupytext_version: 1.16.6
-kernelspec:
-  display_name: Python 3 (ipykernel)
-  language: python
-  name: python3
----
-
 # Characteristic Function
 
-The library makes heavy use of [characteristic function](https://en.wikipedia.org/wiki/Characteristic_function_(probability_theory))
+The library makes heavy use of the [characteristic function](https://en.wikipedia.org/wiki/Characteristic_function_(probability_theory))
 concept and therefore, it is useful to familiarize with it.
 
 ## Definition
 
-The characteristic function of a random variable $x$ is the Fourier (inverse) transform of ${\mathbb P}_x$, where ${\mathbb P}_x$ is the distrubution measure of $x$
+The characteristic function of a random variable $x$ is the Fourier (inverse) transform of ${\mathbb P}_x$, where ${\mathbb P}_x$ is the distribution measure of $x$
+
 \begin{equation}
  \Phi_{x,u} = {\mathbb E}\left[e^{i u x}\right] = \int e^{i u s} {\mathbb P}_x\left(ds\right)
 \end{equation}
@@ -33,23 +21,23 @@ The characteristic function of a random variable $x$ is the Fourier (inverse) tr
 * moments of $x$ are given by
 
 \begin{equation}
-    {\mathbb E}\left[x^n\right] = i^{-n} \left.\frac{\Phi_{x, u}}{d u}\right|_{u=0}
+    {\mathbb E}\left[x^n\right] = i^{-n} \left.\frac{d\Phi_{x, u}}{d u}\right|_{u=0}
 \end{equation}
 
-## Covolution
+## Convolution
 
-The characteristic function is a great tool for working with linear combination of random variables.
+The characteristic function is a great tool for working with linear combinations of random variables.
 
 * if $x$ and $y$ are independent random variables then the characteristic function of the linear combination $a x + b y$ ($a$ and $b$ are constants) is
 
 \begin{equation}
-    \Phi_{ax+bx,u} = \Phi_{x,a u}\Phi_{y,b u}
+    \Phi_{ax+by,u} = \Phi_{x,a u}\Phi_{y,b u}
 \end{equation}
 
 * which means, if $x$ and $y$ are independent, the characteristic function of $x+y$ is the product
 
 \begin{equation}
-    \Phi_{x+x,u} = \Phi_{x,u}\Phi_{y,u}
+    \Phi_{x+y,u} = \Phi_{x,u}\Phi_{y,u}
 \end{equation}
 
 * The characteristic function of $ax+b$ is
@@ -79,11 +67,6 @@ The inversion formula for these distributions is given by
     {\mathbb P}_x\left(x=k\right) = \frac{1}{2\pi}\int_{-\pi}^\pi e^{-iuk}\Phi_{k, u} du
 \end{equation}
 
-```{code-cell}
-
-```
-
-(characteristic-exponent)=
 ## Characteristic Exponent
 
 The characteristic exponent $\phi_{x,u}$ is defined as

quantflow-0.6.2/docs/theory/index.md

@@ -0,0 +1,51 @@
+# Theory
+
+QuantFlow is built around a unified mathematical framework based on **characteristic functions** and **Lévy processes**. This section introduces the core ideas that underpin the library's stochastic process models, Fourier inversion methods, and option pricing routines.
+
+## Characteristic Functions
+
+The [characteristic function](./characteristic.md) of a random variable $x$ is its Fourier transform under the probability measure:
+
+$$
+\Phi_{x,u} = \mathbb{E}\left[e^{iux}\right]
+$$
+
+It is the central computational object throughout the library. Unlike the probability density function, the characteristic function is always well-defined, bounded, and closed under convolution of independent random variables. This makes it the natural tool for working with Lévy processes, where densities are often unavailable in closed form.
+
+## Lévy Processes
+
+A [Lévy process](./levy.md) $x_t$ has independent and stationary increments, and its characteristic function factors cleanly over time:
+
+$$
+\Phi_{x_t, u} = e^{-t\,\phi_{x_1, u}}
+$$
+
+where $\phi_{x_1,u}$ is the **characteristic exponent** at unit time, given by the Lévy-Khintchine formula.
+
+The library extends this to **time-changed Lévy processes** $y_t = x_{\tau_t}$, where $\tau_t$ is a stochastic clock driven by an intensity process $\lambda_t$. When $\tau_t$ and $x_t$ are independent, the characteristic function of $y_t$ reduces to the Laplace transform of the integrated intensity:
+
+$$
+\Phi_{y_t, u} = \mathcal{L}_{\tau_t}\!\left(\phi_{x_1, u}\right)
+$$
+
+This structure includes the Heston stochastic volatility model and its jump extensions as special cases, where the intensity process follows a CIR (Cox-Ingersoll-Ross) dynamics.
+
+## Fourier Inversion
+
+Given the characteristic function, the [probability density function](./inversion.md) is recovered via inverse Fourier transform. The library implements two numerical schemes:
+
+- **Trapezoidal / Simpson integration** (default) using the Fractional FFT (FRFT), which allows the frequency and space domains to be discretized independently.
+- **Standard FFT**, available as an alternative, with the constraint that $\delta_u \cdot \delta_x = 2\pi / N$.
+
+The FRFT is preferred in practice as it achieves higher accuracy with fewer points.
+
+## Option Pricing
+
+[European call options](./option_pricing.md) are priced by applying the Fourier inversion machinery to the damped call payoff. For an underlying $S_t = S_0 e^{s_t}$ with log-price process $s_t = x_t - c_t$ (where $c_t$ is the convexity correction ensuring the forward is a martingale), the call price in log-moneyness $k = \ln(K/S_0)$ is:
+
+$$
+c_k = \frac{e^{-\alpha k}}{\pi} \int_0^\infty e^{-ivk}\, \Psi(v - i\alpha)\, dv, \qquad
+\Psi_u = \frac{\Phi_{s_t}(u-i)}{iu(iu+1)}
+$$
+
+The same numerical transforms used for PDF inversion are reused here, making option pricing computationally efficient across all supported models.