Key Steps to Enable Free-Threading in QuantLib

The first step is improve thread safety in QuantLib itself. It should be compiled with the thread-safe observer pattern enabled. Additionally, enabling sessions allows to separate singleton instances across different threads.

Next, adjustments are needed in QuantLib’s SWIG layer. The Py_LIMITED_API is currently incompatible with free-threading, so it must be removed from setup.py and setup.cfg. The module should also be explicitly marked as “no-gil” in the quantlib.i initialization routine. For a detailed breakdown of the modifications, please see the no-gil fork.

SWIG 4.3 itself is not fully prepared for free-threading in Python. The pyhead.swg file uses macros like PyTuple_GET_ITEM, which are not suited for this mode and should be replaced with limited API versions, such as PyTuple_GetItem. Additionally, many routines in swigrun.swg are not thread-safe, so any function involving swig_type_info needs to be wrapped with a lock guard to prevent race conditions. Update: Changes will be part of next SWIG 4.4 release (21.04.2025)

Results and Performance Gains

After these changes, the Python QuantLib module loads smoothly in Python 3.13’s free-threading mode. Benchmarking option pricing via finite difference methods shows the expected performance scaling on an 8-core (+8 HT) CPU, the example code can be found here.

.

In the following, Spread-Options are defined by with the special case of a two asset spread option with . Basket options are given by and Basket-Spread options by . Finally a vanilla option has . At the time being QuantLib Release 1.36 offers the following algorithms

The new teammates are:

• BjerksundStenslandSpreadEngine: Analytical approximation for 2d spread options [1].
• OperatorSplittingSpreadEngine: Analytical approximation for 2d spread options [2]. Unlike the original publication, the code for the second order approximation is generated by a Mathematica script and does not require any numerical derivatives.
• DengLiZhouBasketEngine: Analytical approximation for N-dim spread, basket and basket-spread options. This method is much better suited for spread options than for basket- or basket-spread options.
• ChoiBasketEngine: Semi-Analytical approximation, which is equally suitable for spread, basket and basket-spread options. The precision is governed by an integration parameter , and the method can efficiently achieve very high precision, particularly when the correlation matrix permits dimensional reduction of the problem. This engine supports semi-analytical delta calculation and control variates.
• FdndimBlackScholesVanillaEngine: A PDE-based method that leverages the PCA of the correlation matrix to reduce the dimensionality of the problem. The engine is equally suited for spread, basket and basket-spread options, although the number of dimensions should not exceed four. This method can also deal with Bermudan and American style options.

The benchmark suite for the probably most important case, the two asset spread option, consists of 55 test cases taken from the literature. The average relative error and average calculation time is summarized in the following table:

For this benchmark suite, the 2nd order Operator Splitting gives accurate results with outstanding runtime performance whereas the Choi methods can deliver unmatched accuracy. Every result is shown in the next diagram.

The next benchmark suite contains 21 spread and basket-spread options with three or four underlyings, again taken from different publications. The Deng-Li-Zhou algorithm provides very good runtime performance together with good accuracy but keep in mind that this method is best suited for spread options only. The Choi method is not only fast but also offers exceptional precision. All benchmark results are summarized in the following diagram:

One challenge with the Choi algorithm is selecting the appropriate value for the parameter . The results of all 76 benchmarks w.r.t. the parameter vs mean absolute error and vs runtime is summarized in the following two charts and might help to identify the optimal sweet spot.

The QuantLib implementation of these algorithms is part of the PR#2110.

[1] P. Bjerksund, G. Stensland: Closed from spread valuation
[2] C. F. Lo: Pricing Spread Options by the Operator Splitting Method
[3] M. Li, S. Deng, J. Zhou: Multi-Asset Spread Option Pricing and Hedging
[4] J. Choi: Sum of all Black-Scholes-Merton models: An efficient pricing method for spread, basket, and Asian options

