quantlib-wasm

A wrapper of the quantitative finance library Quantlib. Compiled as a WebAssembly for use in browsers and in Node.JS.

WARNING: This is work in progress and in alpha mode.

Install

npm install quantlib-wasm

Usage with React

import quantlibWasm from "quantlib-wasm";
import wasm from "quantlib-wasm/dist/quantlib.wasm";

const MyReactComponent = () => {
  const [quantLibLoaded, setQuantLibLoaded] = useState(false);
  const [QuantLib, setQuantLib] = useState(null);

  useEffect(() => {
    if (!quantLibLoaded) {
      quantlibWasm({
        locateFile: (path) => (path.endsWith(".wasm") ? wasm : path),
      }).then((loaded) => {
        setQuantLib(loaded);
        setQuantLibLoaded(true);
      });
    }
  });
  
  ....

Introduction

Quantlib is a quantitative finance library, used for pricing, hedging and valuation of financial sequrities and derivatives. It's open source and widely used. The library is written in C++ and it has been exported to many languages such as Python, Java and C#.

How about exporting QuantLib to JavaScript? In Node.js there are many ways of importing external libraries, including node-gyp, addons and N-API. None of these techniques work client side in a browser. WebAssembly on the other hand, works both client and server-side.

WebAssembly (Wasm) is a sandboxed environment running inside the JavaScript virtual machine. High-level languages like C/C++ can be compiled into the Wasm. WebAssembly is supported by four major browsers (Chrome, Firefox, Safari and Edge). Therefore, QuantLib as WebAssembly can be used from JavaScript both client (web browser) and server-side (Node.js).

Working with QuantLib in JavaScript

QuantLib is an object oriented library, rather than functional oriented. The QuantLib calculations are done with many objects, such as Date, Calendar, Schedule, PricingEngine, YieldCurve and all kind of instrument objects. These objects can be exported and used in JavaScript. The code in JavaScript will be similar to versions in Python or C++.

Here is a schedule generator example:

const { Date, TimeUnit, Schedule, Period, BusinessDayConvention, DateGenerationRule } = QuantLib;
var effectiveDate = Date.fromISOString("2019-08-19");
var terminationDate = Date.fromISOString("2020-08-19");
var period = new Period(3, TimeUnit.Months);
var firstDate = new Date();
var nextToLastDate = new Date();
var schedule = new Schedule(
    effectiveDate,
    terminationDate,
    period,
    QuantLib.TARGET,
    BusinessDayConvention.ModifiedFollowing,
    BusinessDayConvention.ModifiedFollowing,
    DateGenerationRule.Backward,
    true,
    firstDate,
    nextToLastDate
);
var dates = schedule.dates();
for (let i = 0; i < dates.size(); i++) {
    let d = dates.get(i);
    console.log(d.toISOString());
    d.delete();
}
[effectiveDate, terminationDate, period, firstDate, nextToLastDate, dates, schedule].forEach((d) => d.delete());

Emscripten

This implementation uses Emscripten to compile QuantLib. Emscripten compiles C++ into low level JavaScript called asm.js, which is highly optimizable and can be executed at close to native speed. A long list of projects are already using Emscripten to port codebases to JavaScript.

Embind is used to bind C++ functions and classes to JavaScript. The bindings are done with a few lines of code. The technique for defining bindings is similar to Boost Python.

The easiest way to run the Emscripten environment is in a prebuild Docker container. trzeci/emscripten is a good container and when running it compilations are done with the emcc compiler via the command prompt. The three projects Emscripten, QuantLib and Boost (which is a dependency of QuantLib) and wrapped together in a container called captorab/emscripten-quantlib. Running in a docker container saves a lot of time. The operating system issues and the configuration are done once and can easily be shared among developers.

Memory management

When using Wasm and Embind, there is one catch though. Memory management must be handled in both the JavaScript and the Wasm environment. In JavaScript, objects are destructed automatically, but before leaving a QuantLib object in JavaScript a delete command needs to be sent to the Wasm, to destruct the C++ object. This must be done explicitly since the JavaScript objects do not have any finalizer. This is something high level programmers assume the environment will do automatically. Unfortunately this is not done automatically between the two memory areas, one in JavaScript and one in the Wasm. In the example above delete is called on the last line in the for loop and on the very last line of code.

Code like the example below cannot be used because it hides the destructor of the Date-object.

console.log(Date.fromISOString("2019-08-19").toString()); // This causes a memory leak.

Here is the correct equivalent:

var date = Date.fromISOString("2019-08-19");
console.log(date.toString());
date.delete();

Memory usage can be measured in the Wasm at any time, and memory leaks can be detected.

const { Date, mallinfo } = QuantLib;
var m0 = mallinfo();
var date = Date.fromISOString("2019-08-19");
console.log(date.toString());
date.delete();
var m1 = mallinfo();
console.log(m1.uordblks - m0.uordblks + (m1.hblkhd - m0.hblkhd)); // Should print 0

Using the wasm in a React app

React in itself can easily use the Quantlib wasm. See the method above. When the app is build with create-react-app, webpack is used to load and build the source files. By default (version 3.1.1 or earlier of react-scripts), doesn't load wasm files. To bypass this problem Facebook's react-scripts can be forked and modified. How this is done is explained here.

One fork that loads wasm files is @captor/react-scripts. To create a new app that with the modifies script run:

npx create-react-app <app-name> --scripts-version @captor/react-scripts

Or, in an already existing app, change the installed script reference.

npm uninstall react-scripts
npm install @captor/react-scripts

Add quantlib-wasm to the app:

npm install quantlib-wasm

Status

Which objects and functions are exported? There is no documentation written yet. Until this project turns into alpha mode, the only reliable way is to check the code. In this case the binding file is the right place. It's found here.

Versioning

quantlib-wasm does not follow https://semver.org/, but the version from Quantlib with an extra number to version the quantlib-wasm package.

Development

In order to build a new version, when a new Quantlib version is available

git checkout -b $QUANTLIB_VERSION

In:

• .circleci/config.yml
• Dockerfile
• Makefile
• package.json

update from old version number to "${QUANTLIB_VERSION}"."${version}"

make build_docker_image
make build_bindings_from_unix
npm i
npm test
npm pack
npm publish