QuantLib: Events and the Evaluation Date

QuantLib implements a mechanism for handling events which occur on specific dates. Examples of events could be cash flows or … The class Event represents a real life event is defined as an abstract base class from which a specific event type has to inherit. The public interface of Event is minimal. It defines an abstract method

virtual Date date() const = 0;

This method needs to be implemented by a derived class to return the date on which the event occurs. The other event related method is hasOccured()

virtual bool hasOccured(
    const Date& refDate() = Date(),
    boost::optional includeRefDate = boost::none)
        const;

This method returns true if the event has already occured on the reference date. The reference date is an optional argument passed to the method. If the reference date is not specified, or if an empty date object is passed, the reference date is obtained by querying the global settings. By default this will return the current date. Changing the global settings’ reference date will be discussed below.

The second argument, includeRefDate, is also optional and specifies whether an event that occurs on the reference date should be treated as occured or not. If set to true, an event will not have occured on the reference date, i.e. the method will return false if the event’s date is the same as the reference date. If includeRefDate is set to false the the method returns true if the event’s date is the same as the reference date.

If includeRefDate is not specified, then the value from the global settings will be used. Note how the method does not specify a default value for includeRefDate but uses the boost::optional template. This template will be discussed in another post.

In addition to the two methods above, Event defines a method to accept an AcyclicVisitor

virtual void accept(AcyclicVisitor&);

In this post I will not go into the details of the visitor design pattern, or how it is implemented in QuantLib. This will be the topic of another post.

Global Reference Date

The value of the global reference date can be changed through the Settings class. The Settings class is a singleton which stores a number of global settings. The singleton’s instance is accessed through the static instance method.

The reference date can be accessed through the evaluationDate() method.

DateProxy& evaluationDate();
const DateProxy& evaluationDate() const;

The date can be read and written through this method. For all purposes the private DateProxy can be treated as a Date class because of the typecast operator. The reason that a DateProxy is returned is because this class inherits from ObservableValue and can be used by observer classes. The details of obsavles and observers will be talked about in another post.

If the reference date has not been set to a specific date, then evaluationDate() will return the current date as given by the computer’s clock. This means that, as time progresses, the value of the date returned by evaluationDate() can change at midnight. In order to keep the date from changing and fix it at the current date the method anchorEvaluationDate() can be called.

The following call

Settings::instance().anchorEvaluationDate();

is equivalent to calling

Settings::instance().evaluationDate() =
  Date::todaysDate();

The function resetEvaluationDate() set the reference date to today’s date and allows it to change again at midnight as time progresses.

The following call

Settings::instance().resetEvaluationDate();

is equivalent to calling

Settings::instance().evaluationDate() = Date();

Settings also defines a method includeReferenceDateEvents(). This allows the user to influence the default behaviour of Event objects. The flag can be read and written using this method.

bool flag=Settings::instance().includeReferenceDateEvents();

Settings::instance().includeReferenceDateEvents() = true;

The Settings singleton has other methods relating to the default settings for other classes’ behaviours. These will be discussed in the respective posts concerned with these classes.