for a time reversed boundary function with . Knowing the boundary function , the value of an American put option is given by

and the value of an American call option can be evaluated via the call-put symmetry [3]. The algorithm consists of four separate tasks and the precision of each task is steered by a separate parameter and the choice of an integration algorithm.

1. The early exercise boundary is interpolated on Chebyshev nodes [4].
2. The early exercise boundary is approximated using m fixed point iteration steps. The first iteration is a partial Jacobi-Newton step, the other m-1 steps are ordinary fixed point iterations.
3. Integrations during the fixed point iterations are either carried out using Gauss-Legendre integration of order l or a tanh-sinh integration with given tolerance ε.
4. A last integration along the early exercise boundary to get the American option value is using Gauss-Legendre integration of order p or a tanh-sinh integration with given tolerance ν.

It is important for the overall performance that all sub steps lead to a similar accuracy. The parameter space may be best explored with help of a benchmark portfolio, e.g. following [1]

,

and the best accuracy per runtime ratios for different parameter configurations. Each dot in the diagram below corresponds to the root mean square error (RMSE) of a different parameter configuration. The RMSE is calculated for all 6000 option prices in the benchmark portfolio and plotted against the runtime of a single option pricing. For comparison the results of the finite difference method have been added but PDEs can not compete with this algorithm (nor can the tree based algorithms in QuantLib).

This data set can be used to define the efficient parameter frontiers and take optimal parameter configurations from the frontiers. A fast configuration is Legendre integration for step 3 and 4 and

,

accurate is Legendre integration for step 3 and tanh-sinh integration for step 4 with

,

high precision is achieved with tanh-sinh for step 3 and 4 with

The implementation of this algorithm is not always straight forward and part of the PR#1495.

[1] L. Andersen, M. Lake and D. Offengenden: High Performance American Option Pricing

[2] L. Andersen and M. Lake: Fast American Option Pricing: The Double Boundary Case

[3] R. McDonald and M. Schroder: A parity Result for American Options

[4]. S.A. Sarra: Chebyshev Interpolation: An Interactive Tour

Even then – other than in Java/Scala/C# or C++ – there is not much to gain in Python by default because the SWIG generated interface code will not release the GIL while running C++ code. Hence all threads except one will block when running long lasting QuantLib computations. But not all hope is lost, SWIG can be instructed to release the GIL before calling QuantLib methods with the command line parameter “-threads”. The only caveat here is that some of QuantLib’s SWIG interface files contain low level Python C API calls like e.g. Py_XDECREF. Every block with low level Python C API calls has to be guarded with the SWIG_PYTHON_THREAD_BEGIN_BLOCK macro at the beginning of the block to acquire the GIL, in total 60 times.

As a reward, the GIL will be released when running QuantLib code in Python and multi-threading can be used to speed-up multiple, long lasting QuantLib calls in the same manner as in the other languages.

to get – for a given accuracy – to the smallest possible lattice grids. The Heston model parameters at hand are

,

the strikes of the benchmark options are given by

and the maturity of the options should be one year. First let’s use a five point stencil in direction. As expected the order of convergence is increasing from second to fourth order.

The same experiment but now with five point stencil also in direction is shown below. Finite lattice effects show-up already at relatively small lattices due to the high convergence speed.

In time direction Richardson extrapolation can be used to increase the order of convergence from two to three.

So finally for this parameter set if the aim is to get the average pricing error below then a lattice size of

seems to be sufficient when using five point stencil operators in and direction and Richardson extrapolation in time direction. Unfortunately for a given accuracy this technique is slower than the usual suspects, e.g. Operator splitting because the matrix inversion for the Crank-Nicolson scheme has to be carried out by an iterative solver, namely by BiCGstab. The code for the numerical experiments can be found in the test case

NthOrderDerivativeOpTest::testHigerOrderHestonOptionPricing().

.

A lengthy calculation of the asymptotic expansion up to gives

with

