Getting started

PyQL - an overview

Why building a new set of QuantLib wrappers for Python?

The SWIG wrappers provide a very good coverage of the library but have a number of pain points:

  • Few Pythonic optimisations in the syntax: the python code for invoking QuantLib functions looks like the C++ version;
  • No docstring or function signature are available on the Python side;
  • The debugging is complex, and any customization of the wrapper involves complex programming;
  • The build process is monolithic: any change to the wrapper requires the recompilation of the entire project;
  • Complete loss of the C++ code organisation with a flat namespace in Python;
  • SWIG typemaps development is not that fun.

For those reasons, and to have the ability to expose some of the QuantLib internals that could be very useful on the Python side, we chose another road. PyQL is build on top of Cython and creates a thin Pythonic layer on top of QuantLib. It allows a tight control on the wrapping and provides higher level Python integration.

Features:

  • Integration with standard datatypes (like datetime objects) and numpy arrays;
  • Simplifed API on the Python side (e.g. usage of Handles completely hidden from the user);
  • Support full docstring and expose detailed function signatures to Python;
  • Code organised in subpackages to provide a clean namespace, very close to the C++ code organisation;
  • Easy extendibility thanks to Cython and shorter build time when adding new functionalities;
  • Sphinx documentation.

Building and installing PyQL

Prerequisites:

  • Boost (version 1.55 or higher)
  • QuantLib (version 1.5 or higher)
  • Cython (version 0.19 or higher)

Once the dependencies have been installed, enter the pyql root directory. Open the setup.py file and configure the Boost and QuantLib include and library directories, then run

python setup.py build

Installation from source

The following instructions explain how to build the project from source, on a Linux system. The instructions have been tested on Ubuntu 12.04 LTS.

Prerequisites:

  • python 2.7
  • C++ development environment
  • pandas 0.9

  1. Install Boost (taken from a nice post by S. Zebardast)

    1. Download the Boost source package

      wget -O boost_1_55_0.tar.gz \
http://sourceforge.net/projects/boost/files/boost/1.55.0/boost_1_55_0.tar.gz/download
tar xzvf boost_1_55_0.tar.gz

    2. Make sure you have the required libraries

      sudo apt-get update
sudo apt-get install build-essential g++ python-dev autotools-dev libicu-dev libbz2-dev

    3. Build and install

      cd boost_1_55_0
sudo ./bootstrap.sh --prefix=/usr/local
sudo ./b2 install

      If /usr/local/lib is not in your path:

      sudo sh -c 'echo "/usr/local/lib" >> /etc/ld.so.conf.d/local.conf'

      and finally:

      sudo ldconfig

  2. Install Quantlib

    1. Download Quantlib 1.5 from Quantlib.org and copy to /opt

      wget -O QuantLib-1.5.tar.gz  \
http://sourceforge.net/projects/quantlib/files/QuantLib/1.5/QuantLib-1.5.tar.gz/download
sudo cp QuantLib-1.5.tar.gz /opt

    2. Extract the Quantlib folder

      cd /opt
sudo tar xzvf QuantLib-1.5.tar.gz

    3. Configure QuantLib

      cd QuantLib-1.5
./configure --disable-static CXXFLAGS=-O2 --with-boost-include=/usr/local/include --with-boost-lib=/usr/local/lib

    4. Make and install

      make
sudo make install

  3. Install Cython. While you can install Cython from source, we strongly recommend to install Cython via pip:

    pip install cython

    If you do not have the required permissions to install Python packages in the system path, you can install Cython in your local user account via:

    pip install --user cython

  4. Download pyql (https://github.com/enthought/pyql), then extract, build and test:

    $ cd ~/dev/pyql
$ make build
$ make tests

If you have installed QuantLib in a directory different from /opt, edit the setup.py file before running make and update the INCLUDE_DIRS and LIBRARY_DIRS to point to your installation of QuantLib.

Installation from source on Windows

The following instructions explain how to build the project from source, on a Windows system. The instructions have been tested on Windows 7 32bit with Visual Studio 2008.

Prerequisites:

  • python 2.7 (e.g. Canopy with Cython 0.20 or above)
  • pandas 0.9

  1. Install Quantlib

    1. Install the latest version of Boost from sourceforge. You can get the binaries of 1.55 for windows 32 or 64bit depending on your target.

    2. Download Quantlib 1.5 from Quantlib.org and unzip locally

    3. Extract the Quantlib folder

    4. Open the QuantLib_vc9 solution with Visual Studio

    5. Patch ql/settings.hpp.

      In the ql/settings.hpp file, update the Settings class defintion as following (line 37):

      class __declspec(dllexport) Settings : public Singleton<Settings> {

    6. In the QuantLib project properties

    • Change “General” -> “Configuration type” to “Dynamic Library (DLL)”
    • Apply
    • Add the Boost include directory to “C/C++” -> “Additional Include Directories”
    • Apply

    Do a first build to get all the object files generated

    1. Generate the def file:

    In your PyQL clone, got the scripts directory, and edit the main function. Set input_directory to the Release directory where your object files are and change the output_file if appropriate (symbol_win32.def is the default) ! The def file is platform specific (you can’t reuse a 32bit def file for a 64bit linker).

    This will generate a def file of about 44 Mb with all the needed symbols for PyQL compilation.

    1. Build the dll with the new def file
    • Change “Linker” -> “Input” -> “Module definition file” to point to def file you just generated.
    • Apply the changes and build the project
    1. Copy the QuantLib.dll to a directory which is on the PATH (or just the PyQL directory if you’re in development mode)

  2. Install Cython. While you can install Cython from source, we strongly recommend to install Cython via the Canopy Package Manager, another Python distribution or via pip:

    pip install cython

    If you do not have the required permissions to install Python packages in the system path, you can install Cython in your local user account via:

    pip install --user cython

  3. Build and test pyql

    Edit the setup.py to make sure the INCLUDE_DIRS and LIBRARY_DIRS point to the correct directories.

    PS C:\dev\pyql> python setup.py build
PS C:\dev\pyql> python setup.py install

    Note

    Development mode

    If you want to build the library in place and test things, you can do:

    PS C:\dev\pyql> python setup.py build_ext --inplace
PS C:\dev\pyql> python -m unittest discover -v