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.
Short rates and credit: Vasicek, Cox–Ingersoll–Ross, Hull–White, G2++, Intensity basket
Equity diffusions: Black–Scholes, Heston, CEV, Heston with a switching volatility of variance
Jump models: Vasicek with jumps, Merton jump diffusion, Bates, Variance gamma
Hybrid: Equity with stochastic rates
Instruments: Options on bonds, swaptions and caps, Other instruments
Information: Observed and inferred regimes, on observed and inferred regimes
The common formula, the helpers and the index table are on Models: mathematics and Python.
Models: mathematics and Python
Getting started
Background
Examples