High vol of vol leads to small and in turn to a very slowly decaying integrand which renders any type of Black-Scholes control variate

useless. On the other side the integral over the asymptotic expansion has an easy to evaluate semi-analytic solution

with the special functions aka trigonometric integrals

This function can act as a highly efficient control variate for these otherwise difficult to handle high vol of vol parameter sets. A comparison with the Black-Scholes control variate is shown in the diagram below using Gauss-Laguerre integration of different orders .

As a rule of thumb the control variate based on the asymptotic expansion of the characteristic function outperforms the standard Black-Scholes control variate if 

.

The QuantLib implementation of the algorithm is part of the PR#898.

Status quo: Efficient pricing routines for the Heston model

are based on the integration over the normalized characteristic function in the Gatheral formulation

in combination with a Black-Scholes control variate to improve the numerical stability of Lewis’s formula [1][2][3]. The normalized characteristic function of the Black-Scholes model is given by

and the price of a vanilla call option can then be calculated based on

where is the corresponding Black-Scholes price. Different choices for the volatility of the control variate are discussed in the literature. For the following examples the volatility will be defined by either

or

.

The first one matches the overall variance for whereas the latter one matches the values of the characteristic functions at the starting point of the integration. Usually the latter choice gives better results. Looking at the integrand above one can directly spot a weak point in the algorithm for deep in the money/deep out of the money options. In this case the integrand becomes a highly oscillating function due to the term

.

Second, when using Gauss-Laguerre quadrature the overlap of the weight function with the characteristic function becomes sub-optimal for very short maturities or small effective volatilities as can be seen with the Black-Scholes characteristic function already.

Third, for very small the integrand becomes prone to subtractive cancellation errors.

The last issue is easy to overcome by using the second order Taylor expansion of the normalized characteristic for small . The corresponding mathematica script can be seen here.

Rescaling the integrand improves the second issue by rewriting the integral in terms of with

The first problem, the highly oscillating integrand, can be tackled with the exponentially fitted Gauss-Laguerre quadrature rule [4]. The numerical integration of two smooth functions and with

is approximated by a Gauss-Laguerre quadrature rule of the form

.

In this use case the frequency is

,

and the weights and nodes of the Gauss-Laguerre quadrature rule become functions of the frequency . The algorithm outlined in [4] is too slow to be used at runtime and in the original form only usable up to . In order to use it for the Heston model we pre-calculate the weights and nodes for a defined set of frequencies . The closest pre-calculated value for a given frequency is then used to evaluate the integral. Of course it would be optimal to use the weights and nodes for instead of but it is far, far better than assuming as it is done within the conventional Gauss-Laguerre quadrature rule.

Two techniques are key to get to larger N for the pre-calculated weights and nodes:

• Start the algorithm with to get the standard Gauss-Laguerre weights/nodes and gently increase afterwards. Use the old weights and nodes from the previous up to 20 steps to generate the next starting vector for the Newton solver based on the Lagrange interpolating polynomials.
• Increase “numerical head room” by using the boost multi-precision package instead of double precision. This is only relevant for the pre-calculation. The resulting weights and nodes are stored as normal double precision values.

The source code to generate the weights and nodes for the exponential fitted Gauss-Laguerre quadrature rule is available here.

The reference results for the comparison with the other Heston pricing methods are generated using a boost multi-precision version of the Gauss-Laguerre pricing algorithm of order N=2000. Comparison with the results for N=1500 and N=2500 ensures the correctness of the results. The exponentially fitted Gauss-Laguerre quadrature rule is always carried out using N=48 nodes, corresponding to only 48 valuations of the characteristic function. First example model is

Exponential fitting outperforms the other methods especially when taking the total number of characteristic function valuations into consideration. As expected the method works remarkable well for deep OTM/ITM options and ensures that the absolute pricing error stays below for an extremely large range of option strikes. Next round, same model but .

