A look at QuantLib usage and development, a Quants Hub online workshop. Click here for more info.

Monday, March 2, 2015

QuantLib notebook: numerical Greeks calculation

Hello everybody.

Here is the screencast of a new QuantLib notebook (in case you're new to this, the whole series in on both YouTube and Vimeo; choose the one that suits you best). In this one, I show how quotes can be used for the numerical calculation of Greeks.

And so that I don't waste a good segue into self-promotion, this was also one of the notebooks that I used in the workshop I recorded for QuantsHub. I hear there's a March sale going on, so this might be a good time to have a look.

That's all for this week. Turn the video below to full screen, sit back and enjoy.

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Liked this post? Share it:

Monday, February 16, 2015

A quick look at the 1.5 release

Welcome back.

Just a quick post to share some information on the latest QuantLib release (version 1.5, released this past Tuesday; grab it at this link if you haven't already) and to thank all the contributors that made it possible.

There were quite a few of them. A quick bit of git-fu shows that this release includes 566 commits by 16 authors (git shows 18, but two of them are different addresses for the same persons):

The actual contributors are more, though: a few people contributed patch files which were committed into the library by yours truly and thus don't show here. I have no way to retrieve all their names quickly, but you can find them in the list of changes for the 1.5 release. While I was compiling it, I also checked that the pull requests that made the release were tagged correctly, so it's also possible to search and display all 68 of them on GitHub: from that page you can drill down into any pull request that catches your interest and see what commits it contained, the code changes, and any discussion that went on before merging.

One final note: not including version 1.4.1, which only contained a bug fix, the previous version (QuantLib 1.4) was released in February 2014—one year ago. I think we should try and release more often. The content shouldn't be a problem, seeing how we already have 27 open pull requests as I write this (as well as a few very interesting projects that I'll describe in a future post).

I'll stop here for now. Thanks again to all those who contributed to the 1.5 release!

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Liked this post? Share it:

Monday, February 9, 2015

Odds and ends: global settings

Hello everybody.

This week, a section from the book appendix; namely, the one on the infamous Settings class. Feedback would be particularly appreciated on this one.

Did I mention that the workshop "A Look at QuantLib Usage and Development" I recorded for Quants Hub last October is now available for purchase? Right, I did. But in case you missed it, you can go back and read my last post for links and details. Oh, and I'm not the only QuantLib developer that did that; Ferdinando has recorded one as well—although it has nothing to do with QuantLib...

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Odds and ends: global settings

The Settings class, outlined in the listing below, is a singleton (I'll cover this pattern in a future post) that holds information global to the whole library.
    class Settings : public Singleton<Settings> {
        class DateProxy : public ObservableValue<Date> {
            operator Date() const;
        ... // more implementation details
        DateProxy& evaluationDate();
        const DateProxy& evaluationDate() const;
        boost::optional<bool>& includeTodaysCashFlows();
        boost::optional<bool> includeTodaysCashFlows() const;
Most of its data are flags that you can look up in the official documentation, or that you can simply live without; the one piece of information that you'll need to manage is the evaluation date, which defaults to today's date and is used for the pricing of instruments and the fixing of any other quantity.

This poses a challenge: instruments whose value can depend on the evaluation date must be notified when the latter changes. This is done by returning the corresponding information indirectly, namely, wrapped inside a proxy class; this can be seen from the signature of the relevant methods. The proxy inherits from the ObservableValue class template (outlined below) which is implicitly convertible to Observable and overloads the assignment operator in order to notify any changes. Finally, it allows automatic conversion of the proxy class to the wrapped value.
    template <class T>
    class ObservableValue {
        // initialization and assignment
        ObservableValue(const T& t)
        : value(t), observable_(new Observable) {}
        ObservableValue<T>& operator=(const T& t)  {
          value_ = t;
          return *this;
        // implicit conversions
        operator T() const { return value_; }
        operator boost::shared_ptr<Observable>() const {
          return observable_;
        T value_;
        boost::shared_ptr<Observable> observable_;
This allows one to use the facility with a natural syntax. On the one hand, it is possible for an observer to register with the evaluation date, as in:
on the other hand, it is possible to use the returned value just like a Date instance, as in:
    Date d2 = calendar.adjust(Settings::instance().evaluationDate());
which triggers an automatic conversion; and on the gripping hand, a simple assignment syntax can be used for setting the evaluation date, as in:
    Settings::instance().evaluationDate() = d;
which will cause all observers to be notified of the date change.

Of course, the elephant in the room is the fact that we have a global evaluation date at all. The obvious drawback is that one can't perform two parallel calculations with two different evaluation dates, at least in the default library configuration; but while this is true, it is also a kind of red herring. On the one hand, there's a compilation flag that allows a program to have one distinct \code{Settings} instance per thread (with a bit of work on the part of the user) but as we'll see, this doesn't solve all the issues. On the other hand, the global data may cause unpleasantness even in a single-threaded program: even if one wanted to evaluate just an instrument on a different date, the change will trigger recalculation for every other instrument in the system when the evaluation date is set back to its original value.

This clearly points (that is, quite a few smart people had the same idea when we talked about it) to some kind of context class that should replace the global settings. But how would one select a context for any given calculation?

It would be appealing to add a setContext method to the Instrument class, and to arrange things so that during calculation the instrument propagates the context to its engine and in turn to any term structures that need it. However, I don't think this can be implemented easily.

First, the instrument and its engine are not always aware of all the term structures that are involved in the calculation. For instance, a swap contains a number of coupons, any of which might or might not reference a forecast curve. We're not going to reach them unless we add the relevant machinery to all the classes involved. I'm not sure that we want to set a context to a coupon.

Second, and more important, setting the context for an engine would be a mutating operation. Leaving it to the instrument during calculations would execute it at some point during the call to its NPV method, which is supposed to be const. This would make it way too easy to trigger a race condition; for instance with a harmless-looking operation such as using the same discount curve for two instruments and evaluating them at different dates. A user with a minimum of experience in parallel programming wouldn't dream of, say, relinking the same handle in two concurrent threads; but when the mutation is hidden inside a const method, she might not be aware of it. (But wait, you say. Aren't there other mutating operations possibly being done during the call to NPV? Good catch: see the aside at the end of this post.)

So it seems that we have to set up the context before starting the calculation. This rules out driving the whole thing from the instrument (because, again, we would be hiding the fact that setting a context to an instrument could undo the work done by another that shared a term structure with the first) and suggests that we'd have to set the context explicitly on the several term structures. On the plus side, we no longer run the risk of a race in which we unknowingly try to set the same context to the same object. The drawbacks are that our setup just got more complex, and that we'd have to duplicate curves if we want to use them concurrently in different contexts: two parallel calculations on different dates would mean, for instance, two copies of the overnight curve for discounting. And if we have to do this, we might as well manage with per-thread singletons.

Finally, I'm skipping over the scenario in which the context is passed but not saved. It would lead to method calls like
    termStructure->discount(t, context);
which would completely break caching, would cause discomfort to all parties involved, and if we wanted stuff like this we'd write in Haskell.

To summarize: I hate to close the section on a gloomy note, but all is not well. The global settings are a limitation, but I don't have a solution; and what's worse, the possible changes increase complexity. We would not only tell a first-time user looking for the Black-Scholes formula that she needs term structures, quotes, an instrument and an engine: we'd also put contexts in the mix. A little help here?

Aside: more mutations than in a B-movie.

Unfortunately, there are already a number of things that change during a call to the supposedly const method Instrument::NPV.

To begin with, there are the arguments and results structures inside the engine, which are read and written during calculation and thus prevent the same engine to be used concurrently for different instruments. This might be fixed by adding a lock to the engine (which would serialize the calculations) or by changing the interface so that the engine's calculate method takes the arguments structure as a parameter and returns the results structure.

Then, there are the mutable data members of the instrument itself, which are written at the end of the calculation. Whether this is a problem depends on the kind of calculations one's doing. I suppose that calculating the value of the instrument twice in concurrent threads might just result in the same values being written twice.

The last one that comes to mind is a hidden mutation, and it's probably the most dangerous. Trying to use a term structure during the calculation might trigger its bootstrap, and two concurrent ones would trash each other's calculations. Due to the recursive nature of the bootstrap, I'm not even sure how we could add a lock around it. So if you do decide to perform concurrent calculations (being careful, setting up everything beforehand and using the same evaluation date) be sure to trigger a full bootstrap of your curves before starting.

Liked this post? Share it:

Monday, January 19, 2015

Quants Hub workshop available

Welcome back, and happy new year.

Just a short post with some news and self-promotion. The holiday season* didn't just bring a new QuantLib blog from Peter Caspers—whom you want to follow, trust me on this one—but also the publication online of the workshop I recorded for Quants Hub last October. It's now available for purchase from the Quants Hub site, under the title "A Look at QuantLib Usage and Development". It may be an option for those of you that can't attend my courses in London (because there's an ocean in the middle, for instance).

But I think I'll let the explanations to the guy below (he seems to know what he's talking about, even though he's got a funny accent). Click on the image to open the workshop page, read a description of the contents, and see the first 20 minutes or so of the recording.

* As to the actual bearer of these gifts, there are different opinions. If you asked around in Italy, the answer would be Santa or the baby Jesus or St. Lucia, depending on the region.

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Liked this post? Share it:

Monday, December 15, 2014

Odds and ends: indexes

Greetings, everybody.

Ok, I'll make it quick.

First of all: all the slides from the Düsseldorf user meeting are already available on the QuantLib site. Go get 'em. If you want some introduction, my previous post might help.

Then: this week I'm posting some content from the book appendix, namely, an overview of indexes.

Finally: the holiday season is coming.

It's likely that I won't be posting next week, so let me wish a merry Christmas to those who, like my family, celebrate it, a happy holiday to those who celebrate something else, and some holiday cheer to those who don't (but hey, you're missing out, people). I'll see you here after the festivities.

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Odds and ends: indexes

Like other classes such as Instrument and TermStructure, the Index class is a pretty wide umbrella: it covers concepts such as interest-rate indexes, inflation indexes, stock indexes—you get the drift.

Needless to say, the modeled entities are diverse enough that the Index class has very little interface to call its own. As shown in the listing below, all its methods have to do with index fixings. The isValidFixingDate method tells us whether a fixing was (or will be made) on a given date; the fixingCalendar method returns the calendar used to determine the valid dates; and the fixing method retrieves a fixing for a past date or forecasts one for a future date. The remaining methods deal specifically with past fixings: the name method, which returns an identifier that must be unique for each index, is used to index (pun not intended) into a map of stored fixings; the addFixing method stores a fixing (or many, in other overloads not shown here); and the clearFixing method clears all stored fixings for the given index.

Listing: interface of the Index class.
    class Index : public Observable {
        virtual ~Index() {}
        virtual std::string name() const = 0;
        virtual Calendar fixingCalendar() const = 0;
        virtual bool isValidFixingDate(const Date& fixingDate) const = 0;
        virtual Real fixing(const Date& fixingDate,
                            bool forecastTodaysFixing = false) const = 0;
        virtual void addFixing(const Date& fixingDate,
                               Real fixing,
                               bool forceOverwrite = false);
        void clearFixings();

Why the map, and where is it in the Index class? Well, we started from the requirement that past fixings should be shared rather than per-instance; if one stored, say, the 6-months Euribor fixing for a date, we wanted the fixing to be visible to all instances of the same index, and not just the particular one whose addFixing method we called. (Note that by "instances of the same index" I mean here instances of the same specific index, not of the same class, which might group different indexes; for instance, USDLibor(3*Months) and USDLibor(6*Months) are not instances of the same index; two different USDLibor(3*Months) are.) This was done by defining and using an IndexManager singleton behind the curtains. Smelly? Sure, as all singletons. An alternative might have been to define static class variables in each derived class to store the fixings; but that would have forced us to duplicate them in each derived class with no real advantage (it would be as much against concurrency as the singleton). In any case, this is one of the things we'll have to rethink in the next big QuantLib revision, in which we'll have to tackle concurrency. If these past years are any indication, we might expect it around 2020. No, just kidding. Maybe.

Since the returned index fixings might change (either because their forecast values depend on other varying objects, or because a newly available fixing is added and replaces a forecast) the Index class inherits from Observable so that instruments can register with its instances and be notified of such changes.

At this time, Index doesn't inherit from Observer, although its derived classes do (not surprisingly, since forecast fixings will almost always depend on some observable market quote). This was not an explicit design choice, but rather an artifact of the evolution of the code and might change in future releases. However, even if we were to inherit Index from Observer, we would still be forced to have some code duplication in derived classes, for a reason which is probably worth describing in more detail.

I already mentioned that fixings can change for two reasons. One is that the index depends on other observables to forecast its fixings; in this case, it simply registers with them (this is done in each derived class, as each class has different observables). The other reason is that a new fixing might be made available, and that's more tricky to handle. The fixing is stored by a call to addFixing on a particular index instance, so it seems like no external notification would be necessary, and that the index can just call the notifyObservers method to notify its observers; but that's not the case. As I said, the fixings is shared; if we store today's 3-months Euribor fixing, it will be available to all instances of such index, and thus we want all of them to be aware of the change. Moreover, instruments and curves might have registered with any of those Index instances, so all of them must send in turn a notification.

The solution is to have all instances of the same index communicate by means of a shared object; namely, we used the same IndexManager singleton that stores all index fixings. As I said, IndexManager maps unique index tags to sets of fixings; also, by making the sets instances of the ObservableValue class, it provides the means to register and receive notification when one or more fixings are added for a specific tag (this class will be described in a later post. You don't need the details here).

All pieces are now in place. Upon construction, any Index instance will ask IndexManager for the shared observable corresponding to the tag returned by its name method. When we call addFixings on, say, some particular 6-months Euribor index, the fixing will be stored into IndexManager; the observable will send a notification to all 6-months Euribor indexes alive at that time; and all will be well with the world.

However, C++ still throws a small wrench in our gears. Given the above, it would be tempting to call
in the Index constructor and be done with it. However, it wouldn't work; for the reason that in the constructor of the base class, the call to the virtual method name wouldn't be polymorphic. (If you're not familiar with the darker corners of C++: when the constructor of a base class is executed, any data members defined in derived classes are not yet built. Since any behavior specific to the derived class is likely to depend on such yet-not-existing data, C++ bails out and uses the base-class implementation of any virtual method called in the base-class constructor body.) From here stems the code duplication I mentioned a few paragraphs earlier; in order to work, the above method call must be added to the constructor of each derived index class. The Index class itself doesn't have a constructor (apart from the default one that the compiler provides).

As an example of a concrete class derived from Index, the listing below sketches the InterestRateIndex class.

Listing: sketch of the InterestRateIndex class.
    class InterestRateIndex : public Index, public Observer {
        InterestRateIndex(const std::string& familyName,
                          const Period& tenor,
                          Natural settlementDays,
                          const Currency& currency,
                          const Calendar& fixingCalendar,
                          const DayCounter& dayCounter);
        : familyName_(familyName), tenor_(tenor), ... {

        std::string name() const;
        Calendar fixingCalendar() const;
        bool isValidFixingDate(const Date& fixingDate) const {
            return fixingCalendar().isBusinessDay(fixingDate);
        Rate fixing(const Date& fixingDate,
                    bool forecastTodaysFixing = false) const;
        void update() { notifyObservers(); }

        std::string familyName() const;
        Period tenor() const;
        ... // other inspectors

        Date fixingDate(const Date& valueDate) const;
        virtual Date valueDate(const Date& fixingDate) const;
        virtual Date maturityDate(const Date& valueDate) const = 0;
        virtual Rate forecastFixing(const Date& fixingDate) const = 0;
        std::string familyName_;
        Period tenor_;
        Natural fixingDays_;
        Calendar fixingCalendar_;
        Currency currency_;
        DayCounter dayCounter_;
As you might expect, such class defines a good deal of specific behavior besides that inherited from Index. To begin with, it inherits from Observer, too, since Index doesn't. The InterestRateIndex constructor takes the data needed to specify the index: a family name, as in "Euribor", common to different indexes of the same family such as, say, 3-months and 6-months Euribor; a tenor that specifies a particular index in the family; and additional information such as the number of settlement days, the index currency, the fixing calendar, and the day-count convention used for accrual.

The passed data are, of course, copied into the corresponding data members; then the index registers with a couple of observables. The first is the global evaluation date; this is needed because, as I'll explain shortly, there's a bit of date-specific behavior in the class that is triggered when an instance is asked for today's fixing. The second observable is the one which is contained inside IndexManager and provides notifications when new fixings are stored. We can identify this observable here: the InterestRateIndex class has all the information needed to determine the index, so it can implement the name method and call it. However, this also means that classes deriving from InterestRateIndex must not override name; since the overridden method would not be called in the body of this constructor, they would register with the wrong notifier. Unfortunately, this can't be enforced in C++, which doesn't have a keyword like final in Java or sealed in C#; but the alternative would be to require that all classes derived from InterestRateIndex register with IndexManager, which is equally not enforceable, probably more error-prone, and certainly less convenient.

The other methods defined in InterestRateIndex have different purposes. A few implement the required Index and Observer interfaces; the simplest are update, which simply forwards any notification, fixingCalendar, which returns a copy of the stored calendar instance, and isValidFixingDate, which checks the date against the fixing calendar.
    std::string InterestRateIndex::name() const {
        std::ostringstream out;
        out << familyName_;
        if (tenor_ == 1*Days) {
            if (fixingDays_==0) out << "ON";
            else if (fixingDays_==1) out << "TN";
            else if (fixingDays_==2) out << "SN";
            else out << io::short_period(tenor_);
        } else {
            out << io::short_period(tenor_);
        out << " " <<;
        return out.str();

    Rate InterestRateIndex::fixing(
                           const Date& d,
                           bool forecastTodaysFixing) const {
        QL_REQUIRE(isValidFixingDate(d), ...);
        Date today = Settings::instance().evaluationDate();
        if (d < today) {
            Rate pastFixing =
            QL_REQUIRE(pastFixing != Null<Real>(), ...);
            return pastFixing;
        if (d == today && !forecastTodaysFixing) {
            Rate pastFixing = ...;
            if (pastFixing != Null<Real>())
                return pastFixing;
        return forecastFixing(d);

    Date InterestRateIndex::valueDate(const Date& d) const {
        QL_REQUIRE(isValidFixingDate(d) ...);
        return fixingCalendar().advance(d, fixingDays_, Days);
The name method is a bit more complicated. It stitches together the family name, a short representation of the tenor, and the day-count convention to get an index name such as "Euribor 6M Act/360" or "USD Libor 3M Act/360"; special tenors such as overnight, tomorrow-next and spot-next are detected so that the corresponding acronyms are used.

The fixing method contains the most logic. First, the required fixing date is checked and an exception is raised if no fixing was supposed to take place on it. Then, the fixing date is checked against today's date. If the fixing was in the past, it must be among those stored in the IndexManager singleton; if not, an exception is raised since there's no way we can forecast a past fixing. If today's fixing was requested, the index first tries looking for the fixing in the IndexManager and returns it if found; otherwise, the fixing is not yet available. In this case, as well as for a fixing date in the future, the index forecasts the value of the fixing; this is done by calling the forecastFixing method, which is declared as purely virtual in this class and implemented in derived ones. The logic in the fixing method is also the reason why, as I mentioned, the index registers with the evaluation date; the behavior of the index depends on the value of today's date, so it need to be notified when it changes.

Finally, the InterestRateIndex class defines other methods that are not inherited from Index. Most of them are inspectors that return stored data such as the family name or the tenor; a few others deal with date calculations. The valueDate method takes a fixing date and returns the starting date for the instrument that underlies the rate (for instance, the deposit underlying a LIBOR, which for most currencies starts two business days after the fixing date); the maturityDate method takes a value date and returns the maturity of the underlying instrument (e.g., the maturity of the deposit); and the fixingDate method is the inverse of valueDate, taking a value date and returning the corresponding fixing date. Some of these methods are virtual, so that their behavior can be overridden; for instance, while the default behavior for valueDate is to advance the given number of fixing days on the given calendar, LIBOR index mandates first to advance on the London calendar, then to adjust the resulting date on the calendar corresponding to the index currency. For some reason, fixingDate is not virtual; this is probably an oversight that should be fixed in a future release.

Aside: how much generalization?

Some of the methods of the InterestRateIndex class were evidently designed with LIBOR in mind, since that was the first index of that kind implemented in the library. On the one hand, this makes the class less generic than one would like: for instance, if we were to decide that the 5-10 years swap-rate spread were to be considered an interest-rate index in its own right, we would be hard-pressed to fit it to the interface of the base class and its single tenor method. But on the other hand, it is seldom wise to generalize an interface without having a couple of examples of classes that should implement it; and a spread between two indexes (being just that; a spread, not an index) is probably not one such class.

Liked this post? Share it:

Tuesday, December 9, 2014

Report from the QuantLib user meeting in Düsseldorf

Welcome back.

This last Thursday and Friday I was in Düsseldorf for the second QuantLib user meeting.

Man, was it good.

It was two days of great talks, with a good mixture of technical and financial content (and by the way, the slides are being collected and some are already available on the QuantLib page for the meeting). Thanks go to IKB, that sponsored the event and provided the venue, and especially to Michael von der Driesch and Peter Caspers, who organized the meeting and kept it running smoothly. I'm looking forward to next year. Really, we should have more of these events around Europe.

I wasn't giving a talk this year, so I just relaxed and enjoyed the show. It started with the keynote of Ferdinando Ametrano (@Ferdinando1970) on open-source finance: QuantLib, OpenGamma and Bitcoin, with the latter being the success story and having the lion's share in the presentation. (If you want to read Ferdinando's papers on Bitcoin, they're here and here). One thing stuck with me among those Ferdinando said about QuantLib: it isn't nearly as used in academia as we would like. If you teach in a university, let me know if there's anything I can do to help with this.

The second talk was by Roland Lichters, which told us of how speed is paramount in the CVA application he and his team at Quaternion develop. They fine-tuned QuantLib until they could price a swap on a given scenario in 30 microseconds (which I thought quite impressive) with a full analysis in about 30 seconds, but Bermudan swaptions were much slower; a full analysis would take some 50 minutes. Taking inspiration from the Longstaff-Schwartz method for American Monte Carlo, they now run an initial simulation to calculate swaption prices as a regression function. This initial time investment allows them to save time during the analysis, bringing its time back to the order of seconds.

In the last talk of the morning, Matthias Groncki presented the work he and Michael von der Driesch did at IKB on ABS. They wanted to make these instruments easier to simulate and price, and they knew that QuantLib could help since it had the basic pieces of the puzzle. Based on those, they wrote an implementation of the instrument in C++ and exposed it to Python. This allowed them to create an easier interface through IPython notebooks, providing graphs as well as numerical results as an aid to understanding.

After lunch, we restarted with Dirk Eddelbuettel (@eddelbuettel).  Let me add a personal note here: Dirk has been helping with the project and packaging the Debian version of QuantLib almost since day one, and we never had the chance to meet in person before. I was delighted we could do it this time.
Dirk gave us a description of his initial work on exporting QuantLib to R, and how this ultimately led to the development of Rcpp which is now used by more than 300 CRAN packages (or about 5% of the total). Other cool tools shown in his talk: Shiny and RMarkdown, which can use R packages (including RQuantLib) to provide interactive web-based reports. One thing I noticed is that most of the problems the RQuantLib package seems to have are shared with the C++ library, or rather caused by it: singletons, no time component in dates, no simple example for textbook calculations such as Black-Scholes. Eventually, we'll have to do something about it.

Next, Sebastian Schlenkrich on the hot topic of this meeting: the modeling of the basic spread between Libor and funding curves (that is, either the OIS curve or possibly a cross-currency curve for deals collateralized in another currency). I won't go into the details, which are in his (and André Miemiec's) paper at SSRN. I'll note, though, that his talk was the one with the most lively discussion at the end, with Sebastian, Daniel Duffy, Ferdinando and myself going over what could be the right design for including his results into QuantLib. No clear winner emerged yet, but the interest in the topic makes me guess that we'll work on it.

The final talk of the day was from Peter Caspers, who described some of his several contributions to QuantLib during the past year. The list is impressive, covering no-arbitrage SABR; ZABR and SVI interpolations; TSR CMS coupon pricers; CMS-spread coupon pricers; Credit Risk+ model; Gaussian 1D models; simulated annealing optimizer; Runge-Kutta ODE solver; and dynamically created Mersenne-Twister RNGs. With a gentle metaphorical nudge in my ribs, Peter noticed that most of them are in the experimental folder. I agree; we need some kind of triage process to look at the contents of that folder and move them in the core library. I'll explore some ideas after next release.

And with the end of this talk (also immortalized by Dirk on Twitter) we were off to dinner.

And there was evening and there was morning.

The second day started with a talk by Daniel Duffy, who described the latest iteration of his PDE and FDM framework. He made a number of interesting points. He told how, in a mathematical domain such as this, functional programming and generics are more suited to the task than object-oriented programming; and how C++11/14 made this style of programming easier with type inference (auto), lambda functions, and generic function objects (std::function). Using loosely coupled functions, instead of class interfaces, made it possible to separate clearly the different layers of the framework (PDEs, FDM, interface, and so on). Daniel's code might get into QuantLib at some point (the main problem being that we're still supporting older compilers that don't implement C++11) but I've also been talking Daniel into releasing his code as a project on its own. We'll see.

Next, Paolo Mazzocchi, who's been working with Ferdinando on modeling basis spreads. In discount-based legacy systems, synthetic deposits are required for maturities shorter than the Libor tenor. Their approach was to parameterize the spread between Libor and funding curve in that range and fit the parameters to the existing market quotes. The details are in the slides (already available): expect a paper soon.

The last talk of Friday morning was by Bernd Lewerenz, on the subject of a new pricing engine he contributed for Asian options based on a model by Jan Večeř (and that, serendipitously, I merged in the main repository just days before the meeting). The engine makes it possible to efficiently price arithmetic-average Asian options, widely used in commodity markets. Also, Bernd told us he's been driving the thing by means of the QuantLib Perl bindings, which makes this their first documented use.

Starting the afternoon talks: Eric Ehlers and his Reposit project. It is a rewrite of his gensrc generator for the QuantLib Excel bindings, it is implemented as a SWIG module, has a web site, and is a work in progress. Eric's talk had the merit of sparking two developments: it attracted some interest in rekindling the QuantLib Calc addin, and made me think that this is probably the time to check SWIG's support for shared_ptr and see if we can simplify our SWIG interfaces.

Next: a joint presentation by Klaus Spanderen and Johannes Göttker-Schnetmann on their quest for a calibrated local volatility. They are pretty well along it (in fact, so much that they changed he title of their talk to be a lot more optimistic than when they proposed it). Not only the details are in their presentation (and I wouldn't do them justice, so go read the slides), but their code is on GitHub, too.

The final talk was from André Miemiec, talking of an open field of research: the arbitrage-free and consistent modeling of swaptions, CMS and CMS spreads. He's been building on QuantLib to price CMS spread options. A simple extension of the existing code gave him a correct implementation on the first try; but there's still work to be done on speed before it can be used in a production setting. It was nice to see the library help getting a working prototype quickly, though.

And with this, we got to the end. All the comments I heard were enthusiastic (and mine, too).  As I said above: definitely something that should be replicated somewhere else.

Thanks again to the sponsor, the organizers, the speakers and all those who attended. I hope I'll see you again next year.

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Liked this post? Share it:

Monday, November 17, 2014

Odds and ends: date calculations

Welcome back.

My blog schedule continues to be erratic, I know. But November is traditionally the month when writers get all motivated, so I might be working on some new book content (no, my book, not a novel). In the meantime, this post contains a few sections I had already published in the PDF version of the drafts, somewhat reworked to include some new information.

In other news, the QuantLib User Meeting 2014 is drawing near. I won't be giving a talk like I did last year, but I'm looking forward to be there anyway. I'll report on the talks in a future post.

Finally: as you might know if you are subscribed to the developers mailing list, it turns out that QuantLib 1.4 doesn't work with Clang 3.5 and the newly-released Boost 1.57. I'll be putting out a 1.4.1 release to fix the problem; as you read this, it might already be available from our download page. If not, try again in a day or two (but only if you're using Clang: if not, you don't need to upgrade).

Follow me on Twitter if you want to be notified of new posts, or add me to your circles, or subscribe via RSS: the widgets for that are in the sidebar, at the top right of the page. Also, make sure to check my Training page.

Odds and ends: date calculations

Date calculations are among the basic tools of quantitative finance. As can be expected, QuantLib provides a number of facilities for this task; I briefly describe some of them in the following subsections.

Dates and periods

An instance of the Date class represents a specific day such as November 15th, 2014—today's date as I write this post. This class provides a number of methods for retrieving basic information such as the weekday, the day of the month, or the year; static information such as the minimum and maximum date allowed (at this time, January 1st, 1901 and December 31st, 2199, respectively) or whether or not a given year is a leap year; or other information such as a date's Excel-compatible serial number or whether or not a given date is the last date of the month. The complete list of available methods and their interface is documented in the reference manual. No time information is included (although we've been talking about this).

Capitalizing on C++ features, the Date class also overloads a number of operators so that date algebra can be written in a natural way; for example, one can write expressions such as ++d, which advances the date d by one day; d + 2, which yields the date two days after the given date; d2 - d1, which yields the number of days between the two dates; d - 3*Weeks, which yields the date three weeks before the given date (and incidentally, features a member of the available TimeUnit enumeration, the other members being Days, Months, and Years); or d1 < d2, which yields true if the first date is earlier than the second one. The algebra implemented in the Date class works on calendar days; neither bank holidays nor business-day conventions are taken into account.

The Period class models lengths of time such as two days, three weeks, or five years by storing a TimeUnit and an integer. It provides a limited algebra and a partial ordering. For the non mathematically inclined, this means that two Period instances might or might not be compared to see which is the shorter; while it is clear that, say, 11 months are less than one year, it is not possible to determine whether 60 days are more or less than two months without knowing which two months. When the comparison cannot be decided, an exception is thrown.

And of course, even when the comparison seems obvious, we managed to sneak in a few surprises. For instance, the comparison
    Period(7,Days) == Period(1,Weeks)
returns true. It seems correct, right? Hold that thought.


Holidays and business days are the domain of the Calendar class. Several derived classes exist which define holidays for a number of markets; the base class defines simple methods for determining whether or not a date corresponds to a holiday or a business day, as well as more complex ones for performing tasks such as adjusting a holiday to the nearest business day (where "nearest" can be defined according to a number of business-day conventions, listed in the BusinessDayConvention enumeration) or advancing a date by a given period or number of business days.

It might be interesting to see how the behavior of a calendar changes depending on the market it describes. One way would have been to store in the Calendar instance the list of holidays for the corresponding market; however, for maintainability we wanted to code the actual calendar rules (such as "the fourth Thursday in November" or "December 25th of every year") rather than enumerating the resulting dates for a couple of centuries. Another obvious way would have been to use polymorphism and the Template Method pattern; derived calendars would override the isBusinessDay method, from which all others could be implemented. This is fine, but it has the shortcoming that calendars would need to be passed and stored in shared_ptrs. The class is conceptually simple, though, and is used frequently enough that we wanted users to instantiate it and pass it around more easily—that is, without the added verbosity of dynamic allocation.

The final solution was the one shown in the listing below.
    class Calendar {
        class Impl {
            virtual ~Impl() {}
            virtual bool isBusinessDay(const Date&) const = 0;
        boost::shared_ptr<Impl> impl_;
        bool isBusinessDay(const Date& d) const {
            return impl_->isBusinessDay(d);
        bool isHoliday(const Date& d) const {
            return !isBusinessDay(d);
        Date adjust(const Date& d,
                    BusinessDayConvention c = Following) const {
            // uses isBusinessDay() plus some logic
        Date advance(const Date& d,
                     const Period& period,
                     BusinessDayConvention c = Following,
                     bool endOfMonth = false) const {
            // uses isBusinessDay() and possibly adjust()
        // more methods
It is a variation of the pimpl idiom, also reminiscent of the Strategy or Bridge patterns; these days, the cool kids might call it type erasure, too. Long story short: Calendar declares a polymorphic inner class Impl to which the implementation of the business-day rules is delegated and stores a pointer to one of its instances. The non-virtual isBusinessDay method of the Calendar class forwards to the corresponding method in Calendar::Impl; following somewhat the Template Method pattern, the other Calendar methods are also non-virtual and implemented (directly or indirectly) in terms of isBusinessDay. (The same technique is used in a number of other classes, such as DayCounter in the next section or Parameter from this post.)

Derived calendar classes can provide specialized behavior by defining an inner class derived from Calendar::Impl; their constructor will create a shared pointer to an Impl instance and store it in the impl_ data member of the base class. The resulting calendar can be safely copied by any class that need to store a Calendar instance; even when sliced, it will maintain the correct behavior thanks to the contained pointer to the polymorphic Impl class. Finally, we can note that instances of the same derived calendar class can share the same Impl instance. This can be seen as an implementation of the Flyweight pattern—bringing the grand total to about two and a half patterns for one deceptively simple class.

Enough with the implementation of Calendar, and back to its behavior. Here's the surprise I mentioned in the previous section. Remember Period(1,Weeks) being equal to Period(7,Days)? Except that for the advance method of a calendar, 7 days means 7 business days. Thus, we have a situation in which two periods p1 and p2 are equal (that is, p1 == p2 returns true) but calendar.advance(p1) differs from calendar.advance(p2).

Yay, us.

I'm not sure I have a good idea for a solution here. If we want backwards compatibility, the current uses of Days must keep working in the same way; so it's not possible, say, to start interpreting calendar.advance(7, Days) as 7 calendar days. One way out might be to keep the current situation, introduce two new enumeration cases BusinessDays and CalendarDays that remove the ambiguity, and deprecate Days. Another is to just remove the inconsistency by dictating that a 7-days period do not, in fact, equal one week; I'm not overly happy about this one.

If we give up on backwards compatibility (the legendary QuantLib 2.0) then there are more possibilities. One is to always use Days as calendar days and add BusinessDays as a different enumeration case. Another, which I'm liking more and more as I think about it, would be to always use Days as calendar days and add a specific method advanceBusinessDays to Calendar (or maybe an overload advance(n, BusinessDays), with BusinessDays being an instance of a separate class); however, this would mean that 3 business days wouldn't be a period.

As I said, no obvious solution. If you have any other suggestions, I'm all ears.

Day-count conventions

The DayCounter class provides the means to calculate the distance between two dates, either as a number of days or a fraction of an year, according to different conventions. Derived classes such as Actual360 or Thirty360 exist; they implement polymorphic behavior by means of the same technique used by the Calendar class and described in the previous section.

Unfortunately, the interface has a bit of a rough edge. Instead of just taking two dates, the yearFraction method is declared as
    Time yearFraction(const Date&,
                      const Date&,
                      const Date& refPeriodStart = Date(),
                      const Date& refPeriodEnd = Date()) const;
The two optional dates are required by one specific day-count convention (namely, the ISMA actual/actual convention) that requires a reference period to be specified besides the two input dates. To keep a common interface, we had to add the two additional dates to the signature of the method for all day counters (most of which happily ignore them). This is not the only mischief caused by this day counter; you'll see another in the next section.


The Schedule class, shown in the listing below, is used to generate sequences of coupon dates.
    class Schedule {
        Schedule(const Date& effectiveDate,
                 const Date& termination Date,
                 const Period& tenor,
                 const Calendar& calendar,
                 BusinessDayConvention convention,
                 BusinessDayConvention terminationDateConvention,
                 DateGeneration::Rule rule,
                 bool endOfMonth,
                 const Date& firstDate = Date(),
                 const Date& nextToLastDate = Date());
        Schedule(const std::vector<Date>&,
                 const Calendar& calendar = NullCalendar(),
                 BusinessDayConvention convention = Unadjusted);

        Size size() const;
        bool empty() const;
        const Date& operator[](Size i) const;
        const Date& at(Size i) const;
        const_iterator begin() const;
        const_iterator end() const;

        const Calendar& calendar() const;
        const Period& tenor() const;
        bool isRegular(Size i) const;
        Date previousDate(const Date& refDate) const;
        Date nextDate(const Date& refDate) const;
        ... // other inspectors and utilities
Following practice and ISDA conventions, it has to accept a lot of parameters; you can see them as the argument list of its constructor. (Oh, and you'll forgive me if I don't go and explain all of them. I'm sure you can guess what they mean.) They're probably too many, which is why the library uses the Named Parameter Idiom (already described in this post) to provide a less unwieldy factory class. With its help, a schedule can be instantiated as
    Schedule s = MakeSchedule().from(startDate).to(endDate)
Other methods include on the one hand, inspectors for the stored data; and on the other hand, methods to give the class a sequence interface, e.g., size, operator[], begin, and end.

The Schedule class has a second constructor, taking a precomputed vector of dates. It's only kind of working, though: the resulting Schedule instances simply don't have some of the data that their inspectors are supposed to return, so those methods will throw an exception if called. Among those, there are tenor and isRegular, about which I need to spend a couple of words.

First of all, isRegular(i) doesn't refer to the i-th date, but to the i-th interval; that is, the one between the i-th and (i+1)-th dates. This said, what does "regular" means? When a schedule is built based on a tenor, most intervals correspond to the passed tenor (and thus are regular) but the first and last intervals might be shorter or longer depending on whether we passed an explicit first or next-to-last date. We might do this, e.g., when we want to specify a short first coupon.

If we build the schedule with a precomputed set of dates, we don't have the tenor information and we can't tell if a given interval is regular. (Well, we could use heuristics, but it could get ugly fast.) The bad news is, this makes it impossible to use that schedule to build a sequence of bond coupons; if we pass it to the constructor of, say, a fixed-rate bond, we'll get an exception. And why, oh, why does the bond needs the missing info in order to build the coupons? Because the day-count convention of the bond might be ISMA actual/actual, which needs a reference period; and in order to calculate the reference period, we need to know the coupon tenor.

Fortunately, it shouldn't be difficult to fix this problem. One way would be to check the day-count convention, and only try to calculate the reference period when needed; this way the constructor would still raise an exception for ISMA actual/actual, but would succeed for all other conventions. Another way might be to add the tenor and regularity information to the schedule, so that the corresponding methods can work; but I'm not sure that this makes a lot of sense.

Liked this post? Share it: