regimelib

QuantLib’s models with a hidden Markov regime, priced by the fast-switching expansion.

A regime is a finite-state Markov chain that the market does not observe directly. Any parameter of a QuantLib model may take a different value in each regime: the Vasicek mean level, the Black–Scholes volatility, the Heston long-run variance, a jump intensity, a default intensity. regimelib prices the usual instruments under such models in QuantLib’s mold — setPricingEngine, NPV(), greeks as methods on the instrument — with three tiers of engine: the fast-switching expansion in the mean holding time of the chain, the numerical solution of the reduced system it expands, and grids and Monte Carlo for early exercise and paths.

Every model has a frozen limit, all regimes equal, in which it is QuantLib’s model; every certificate in the test suite checks that limit against QuantLib’s own engine and then checks the switching case against an independent referee.

The method and its checks are written up in Cotton (2026), Security and Derivative Pricing with Fast Regime Switches, arXiv:2611.00466.

Dedication

regimelib is dedicated to Jean-Pierre Fouque, Distinguished Professor of Statistics and Applied Probability at UC Santa Barbara, as he approaches retirement.

Fouque was instrumental in bringing homogenization and multiscale asymptotics to finance. With George Papanicolaou and Ronnie Sircar he priced derivatives by an expansion in the time scale of a fast volatility factor, in Derivatives in Financial Markets with Stochastic Volatility (Cambridge University Press, 2000), and with Knut Sølna extended it in Multiscale Stochastic Volatility for Equity, Interest-Rate and Credit Derivatives (Cambridge University Press, 2011). The engine here runs the same kind of expansion. There the fast factor is a mean-reverting volatility process. Here it is a finite Markov chain.

The center he co-directs at UC Santa Barbara turns twenty in 2027: Dedication.

import regimelib as rl

chain = rl.RegimeChain.twoState(3.0, 5.0)              # rates out of regime 0 and out of regime 1
model = rl.SwitchingVasicek(chain, r0=0.03, a=0.5, b=[0.06, 0.02], sigma=[0.015, 0.008])
bond = rl.ZeroCouponBond(5.0)
bond.setPricingEngine(rl.FastSwitchingEngine(model, order=4, regime=0))
print(bond.NPV(), bond.delta(), bond.gamma())

Models

Each model has one page with its mathematics and the Python that evaluates it: the dynamics, the reduction to a linear system, the closed form for a two-regime chain, and that closed form computed next to the library’s price.

The common formula, the helpers and the index table are on Models: mathematics and Python.

Getting started

Examples