Again the pricing error for exponential fitting stays below for all moneynesses between -15 and 15 and well below the other methods. Next test, same model but very short maturity with . The COS-method with 250 calls of the characteristic function and exponential fitting with N=48 are close together and outperform all other methods.

The same graphs are shown for a variety of different Heston parameters being used in the literature in the following document. The exponentially fitted Gauss-Laguerre quadrature rule with only 64 nodes solves the problem almost always with for moneynesses between -20 and 20 and maturities between one day and 10 years and outperforms the other methods, especially when taking the number of characteristic function calls needed into consideration. This method can also be extend to larger number of nodes.

The QuantLib implementation of the algorithm is part of the PR#812.

[1] Lewis, A. A simple option formula for general jump-diffusion and other exponential Lévy processes

[2] F. Le Floc’h, Fourier Integration and Stochastic Volatility Calibration.

[3] L. Andersen, and V. Piterbarg, 2010,  Interest Rate Modeling, Volume I: Foundations and Vanilla Models,  Atlantic Financial Press London.

[4] D. Conte, L. Ixaru, B. Paternoster, G. Santomauro, Exponentially-fitted Gauss–Laguerre quadrature rule for integrals over an unbounded interval.

and the n-th moment of the probability distribution Z is then given by

The moment generating function is known for many financial models. Hence it is natural to derive approximations to exact pricing formulas based on the moment generating function.

The Kluge model [1] with exponential jump size distribution may serve here as a test bed for this approach. It is defined by

where is a Poisson process with jump intensity and is the inverse jump size. To match today’s forward curve the function is given by

The moment generating function for the log spot process

is then given by [1]

The pricing approximation formulas are based on the central moments

Mathematica calculates the first four central moments as

Approximations to Black-Scholes like log-normal models with higher moments are summarized in [2]. These extensions are parameterized in terms of the Fisher parameters for sknewness and kurtosis

Corrado and Su [3] get for an European call option price with third and fourth order corrections

whereas in 1998 Rubinstein [4] derived the following approximation considering a normal Edgeworth series expansion

Two regimes are considered to test the quality of the different approximations for the Kluge model. First a regime with relatively small jumps but changing jump intensity and second a regime with a few jumps but changing jump size. The test parameters are

The reference results for Euopean vanilla calls are generated with the corresponding finite difference pricing engine and Richardson extrapolation. First test case is to vary the number of jumps by increasing from zero to 40.The Corrado/Su fourth order approximation wins only for very small jump intensities, whereas for larger jump intensities the Corrado/Su approximation up to third order competes head-to-head against the Rubinstein formula. Similar picture can be seen for the second test case, few jumps with increasing jump size. For small jumps the fourth order approximation takes the lead but for most of the time the Rubinstein approximation gives the best results.

Source code for these results can be taken from the PR #728.

[1] Kluge, T. : Pricing Swing Options and other Electricity Derivatives
[2] Jurczenko, E, Maillet, B and Negrea, B: Multi-moment Approximate Option Pricing
Models: A General Comparison (Part 1)
[3]  Corrado C. and T. Su: Implied Volatility Skews and Stock Return
Skewness and Kurtosis Implied by Stock Option Prices , European Journal of
Finance 3, 73-85., 1997
[4] Rubinstein M: Edgeworth Binomial Trees, Journal of Derivatives
5 (3), 20-27., 1998

Very efficient approximations exist for the SABR model

like the original Hagan et. al. formula [1] or variants of it [2] but these analytic formulas are in general not arbitrage free. Solving the corresponding partial differential equation leads to an arbitrage free solution

but is computationally demanding. The basic idea here is to use a neural network or gradient boosted trees to interpolate (predict) the difference between the analytic approximation and the exact result from the partial differential equation for a large variate of model parameters.

First step is to reduce the number of dimensions of the parameter space by utilizing the scaling symmetry of the SABR model [3]

so that we can focus on the case without lose of generality

.

This in turns also limits the “natural” parameter space for which will be set to

