Kalotay
Analytics
A Division of Andrew Kalotay Associates, Inc.
BondOAS™ Library Getting Started

Requirements

Building an application using the BondOAS™ library requires only two BondOAS™ files: the bondoas library file and the API definition file, akaapi.hpp.

BondOAS™ has releases for a wide group of operating systems and architectures. There is no minimum hardware requirement.

A Very Simple Example

BondOAS™ is as simple or as sophisticated as you need it to be. The C++ API (or the Java and C# APIs which closely follow the C++ API) provide constructors and methods which default to reasonable and common values.

The following is a simple program fragment:

#include "akaapi.hpp" using namespace AndrewKalotayAssociates; ... // The Initialization object must be successfully created and authorized Initialization init; if (init.Authorize("./akalib.key") > 0) { // read key from a file cerr << "Error: " << init.ErrorString() << endl; return init.Error(); } // Create both an interest rate model and a bond object Bond bond("simple", Date(2010, 1, 1), Date(2020, 1, 1), 3.5); // 10yr, 3.5% InterestRateModel model; model.SetRate(1, 2.0); // set a flat 2% rate model.Solve(); if (model.Error() > 0) { cerr << "Error: " << model.ErrorString() << endl; return model.Error(); } // Now value the bond Value value(bond, model, Date(2013, 7, 1)); if (value.Error() > 0) { cerr << "Error: " << value.ErrorString() << endl; return value.Error(); } double oas = value.OAS(price); // oas at a given price

Only one include file, akaapi.hpp, is required to program with the library. All symbols in akaapi.hpp are under the namespace AndrewKalotayAssociates.

The first step in building a Bondoas™ application is initializing the library. This needs to be done exactly once. The status of the initialization can be checked with the Error() method. All BondOAS™ objects inherit from the Status object which provides the Error() method.

Once the library is initialized a bond can be created. In this case a thirty year, 2% bullet. Many additional characteristics of the bond can be specified. Please see the detailed API documentation.

Next, an interest rate environment must be instantiated. The above example sets only one rate, the 1 year, to 2%. This will result in a flat yield curve. Additional points could be set, of course. The interest rate model can also be configured for volatility and the type of input (par or discount). The interest rate model can also be queried for yields and discounts at any period. Please see the detailed API documentation.

Now we are ready to value the bond using the interest rate environment. A Value object is instantiated to do this. It requires the bond and environment as well as the valuation date. Note, we check the Error() status as with all objects. Finally we get the OAS at a price. There are many more values available through the Value object. Please see the detailed API documentation.

Getting A Little More Sophisticated

The bond in the simple example is a bullet bond and the yield curve is an unrealistic flat. Below we add a call option to the bond and use actual treasury rates from 2013. In addition to getting the OAS we compute the option value given the computed OAS. Below is an excerpt from the program verysimple.cpp which is in the example directory.

bond.SetCallAmerican(true); // not necessary as this is the default bond.SetNoticePeriod(15); // 15 days // add a declining call schedule bond.SetCall(Date(2014,01,01), 102); bond.SetCall(Date(2015,01,01), 101.5); bond.SetCall(Date(2016,01,01), 101); // set a realistic rate curve double terms[] = {.25, .5, 1., 2, 3, 4, 5, 7, 10, 20, 30 }; double rates[] = { 0.061, 0.111, 0.17, 0.43, 0.74, 1.115, 1.49, 2.03, 2.6, 3.31, 3.6 }; for (unsigned int i = 0; i < sizeof(terms) / sizeof(terms[0]); i++) model.SetRate(terms[i], rates[i]); model.SetVolatility(7.5); model.Solve(); if (model.Error() > 0) { cerr << "Error: " << model.ErrorString() << endl; return model.Error(); } value.Reset(bond, model, Date(2013, 7, 1)); if (value.Error() > 0) { cerr << "Error: " << value.ErrorString() << endl; return value.Error(); } oas = value.OAS(price); // oas at price double optval = value.OptionValue(oas);

Compiling

The C++ API is defined in a single include file, akaapi.hpp. It is in the include/ directory of the release.

The Bondoas™ library is released as both a dynamic and a static library. The library is called bondoas. The dynamic library is located in the akalib/{os-arch}/lib directory. For example, akalib/win32/lib. The static library is located in the library sub-directory static/.

The library is named in an operating system appropriate way. The Unix libraries are named libbondoas.so and static/libbondoas.lib. The Windows libraries are named bondoas.dll and static/bondoas.lib.

The above code fragment, slightly expanded, is in example/verysimple.cpp. The following sample compilation commands assume the source file being compiled is in a directory parallel to the lib/ and include/ directories. This is the case with the provided example/ directory. For a more general installation approach please see the BondOAS™ Installation document. The simplified compilation commands are:

For 32 bit Windows:

cl -Ox -W3 -MT -D_CONSOLE -D_CRT_SECURE_NO_DEPRECATE -nologo -I../include -I. verysimple.cpp /link -libpath:../win32/lib bondoas.lib

For 32 bit Linux:

g++ -O3 -Wall -I../include -I. verysimple.cpp -o verysimple -L../linux/lib -lbondoas -lm

Other operating systems, architectures, and compilers can be extrapolated from those examples..

Library Name Complexities Under Windows

The Windows library names are slightly complicated. The Microsoft C++ compiler is unable to link directly to the .dll. A stub link library is required. The stub link library is also called bondoas.lib. This library is in the top level lib/ directory and is distinct from the statically compiled library with the same name in the static/ sub-directory.

In addition the Windows release is packaged with a second static library, lib/static/bondoas_md.lib. The Microsoft compiler requires the C run-time library linkage to be specified at compile time by using either the /MD or /MT compilation switch. These switches determine which MSC library is expected to be linked with the object (or library containing the object) when creating an executable or dll. The Microsoft documentation specifies: "All modules passed to a given invocation of the linker must have been compiled with the same run-time library compiler option." The default bondoas static library is compiled with /MT. The static/ sub-directory also contains bondoas_md.lib in which the objects were compiled with /MD. For more information about these compile switches please refer to the Microsoft compiler documentation.

The additional Windows complexities are unfortunate, unavoidable, and universal.

More Examples

The BondOAS™ package comes with an example/ directory. The directory contains sample source files for C, C++, and Java. The C and C++ sources come with sample Makefiles. There is a GNU make Makefile, called Makefile.gmake which can be used to compile on any system, include Windows. There is also a Windows nmake Makefile, Makefile.nmake.

Conclusions

The BondOAS™ C++ API has a drill down approach to describing the complexities of the bond and interest rate environment. The simplest specifications require only a few lines of code. Additional features can be specified through the object method interface described in the API. Compiling and linking to the library is never complicated. Only one include file and one library are required.

Contents