import numpy as np, foureng as fe

fwd    = fe.ForwardSpec(S0=100.0, r=0.01, q=0.02, T=1.0)
params = fe.HestonParams(kappa=4.0, theta=0.25, nu=1.0, rho=-0.5, v0=0.04)
prices = fe.price_strip("heston", "cos_improved", np.array([80, 90, 100, 110, 120]), fwd, params)

Swap "heston" for any of 27 models and "cos_improved" for any European engine. Same call, no rewiring.

Engines at a glance

Plus Fourier exotics engines (exact Fang-Oosterlee COS Bermudans and Richardson-extrapolated Americans, Hilbert-transform discrete barriers and lookbacks, ASCOS arithmetic Asians, PROJ recursions), non-Fourier baselines (CRR lattice, implicit PDE, CTMC generator methods, Monte Carlo with control variates and LSMC), a vectorised machine-precision implied-vol solver, a calibrator for any registry model, and product-level pricing for 24 payoff dataclasses (barriers, Asians, cliquets, faders, step and swing options, variance products, spreads and rainbows, and more).

What problem it solves

Most option pricing models beyond Black-Scholes (Heston, Bates, Variance Gamma, CGMY...) do not have a closed-form price formula. What they do have is an analytic characteristic function of log-returns, $\varphi_T(u) = \mathbb{E}[e^{iuX_T}]$. This package turns that into option prices.

Monte Carlo is the obvious baseline: simulate paths and average the discounted payoffs. The catch is that standard error scales as $\sigma/\sqrt{n}$, meaning 10x better accuracy requires 100x more paths. In a calibration loop repricing across a full surface, this gets expensive fast.

Fourier methods (Carr-Madan FFT, FRFT, COS) sidestep this entirely. A single characteristic function evaluation plus a deterministic transform prices a whole strike strip at once, reaching near-machine-precision accuracy at sub-millisecond runtimes.

The COS method (Fang & Oosterlee 2008) is typically the fastest of the three, but it has a subtle trap. The method approximates the log-return density as a Fourier-cosine series on a finite window $[a, b]$. The standard truncation rule places that window as

$$[a, b] = \left[c_1 - L\sqrt{c_2 + \sqrt{|c_4|}},; c_1 + L\sqrt{c_2 + \sqrt{|c_4|}}\right]$$

where $c_1, c_2, c_4$ are the model's cumulants and $L$ is a heuristic multiplier. If the window is too narrow, tail mass is lost before the series even starts and no number of additional terms can fix that. The heuristic $L$ works fine on well-behaved models but fails on heavy-tailed or short-maturity cases, producing visible oscillation in the pricing surface:

This project implements the improved COS truncation of Junike & Pankrashkin (2022) and Junike (2024), which replaces the heuristic $L$ with a rigorous tail-mass bound. On the FO2008 test suite, this truncation improvement beats the paper-grid COS in 7 of 8 cases and beats the paper's own best-N result in 6 of 8 (see benchmarks/cos_method_improved/). On top of that, we add an original adaptive filtered-COS extension: spectral weights $\sigma_k \in [0, 1]$ (Fejér, Lanczos, raised-cosine, or exponential) applied to the high-frequency COS coefficients to suppress residual oscillation from sharp density features. A policy-search selector automatically compares grid and filter combinations, returning the fastest configuration that meets the user's tolerance, with the plain Junike path always included as a fallback.

The package covers 27 characteristic-function models across stochastic-volatility, jump-diffusion, pure-Lévy, rough-volatility (including a Markovian lifted Heston), regime-switching, stochastic-rate-hybrid, time-changed Lévy, hybrid SVJ and generic affine families, plus a SABR approximation surface. They are priced through one price_strip dispatcher with COS/FFT/FRFT/CONV, the Feng-Linetsky Hilbert-transform engine, SINC, SWIFT, a high-precision optimal-contour engine, a first-slice Mellin façade, a real PROJ frame-projection engine (Kirkby 2015/2017: Europeans, Bermudans, single and double barriers, step and swing options, and an Asian control variate), BSM finite-difference/lattice baselines, and product-level exotic routes. For 1-D Lévy models the exotic routes include Americans, discretely monitored barriers and lookbacks, and arithmetic Asians, all priced from the same characteristic function. Under Heston, Bates and regime switching there are Bermudans, Americans and discrete barriers, and for pairs of assets spreads, exchange options and options on the max or min. calibrate fits any of the models to option quotes using gradients of the characteristic function.