.

Next on the list is to set-up an efficient PDE solver to prepare the training data. The QuantLib solver supports already the two standard error reduction techniques, namely adaptive grid refinement around important points and cell averaging around special points of the payoff. The latter one ensure a smooth second order convergence in spatial direction [4]. The Hundsdorfer-Viewer ADI scheme is also of second order in the time direction and additional Rannacher smoothing steps at the beginning will ensure a smooth convergence in the time direction as well [5].  Hence the Richardson extrapolation can be used to improve the convergence order of the overall algorithm. An example pricing for

is shown in the diagram below to demonstrate the efficiency of the Richardson extrapolation. The original grid size for scaling factor 1.0 is .

The training data was generated by a five dimensional quasi Monte-Carlo Sobol sequence for the parameter ranges

.

The strikes are equally distributed between the and quantile of the risk neutral density distribution w.r.t to the ATM volatility of the SABR model. The PDE solver will not only calculate the fair value for but for a range of spot values around . Using the scaling symmetry of the SABR model this can be utilized to calculate more prices with new and values for .

The training set includes 617K samples values.  The network is trained to fit the difference between the correct SABR volatility from the solution of the partial differential equation and the Floc’h-Kennedy approximation. It does not need a large neural network to interpolate the parameter space, e.g. the following Tensorflow/Keras model definition with 46K parameters has been used in the examples below

model = Sequential()
model.add(Dense(20, activation='linear', input_shape=(7, )))
model.add(Dense(100, activation='linear'))
model.add(Dense(400, activation='sigmoid'))
model.add(Dense(10, activation='tanh'))
model.add(Dense(1, activation='sigmoid'))
model.compile(loss='mae', optimizer='adam')

As always it is important for the predictive power of the neural network to normalize the input data e.g. by using sklearn.preprocessing.MinMaxScaler. The out-of-sample mean absolute error of the neural network is around 0.00025 in annualized volatility, far better than the Kennedy-Floc’h or Hagan et al approximation.

The diagram below shows the difference between the correct volatility and the different approximations using the parameter example from the previous post. One could also used gradient tree boosting algorithms like XGBoost or LightGBM. For example the models

xgb_model = xgb.XGBRegressor(nthread=-1,
                             max_depth=50,
                             n_estimators=100,
                             eval_metric ="mae")

gbm_model = lgb.train({'objective': 'mae',
                       'num_leaves': 500 }
                      lgb.Dataset(train_X, train_Y),
                      num_boost_round=2000,
                      valid_sets=lgb_eval,
                      early_stopping_rounds=20)

result in similar out-of-sample mean absolute errors of 0.00030 for XGBoost and 0.00035 for LightGBM. On the first glance the interpolation looks smooth as can be seen in the diagram below using the same SABR model parameters, but zooming into it exposes non differentiable points, which defeats the object of stable greeks.

The average run time for the different approximations is shown in the tabular below.

With this highly efficient pricing routines calibration of the full SABR model can be done in a fraction of a second. To test this approach several Heston parameter configurations have been used to calculated the implied volatility of 15 benchmark options for a single expiry. The full SABR model has been calibrated against these volatility sets with help of a standard Levenberg-Marquardt optimizer by either using the PDE pricer or the neural network pricer. As expected the neural network calibration routine has only taken 0.2 seconds but the PDE calibration has taken over half an hour on average.

[1] P. Hagan, D. Kumar, A. Lesnieski, D. Woodward: Managing Smile Risk.
[2] F. Le Floc’h, G. Kennedy: Explicit SABR Calibration through Simple Expansions.
[3] H. Park: Efficient valuation method for the SABR model.
[4] K. in’t Hout: Numerical Partial Differential Equations in Finance explained.
[5] K. in’t Hout, M. Wyns: Convergence of the Hundsdorfer–Verwer scheme for two-dimensional convection-diffusion equations with mixed derivative term