Basics
Regime chains
- rl.RegimeChain(generator)
The hidden regime is a continuous-time Markov chain given by its generator matrix Q (rows sum to zero, off-diagonal
entries are the switching rates). Any number of regimes is allowed.
chain = rl.RegimeChain([[-5.0, 3.0, 2.0],
[4.0, -9.0, 5.0],
[1.0, 6.0, -7.0]])
chain.numberOfRegimes() # 3
chain.stationaryDistribution() # the long-run occupation of each regime
chain.meanHoldingTime() # n / -trace Q, the expansion parameter
- rl.RegimeChain.twoState(rate12, rate21)
The two-regime chain with switching rate rate12 out of regime 0 and rate21 out of regime 1.
chain = rl.RegimeChain.twoState(3.0, 5.0)
Chains from data
regimelib prices; it does not estimate, and it takes no position on how a chain is fitted or under which measure. What an estimator produces is usually a transition matrix at the data frequency and a probability for each regime at the last observation. Two functions connect those to the library.
- rl.RegimeChain.fromTransitionMatrix(P, dt)
The chain whose transition matrix over a step dt is P (rows are the regime now). Not every transition
matrix comes from a continuous-time chain: for two regimes it does exactly when p11 + p22 > 1, and in general
when its principal logarithm is a generator. A matrix that does not is refused, since how to move it to one that
does is a modelling choice.
- chain.transitionMatrix(dt)
exp(Q dt), the transition matrix of the chain over a step dt.
P = [[0.98, 0.02], [0.08, 0.92]] # monthly, from any estimator
chain = rl.RegimeChain.fromTransitionMatrix(P, 1 / 12)
model = rl.SwitchingVasicek(chain, r0=0.03, a=0.5, b=[0.045, 0.015], sigma=[0.006, 0.018])
bond = rl.ZeroCouponBond(5.0)
bond.setPricingEngine(rl.NumericalSwitchingEngine(model, regime=[0.3, 0.7])) # the filtered probabilities
bond.NPV()
The starting regime given as probabilities is the estimator’s belief at the last observation
(Observed and inferred regimes). A chain estimated from monthly or quarterly data typically switches slowly, where
NumericalSwitchingEngine is the engine to use; the expansion is for chains that switch fast against the life of
the instrument.
Per-regime parameters
A model parameter that may switch is given as a list with one value per regime, or as a scalar for the same value in every regime. The frozen limit — every regime equal — is the QuantLib model with those parameters, whatever the chain does; the certificates check each model against QuantLib in that limit.
rl.SwitchingVasicek(chain, r0=0.03, a=0.5, b=[0.06, 0.02], sigma=0.012) # b switches, sigma does not
Maturities and dates
Times are years. Wherever a maturity is expected, a QuantLib Date is also accepted and is measured from
ql.Settings.instance().evaluationDate with Actual/365 unless a dayCounter is given; a VanillaOption takes
its maturity from a QuantLib exercise object.
ql.Settings.instance().evaluationDate = ql.Date(1, 1, 2020)
bond = rl.ZeroCouponBond(ql.Date(1, 1, 2025))
option = rl.VanillaOption(ql.PlainVanillaPayoff(ql.Option.Put, 100.0),
ql.EuropeanExercise(ql.Date(1, 1, 2021)))
Instruments, engines and results
- instrument.setPricingEngine(engine)
- instrument.NPV()
- instrument.delta(), instrument.gamma(), instrument.theta(), instrument.vega(), instrument.rho()
As in QuantLib, an instrument holds its terms, an engine holds the model and the method, and NPV() triggers the
calculation. The greeks are computed by differentiating the pricing formula, never by bumping; a greek the engine
does not provide raises RuntimeError("... not provided by the engine"), as QuantLib’s “not provided” does.
Options under the characteristic-function engines:
delta,gamma,theta,rhoin the spot, andvegain the initial variance for stochastic-volatility models.Bonds under Vasicek and CIR:
deltaandgammain the short rate.Options on the finite-difference engine:
delta,gamma,thetafrom the grid.
option.setPricingEngine(rl.NumericalSwitchingEngine(model, regime=1))
option.NPV()
option.delta()
option.impliedVolatility() # the Black volatility reproducing the price
Regimes and the starting regime
Every engine takes regime, the regime in force today. The price of the same instrument differs by starting
regime; the difference is the memory of the regime, which the expansion carries in its initial-layer terms.
for regime in range(chain.numberOfRegimes()):
option.setPricingEngine(rl.FastSwitchingEngine(model, order=4, regime=regime))
print(regime, option.NPV())
Warnings and diagnostics
- class rl.ExpansionWarning
The expansion is asymptotic in the mean holding time times the forcing, so it can fail to converge: for a slow chain,
a large difference between regimes, or at high Fourier frequencies. FastSwitchingEngine raises an
ExpansionWarning when the last term kept is not smaller than the one before it, when it is more than a
thousandth of the value, or when nodes of the Fourier integral had to be solved numerically because the series
diverged there. instrument._result("diagnostics") returns the holding time, the order used, the relative size
of the last term and the count of numerical nodes.
import warnings
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
price = option.NPV()
for w in caught:
print(w.message)
option._result("diagnostics")