Skip to content

QuantLib Integration

As a demonstrator of integration with real-world code, the latest release of QuantLib is AAD-enabled with XAD. The performance achieved on sample applications is many-fold superior to what has been reported previously with other tools. This demonstrates production quality use of the XAD library in a code-base of several hundred thousand lines.

A small adaptor module (also open-source) is required between the two projects, which contains build instructions as well as XAD-specific tests and examples.

Getting Started

1. Repository Clone/Checkout

Clone these three repositories into separate folders:

It is recommended to either use the lastest master branch for all repositories involved, or use matching tags between QuantLib and quantlib-xad.

2. Install Boost

A recent version of boost is a requirement for building QuantLib. If you do not have it already, you need to install it into a system path. You can do that in one of the following ways, depending on your system:

  • Ubuntu or Debian: sudo apt install libboost-all-dev
  • Fedora or RedHat: sudo yum install boost-devel
  • MacOS using Homebrew: brew install boost
  • MacOS using Mac Ports: sudo port install boost

  • Windows using Chocolatey:

    • For Visual Studio 2022: choco install boost-msvc-14.3
    • For Visual Studio 2019: choco install boost-msvc-14.2
    • For Visual Studio 2017: choco install boost-msvc-14.1

  • Windows using manual installers: Boost Binaries on SourceForge

3. Install CMake

You will also need a recent version of CMake (minimum version 3.15.0). You can also install this with your favourite package manager (e.g. apt, yum, homebrew, chocolatey as above), or obtain it from the CMake downloads page.

Note that Microsoft ships Visual Studio with a suitable version command-line only version of CMake since Visual Studio 2019 (the Visual Studio 2017 CMake version is outdated). It is available in the PATH from a Visual Studio command prompt and can alternatively be used directly from the IDE.

4. QuantLib CMake Configuration

The build is driven from the QuantLib directory - XAD and quantlib-xad are inserted using QuantLib's extension hook.

Configure the QuantLib CMake build with setting the following parameters:

  • QL_EXTERNAL_SUBDIRECTORIES=/path/to/xad;/path/to/quantlib-xad
  • QL_EXTRA_LINK_LIBRARIES=quantlib-xad
  • QL_NULL_AS_FUNCTIONS=ON
  • XAD_STATIC_MSVC_RUNTIME=ON

For Linux, the command-line for this is:

cd QuantLib
mkdir build
cd build
cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release \
  -DQL_EXTERNAL_SUBDIRECTORIES="`pwd`/../../xad;`pwd`/../../quantlib-xad" \
  -DQL_EXTRA_LINK_LIBRARIES=quantlib-xad \
  -DQL_NULL_AS_FUNCTIONS=ON \
  -DXAD_STATIC_MSVC_RUNTIME=ON

In Windows, you can use the CMake GUI to generate the build files, setting the same variables as above.

5. Building

The generated build files can now be built using the regular native build tools. For example, in Linux make can be run, and in Visual Studio, the solution can be opened and built. Note that we recommend Release mode for Windows builds.

6. Running the Tests

There are two test executables that get built - the regular QuantLib test suite with all the standard tests from the mainline repository, as well as the QuantLib XAD test suite from the quantlib-xad repository. Both are using the overloaded XAD type for double, but only the XAD suite checks for the correctness of the derivatives as well.

These executables can simply be run to execute all the tests. We recommend to use the parameter --log_level=message to see the test progress. Alternatively, CTest can also be used to execute them.

7. Running the Examples

Apart from the regular QuantLib examples, there are XAD-specific examples in the quantlib-xad repository, in the Examples folder. These demonstrate the use of XAD to calculate derivatives using AAD.

Benchmarks

Some of the examples in quantlib-xad are enabled for benchmarking. That is, the performance of the pricing and sensitivity calculation is measured, averaged over several iterations, for accurate performance reporting.

Further, setting the CMake option QLXAD_DISABLE_AAD to ON builds QuantLib and quantlib-xad with the default double datatype, enabling measurement of the same examples without the overheads involved in using a custom active data type. The benchmark-enabled examples calculate sensitivities using finite differences in that case, which also allows verifying correctness of the result against XAD.

Bechmark results:

QuantLib Example Sensitivites Valuation run (ms) AAD run (ms) AAD vs Valuation
Equity Option Portfolio 98 2.83 7.00 2.47x
Barrier Option Replication 13 1.48 4.16 2.81x
Swap Portfolio 55 26.05 36.28 1.39x
Multicurve Bootstrapping 65 192.11 299.63 1.56x

Benchmark configuration:

  • QuantLib version: 1.30
  • XAD version: 1.2.0
  • XAD configuration: XAD_USE_STRONG_INLINE=ON, XAD_NO_THREADLOCAL=ON, XAD_SIMD_OPTION=AVX512
  • OS: Windows Server 2022 Datacenter
  • Compiler: Visual Studio 2022, 17.6.1
  • RAM: 64GB
  • CPU: Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz

Getting Help

If you have found an issue, want to report a bug, or have a feature request, please raise a GitHub issue.

For general questions about the QuantLib to XAD integration, sharing ideas, engaging with community members, etc, please use GitHub Discussions.

Continuous Integration

To ensure continued compatibility with QuantLib's master branch, automated CI/CD checks are running in the quantlib-xad repository on a daily basis. Potential breaks (for example do to changes in QuantLib) are therefore detected early and fixed quickly.