Full methodology: appendix.md · Extension details: docs/filtered_cos_extension.md · Package architecture: docs/architecture_overview.md.

🆕 What's new in 0.23

Also in 0.23: sv32 prices at short maturities are fixed (PyFENG's CF series overflowed). Details are in the CHANGELOG.

What's new in 0.22

New models, engines and exotic routes. Each one is tested against something independent of it: a closed form, a model it should reduce to, a high-precision calculation, or Monte Carlo. The full list is in the CHANGELOG.

Examples for most of these are in the Quick start. Also in 0.22: bsm_lookback_floating (and price(..., "lookback_bsm")) was about 10% off and is fixed, cos_bermudan_price is now exact and much faster, and matplotlib moved to the optional [viz] extra.

Earlier releases (0.11 to 0.21)

Thirteen capabilities ported into the Fourier stack from the transform-methods literature (the territory covered by Kirkby's PROJ MATLAB toolbox), each implemented natively against foureng's CF interfaces and validated against closed forms and Monte Carlo.

Also in this line: cp=-1 is now honored uniformly across every Fourier engine (parity applied once at dispatch), a long-standing drift omission in merton_jd_cumulants is fixed, and the API reference was backfilled to cover every public symbol. Details in the CHANGELOG.

Installation

Choose the path that fits your goal:

Option A: fork and run everything (recommended)

Forking gives you your own copy on GitHub so you can save changes and push them back.

1. Fork on GitHub

Click Fork at the top-right of github.com/nl2992/fourier-option-pricer, then clone your fork:

git clone https://github.com/YOUR-USERNAME/fourier-option-pricer.git
cd fourier-option-pricer

2a. Set up the environment (pip + venv)

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt  # installs foureng + notebook + test deps

2b. Set up the environment (conda)

conda env create -f environment.yml
conda activate foureng

3. Run the notebooks

jupyter lab   # navigate to notebooks/demo.ipynb to start

4. Run the tests

python -m pytest -q -m "not slow"   # fast suite (about 1.5 minutes)
python -m pytest -q                  # full suite including notebook guards

5. Keep your fork in sync (optional)

git remote add upstream https://github.com/nl2992/fourier-option-pricer.git
git fetch upstream
git rebase upstream/main

Option B: clone without forking (pip + venv or conda)

Use this if you just want to run locally and do not need your own GitHub copy.

git clone https://github.com/nl2992/fourier-option-pricer.git
cd fourier-option-pricer

Then follow step 2a (venv) or 2b (conda) from Option A above.

Option C: Google Colab (no local setup)

Click the Open in Colab badge in the Demo notebook section. The first cell installs all dependencies automatically. No local Python needed.

Note: Colab's Python 3.12 runtime ships with numpy 2.0.0, which has a known import bug. Cell 1 automatically upgrades numpy to a compatible version and clears the module cache. No manual restart needed.

Option D: library only (PyPI)

Use this if you want to import foureng in your own code without cloning the repo.

pip install fourier-option-pricer          # core: numpy, scipy, pyfeng (+ statsmodels)
pip install "fourier-option-pricer[viz]"   # + matplotlib/pandas for foureng.viz
pip install "fourier-option-pricer==0.23.0"  # pin a release

Requires Python 3.10 to 3.14. The package ships inline type hints (py.typed). Check what you have with python -c "import foureng; print(foureng.__version__)".

If you are upgrading from 0.5.x (the previous PyPI release), note that matplotlib is now optional (install the [viz] extra for foureng.viz) and that cos_bermudan_price now uses the exact Fang-Oosterlee scheme, so its prices move slightly. The CHANGELOG has the rest.

Dependencies at a glance

requirements.txt covers runtime + notebook + test deps in one file. environment.yml is the conda equivalent.

Quick start

Price a strike strip

import numpy as np
import foureng as fe

fwd    = fe.ForwardSpec(S0=100.0, r=0.01, q=0.02, T=1.0)
params = fe.HestonParams(kappa=4.0, theta=0.25, nu=1.0, rho=-0.5, v0=0.04)

strikes = np.array([80.0, 90.0, 100.0, 110.0, 120.0])
calls   = fe.price_strip("heston", "cos_improved", strikes, fwd, params)
puts    = fe.price_strip("heston", "cos_improved", strikes, fwd, params, cp=-1)
print(calls)

Switch engine or model

Only the strings and the parameter object change:

for method in ["cos_filtered", "sinc", "swift", "hilbert", "contour"]:
    prices = fe.price_strip("heston", method, strikes, fwd, params)

bates = fe.BatesParams(kappa=4.0, theta=0.25, nu=1.0, rho=-0.5, v0=0.04,
                       lam_j=0.5, mu_j=-0.1, sigma_j=0.15)
prices = fe.price_strip("bates", "cos_improved", strikes, fwd, bates)

On this Heston strip the engines agree to about 1e-9. Some rules of thumb for picking one:

Implied vols and far wings

vols = fe.implied_vol_lets_be_rational(calls, fwd.F0, strikes, fwd.T, disc=fwd.disc)

wings = fe.price_strip("heston", "contour", np.array([200.0, 300.0]), fwd, params)

implied_vol_lets_be_rational is vectorised and accurate to machine precision, including far from the money. The contour engine keeps full relative accuracy on tiny wing prices, where a fixed-grid method only guarantees absolute accuracy.

Exotics under Lévy models

Products are dataclasses passed to price. For the discretely monitored routes, grid is the number of monitoring dates.

from foureng.products.american import AmericanOption
from foureng.products.asian import AsianOption
from foureng.products.barrier import BarrierOption
from foureng.products.lookback import LookbackOption

fwd_l = fe.ForwardSpec(S0=100.0, r=0.05, q=0.0, T=1.0)
kou   = fe.KouParams(sigma=0.15, lam=1.0, p=0.4, eta1=10.0, eta2=5.0)

american = fe.price(AmericanOption(strike=100.0, maturity=1.0, cp=-1),
                    "kou", "cos_american", fwd_l, kou)
barrier  = fe.price(BarrierOption(strike=100.0, barrier=85.0, maturity=1.0,
                                  barrier_type="down_out", monitoring="discrete"),
                    "kou", "hilbert_barrier", fwd_l, kou, grid=52)
lookback = fe.price(LookbackOption(maturity=1.0, cp=-1, strike_type="floating",
                                   monitoring="discrete"),
                    "kou", "hilbert_lookback", fwd_l, kou, grid=52)
asian    = fe.price(AsianOption(strike=100.0, maturity=1.0,
                                monitoring_times=np.linspace(1 / 12, 1.0, 12)),
                    "kou", "asian_cos", fwd_l, kou)

The same calls work for the other 1-D Lévy models (bsm, vg, nig, cgmy, merton_jd, meixner and so on).

Newer models

bns = fe.BNSParams(v0=0.04, lam=1.5, a=1.2, b=30.0, rho=-2.0)
prices = fe.price_strip("bns", "cos_improved", strikes, fwd, bns)

vg_on_cir = fe.TimeChangedLevyParams("vg", fe.VGParams(sigma=0.2, nu=0.3, theta=-0.1),
                                     fe.CirClock(y0=1.0, kappa=2.0, eta=1.0, lam=1.0))
prices = fe.price_strip("time_changed_levy", "cos_improved", strikes, fwd, vg_on_cir)

lifted = fe.LiftedHestonParams(v0=0.04, kappa=0.3, theta=0.04, nu=0.3, rho=-0.7,
                               H=0.1, n=20, r_n=2.5)
prices = fe.price_strip("lifted_heston", "sinc", strikes, fwd, lifted)

Every model and its parameters are listed in docs/model_zoo.md.

Two-asset options

The second asset's spot and dividend yield sit on the product. With model="bsm" the product's sigma2 and rho complete a correlated GBM pair; a two-asset model (bsm2d, vg2d, heston2d) carries its own dynamics.

from foureng.products import RainbowOption, SpreadOption

fwd2 = fe.ForwardSpec(S0=100.0, r=0.05, q=0.0, T=1.0)
bsm = fe.BsmParams(sigma=0.2)
spread = SpreadOption(strike=5.0, maturity=1.0, spot2=95.0, sigma2=0.3, rho=0.6)
exact = fe.price(spread, "bsm", "fourier_2d", fwd2, bsm)
kirk = fe.price(spread, "bsm", "spread_bsm", fwd2, bsm)  # the Kirk approximation

vg2 = fe.Vg2dParams(sigma1=0.2, sigma2=0.3, theta1=-0.1, theta2=-0.05, nu=0.3, rho=0.6)
call_on_max = fe.price(RainbowOption(strike=100.0, maturity=1.0, kind="max", spot2=95.0),
                       "vg2d", "fourier_2d", fwd2, vg2)

Exotics under stochastic volatility

from foureng.products import BermudanOption

fwd_sv = fe.ForwardSpec(S0=10.0, r=0.1, q=0.0, T=0.25)
heston = fe.HestonParams(kappa=5.0, theta=0.16, nu=0.9, rho=0.1, v0=0.0625)
bermudan = BermudanOption(strike=10.0, maturity=0.25, cp=-1,
                          exercise_times=np.linspace(0.025, 0.25, 10))
value = fe.price(bermudan, "heston", "cos_ctmc", fwd_sv, heston)

With AmericanOption(strike=10.0, maturity=0.25, cp=-1) the same call gives 0.52003 in about four seconds; Ikonen & Toivanen (2004) report 0.520038. Discretely monitored barriers take a BarrierOption(..., monitoring="discrete") and grid=<number of dates>. "bates" and "regime_switching" work the same way.

Calibration

true = fe.HestonParams(kappa=2.5, theta=0.06, nu=0.7, rho=-0.65, v0=0.04)
mats, ks = np.repeat([0.25, 0.5, 1.0], 7), np.tile(np.linspace(80.0, 120.0, 7), 3)
vols = []
for T, K in zip(mats, ks):
    f = fe.ForwardSpec(S0=100.0, r=0.02, q=0.01, T=T)
    c = fe.price_strip("heston", "contour", np.array([K]), f, true)
    vols.append(fe.implied_vol_lets_be_rational(c, f.F0, K, T, disc=f.disc)[0])

quotes = fe.MarketQuotes(S0=100.0, r=0.02, q=0.01, maturities=mats, strikes=ks, ivs=np.array(vols))
start = fe.HestonParams(kappa=1.0, theta=0.03, nu=0.3, rho=-0.2, v0=0.02)
fit = fe.calibrate("heston", quotes, start)
print(fit.values, fit.rmse_iv)

calibrate works for any registry model with float parameters. It uses analytic CF gradients for BSM, Merton, Kou, VG, NIG, CGMY, Heston and Bates and differences of the CF for the rest; parameters can be fixed (fixed=["rho"]), bounded and weighted.

API reference

Everything is importable from import foureng as fe.

Market inputs

Model parameter dataclasses

Full model details: docs/model_zoo.md.

Unified dispatcher

Method labels: "cos", "cos_improved", "cos_filtered", "carr_madan", "frft", "conv", "hilbert", "sinc", "swift", "contour", "cos_bermudan", "cos_ctmc", "fourier_2d", "mellin", "proj", "pyfeng_fft", plus product-aware "asian_cf" / "variance_levy_analytic" / "forward_start_cf" / "cliquet_cf" / "fader_cf" (exact Lévy geometric Asians, variance-swap strikes, forward-starts, and locally collared cliquets) and "cos_digital" / "digital_bsm" / "monte_carlo" / "barrier_bsm" / "asian_bsm" / "asian_mc" / "double_barrier_mc" / "proj_double_barrier" / "forward_start_bsm" / "exchange_bsm" / "spread_bsm" / "multi_asset_mc" / "lookback_bsm" / "lookback_mc" / "variance_analytic_bsm" / "variance_mc" / "cliquet_mc" and SABR-only "sabr_hagan".

Product-level pricing uses price(product, model, method, fwd, params). It currently routes European options, cash-or-nothing and asset-or-nothing digitals via "cos_digital" or BSM "digital_bsm", supported 1-D Levy Bermudans via "cos_bermudan", BSM generic Monte Carlo / Longstaff-Schwartz via "monte_carlo" for Europeans, Americans, Bermudans, and the GBM-simulated exotic book, continuously monitored zero-rebate BSM single barriers via "barrier_bsm", BSM Asians via "asian_bsm" / "asian_mc", BSM forward-start options via "forward_start_bsm", BSM two-asset exchange options via "exchange_bsm" / "multi_asset_mc", BSM basket and best-of options via "multi_asset_mc", BSM spread options via "spread_bsm" / "multi_asset_mc", BSM lookbacks via "lookback_bsm" / "lookback_mc", BSM variance swaps via "variance_analytic_bsm" / "variance_mc", integrated-variance BSM options via "variance_analytic_bsm" and realised/integrated BSM variance options via "variance_mc", BSM cliquets via "cliquet_mc", BSM double barriers via "double_barrier_mc" / "proj_double_barrier", and, for 1-D Lévy models, Americans via "cos_american", discretely monitored barriers and floating- or fixed-strike lookbacks via "hilbert_barrier" / "hilbert_lookback" (pass grid=<int> for the number of monitoring dates), and arithmetic Asians via "asian_cos". Under heston, bates and regime_switching, Bermudans, Americans and discrete barriers go through "cos_ctmc"; exchange, spread, two-asset best-of and RainbowOption products go through "fourier_2d" with bsm or a two-asset model.

Path-dependent MC engines (foureng.mc)

All MC functions take a GBMPathSpec(n_paths, n_steps, seed, antithetic) configuration object.

Core pricing functions

Grid constructors

Implied volatility and Greeks

Full reference for all public objects: docs/api_reference.md.

License

MIT. See LICENSE.

Demo notebook

notebooks/demo.ipynb is the primary entry point. It runs Carr-Madan, COS, and FRFT on a Heston strip and works in Colab with no local setup.

Supplementary notebook

notebooks/supplementary/demo_advanced.ipynb is a supplementary reference for readers who want a comprehensive tour after the main demo. It covers the model zoo, the main Fourier pricers, Greeks, IV surface, Heston calibration, Monte Carlo, new models (Double Heston, VGSA), and validation highlights. It is not the recommended starting point.

Paper replications and research notebooks

Paper replications

Research notebooks

Validation summary

Full per-paper matrix: docs/paper_validation_matrix.md. Evidence-level definitions: docs/validation_hierarchy.md.

Reproduce results

After cloning and installing (see Installation above):

# fast CI suite (skips slow Monte Carlo and notebook-execution tests)
python -m pytest -q -m "not slow"

# full suite including notebook execution guards
python -m pytest -q

# paper-replication tests only
python -m pytest -q -m "paper"

# MathWorks Bates software-reference tests
python -m pytest -q -m "software_reference"

The repository has 2,300+ pytest cases.

For linting and type checks:

pip install -e ".[dev]"
ruff check foureng/ tests/
python -m mypy foureng

Course rubric map

Key papers

Full bibliography with DOIs and free-access links: docs/papers.md.

Roadmap

Transform-method territory not yet covered here, in rough priority order (the first block tracks capabilities popularized by the PROJ/CTMC MATLAB literature):

• PROJ double-barrier options under Lévy models (proj_double_barrier, 0.14.0)
• Fader options under Lévy models (fader_cf, 0.17.0)
• Step options (occupation-time payoffs, Linetsky 1999) under Lévy models (proj_step, 0.18.0)
• CTMC (continuous-time Markov chain) approximation: 1-D diffusions with local vol, European + American (ctmc, 0.21.0); stochastic-vol/SABR 2-D extension is future work
• Credit default swaps via transform methods (levy_cds_spread, 0.19.0)
• Swing options via transform methods (proj_swing, 0.20.0)
• Regime-switching jump-diffusion regimes (per-regime Merton blocks, 0.15.0)
• Stochastic-interest-rate hybrids (one-factor Hull-White composite CFs, hw_hybrid, 0.16.0)
• Machine-precision vectorised implied volatility (Let's Be Rational) (0.22.0)
• American options for Lévy models (COS Bermudans + Richardson) (0.22.0)
• Discrete barriers and floating/fixed lookbacks by the Hilbert transform; arithmetic Asians (ASCOS) (0.22.0)
• SINC, SWIFT and optimal-contour European engines (0.22.0)
• 4/2, BNS Γ-OU, lifted Heston, time-changed Lévy and generic affine models (0.22.0)
• Model-free variance and VIX-style index from option strips (0.22.0)
• Stochastic-volatility exotics: Bermudans, Americans and discrete barriers under Heston and Bates (COS with a variance chain) (0.23.0)
• Two-dimensional Fourier spread and rainbow options (Hurd & Zhou 2010) (0.23.0)
• Registry-driven calibration with analytic CF gradients (0.23.0)
• SABR and stochastic local volatility through the same variance-chain engine
• Asian and lookback options under stochastic volatility
• Baskets on more than two assets

Contributions welcome, see CONTRIBUTING.md.

Documentation

All reference documentation is indexed at docs/README.md: model zoo, full API, validation hierarchy, paper replication tables, filtered-COS extension, Bates/3/2 SV validation, AI workflow, and packaging checklist.